newt-core 0.8.0

//! The agentic loop — call model → execute tool calls → feed results back →
//! repeat — extracted verbatim from `newt-tui` in Step 9.7 so the same
//! battle-tested loop can serve both the TUI and the ACP worker (Step 9.8)
//! without being written twice.
//!
//! `ChatCtx` stays a **concrete** type: there is exactly one loop
//! implementation and no `InferenceBackend` trait (YAGNI per the roadmap —
//! revisit only when a second concrete backend exists). The only seam is
//! [`McpTools`], which breaks the `newt-core` ← `newt-mcp-client` dependency
//! cycle; see `mcp.rs`.

// pub(crate) since Step 18.5 (#247): the `Summarizing` memory provider
// delegates to this same pipeline instead of keeping a duplicate one.
// #727: read-only context-budget introspection (the `get_context_remaining`
// tool) — a pure renderer the agentic loop feeds per-turn budget state into.
mod attempt_capture;
mod budget;
pub mod digest_fold;
pub mod run_allowance;
// #867: path-claim verification for the cap-exit summary (the file-name
// sibling of the #717 phantom-tool-reach telemetry).
/// Anthropic `/v1/messages` wire mapping — `pub` so `newt-inference`'s simple
/// transport reuses the body builder/reply parser instead of duplicating them
/// (the `retry` re-export precedent; the dependency points inference → core).
pub mod anthropic_wire;
/// #1947: `claim_check`'s sibling for CAPABILITY claims — "verified",
/// "working end-to-end", a table of green checkmarks — bound against the
/// turn's `ToolEvent` ledger. Same append-never-rewrite shape.
mod capability_check;
mod claim_check;
mod final_reply;
pub(crate) mod observed_report;
use final_reply::FinalReply;
pub use observed_report::assistant_prose as model_reply_for_history;
mod selected_target;
mod semantic_pins;
pub use claim_check::{
    files_changed_between, is_workspace_repo_root, locate_workspace_repo, nested_current_paths,
    nested_files_changed_between, snapshot_nested_repos, snapshot_workspace,
    snapshot_workspace_subtree, NestedRepoSnapshot, StatusSnapshot, WorkspaceRepoLocation,
};
#[cfg(test)]
pub(crate) use observed_report::tests::model_explanation;
pub(crate) mod compress;
mod context_recovery;
mod crew_attest;
mod crew_tool;
pub(crate) mod cw_overflow;
mod display;
mod generation_bounds;
mod generation_policy;
mod generation_repetition;
mod output_budget;
mod output_limit_recovery;
pub use generation_policy::{
    preview_chat_generation, projected_cognition, validate_output_allowance, ChatGenerationPreview,
};
mod git_tool;
pub mod openai_sse;
pub(crate) mod publish_early;
pub(crate) mod self_verify;
pub use publish_early::GUIDANCE as REFACTOR_PUBLISH_GUIDANCE;
// Step 26.4 (#583): scratchpad structured-state — the `scratchpad` context feature.
pub(crate) mod scratchpad;
// Step 26.5 (#582): semantic repo-evidence retrieval (embedding RAG-for-code).
pub(crate) mod semantic;
// Step 26.6a (#585): experiential memory — the `experiential` context feature.
pub(crate) mod experiential;
// Step 26.6b (#586): scheduled per-step compiled view — the `scheduled` feature.
pub(crate) mod scheduled;
// Step 26.3 (#584): tool-output offloading — the `tool_offload` context feature.
/// Content-addressed spill identity (#1528 B3): a spill handle is the BLAKE3 CIDv1
/// of a versioned, session-scoped record. This is the sole spill/compaction store;
/// the old reservation/allocator store was deleted at cutover.
pub(crate) mod content_spill;
/// Drive an overseer-authored plan through a `CrewRunner` (#628 P2 execute side).
pub(crate) mod plan_exec;
// W0 (#1511, epic #1506): typed dispatch-error classification + per-round
// tool-call parse signals — the structural inputs of the observability
// contract `newt solve` emits for the external evaluator.
pub(crate) mod observability;
/// Recover tool calls a weak model emitted in CONTENT instead of the native
/// `tool_calls` field (the #1 weak-model failure — see the module docs).
pub(crate) mod tool_recovery;
// Issue #308 — the cowork foundation: a non-blocking turn driver around
// `chat_complete` (driver), a renderer-agnostic transcript render (transcript),
// and the redaction-gated ShellObservation seam (observation). All additive;
// they wrap/precede `chat_complete` and never touch its internals.
mod driver;
mod file_change_display;
pub use file_change_display::{file_change_style, write_file_change_row, FileChangePresentation};
#[cfg(feature = "markdown-syntect")]
mod syntax_foreground;
// Step 25.1 (#568): Markdown → ANSI rendering of assistant output. Behind the
// default `markdown` feature; a passthrough shim takes its place under
// --no-default-features so the headless wyvern strip carries no markdown deps.
#[cfg(feature = "markdown")]
mod markdown;
#[cfg(not(feature = "markdown"))]
mod markdown {
    //! Passthrough shim used when the `markdown` feature is disabled (the
    //! headless wyvern strip). Keeps `render_markdown` / `RenderOpts` /
    //! `MarkdownStreamWriter` in the public API with zero markdown
    //! dependencies; output is the source verbatim — identical to color-off
    //! behavior in the full renderer.
    use std::io::{self, Write};

    #[derive(Debug, Clone, Copy)]
    pub struct RenderOpts {
        pub color: bool,
        pub cols: usize,
    }
    pub fn render_markdown(src: &str, _opts: RenderOpts) -> String {
        src.to_string()
    }

    /// Raw passthrough writer — bytes through unchanged, with a trailing newline
    /// at `finish` if the stream didn't end with one (matching the raw token
    /// path's closing `println!`).
    pub struct MarkdownStreamWriter<W: Write> {
        out: W,
        wrote: bool,
        ended_nl: bool,
    }
    impl<W: Write> MarkdownStreamWriter<W> {
        pub fn new(out: W, _opts: RenderOpts) -> Self {
            Self {
                out,
                wrote: false,
                ended_nl: true,
            }
        }
        pub fn push(&mut self, delta: &str) -> io::Result<()> {
            if let Some(&last) = delta.as_bytes().last() {
                self.wrote = true;
                self.ended_nl = last == b'\n';
            }
            self.out.write_all(delta.as_bytes())
        }
        pub fn finish(&mut self) -> io::Result<()> {
            if self.wrote && !self.ended_nl {
                self.out.write_all(b"\n")?;
            }
            self.out.flush()
        }
        /// Give the sink back — see the full renderer's `into_inner`.
        pub fn into_inner(self) -> W {
            self.out
        }
    }
}
mod adjudicate;
mod artifact_hooks;
mod artifact_read;
mod disposition_voice;
mod mcp;
mod memory_fetch;
mod note_sink;
mod observation;
mod operating_mode;
mod permissions;
mod plan_mode;
pub mod smart_harness;
// PR5: deterministic prompt-comprehension intake owns the turn disposition,
// bounded clarification manifest, and content-free model projection.
mod prompt_intake;
mod prompt_read;
mod recall;
mod tool_args;
// #952/#1669: operator steering submitted mid-turn, drained at the next
// round boundary as a genuine operator message.
mod steering;
// #1004: the `render_report` tool — present collected findings as a rendered
// Markdown document in the plain scroller (the missing "present" affordance a
// doer-oriented gather-and-report task otherwise lacks).
mod report;
// #714: the `resume_context` tool — a self-scoped read of THIS conversation's
// own pre-interrupt work (the affordance `recall` structurally cannot be).
mod resume;
// #1528: pure Value↔Value bridge letting the Responses `input` shape reuse the
// chat-shaped `compress::compress` compactor on a context-window-400 recovery.
mod responses_compaction;
// #1528 B5: the ONE typed strict-wire validator — every Responses dispatch goes
// through `validate_responses_request` and `dispatch_responses_json` accepts only a
// `ValidatedResponsesRequest`, so a broken request cannot reach `POST /v1/responses`.
mod responses_wire_validation;
mod send_budget;
// FR-3 (#998): the grant-independent absolute deny-list — a fixed exec veto
// (ssh / rm / systemctl restart …) no capability, mode, or persona unlocks,
// classified STRUCTURALLY by exec target so a coach's runbook TEXT is untouched.
mod deny;
// facade P4 (#780): hidden tool-call routing — promote the model's read-only
// shell reaches (`cat`/`ls`/`find` + read-only `git`) to a silent rewrite onto
// the governed built-ins, gate the rest. The route/gate split is pure DATA.
mod routing;
// #725: the `tool_search` discovery tool — find a real tool by intent instead
// of fabricating a foreign name (the structural complement to the #716 alias
// seam + #717 phantom telemetry).
mod tool_search;
pub(crate) mod tools;
mod transcript;
mod trim;
// Scoped FR-14 (#1042): wrap a remote MCP tool's result as explicitly
// untrusted data before it re-enters context — an injection-guard framing,
// not a filter.
mod untrusted;
mod warmup;

pub use adjudicate::{adjudicate_decisions, AdjudicationFailure};
pub use artifact_hooks::{
    record_manual_compaction_checkpoint, record_memory_compaction_checkpoint,
    record_observed_head_transition, record_prompt_comprehension_manifest,
    record_retry_revert_file, record_turn_outcome,
};
pub use artifact_read::{
    artifact_read_tool_definition, ArtifactPage, ArtifactReadContext, ArtifactReadRecord,
    ArtifactSource, PromptArtifactSink, SessionArtifactStore, StoreArtifactStore,
};
pub use compress::{
    compress_user_initiated, compress_user_initiated_for_task, CompressCounters, CompressState,
    FloorTrend, ManualCompressOutcome, ManualCompressPolicy, SummarizeFn, SummarizeFuture,
    Summarizer, CONTINUATION_PREFIX, PLAN_APPROVAL_PREFIX, SUMMARY_END_MARKER, SUMMARY_PREFIX,
};
pub use content_spill::{
    SessionSpillStore, SpillCid, SpillCidError, SpillProvenance, SpillRecordV1, SpillScope,
    SpillStore,
};
pub use crew_attest::{crew_authz, crew_step_up_policy, CrewAuthz, Presence};
pub use crew_tool::{compose_roster_tool_definition, crew_tool_definition, CrewRunner};
pub use cw_overflow::{parse_context_window_error, recover_context_window_400};
pub use display::{
    fmt_token_gauge, fmt_tokens_compact, gauge_level, interactive_recovery, newt_line,
    print_harness_notice, print_list_item, print_newt, reply_cols, set_mouse_recovery,
    set_spill_lines, set_spill_summary, set_time_marker_secs, Fold, GaugeLevel, Hidden, Recovery,
    ThinkingFold, NEWT_ORANGE_CT, REPLY_MARKER,
};
pub use driver::{
    HeadlessCodeSearch, InstantiatedFeatures, TurnDriver, TurnDriverConfig, TurnDriverError,
    TurnOutcome, TurnStatus,
};
pub use experiential::{
    experience_block, ExperienceStore, SessionExperienceStore, EXPERIENCE_TOP_K,
};
pub use git_tool::{check_git_read_scope, git_tool_definition, GitTool};
pub use markdown::{render_markdown, MarkdownStreamWriter, RenderOpts};
pub use mcp::{
    classify_mcp_effect, leash_mcp_call, LeasedMcpCall, LeashDenied, McpEffect, McpGrant, McpTools,
    NoMcp,
};
pub use observability::{
    classify_reqwest, error_class, round_parse_signal, BehaviorSignal, DispatchError, Enforcement,
    ErrorClass, OutputAllowance, ParseSignal, SolveObservation, ToolCallDialect,
};
pub use plan_exec::{run_plan, run_plan_with_reground, NoReground, PlanRun, Reground};
pub use prompt_intake::{
    discussion_request, AdjudicationCandidate, AdjudicationRefusal, AdjudicationVerdict, AtomicAsk,
    ClarificationRejection, DecisionLock, DecisionSource, DecisionStatus, DispositionLexicon,
    DispositionSource, PromptComprehensionManifest, PromptDisposition, PromptIntake,
    MAX_ADJUDICATION_BATCH,
};
#[cfg(test)]
pub(crate) use prompt_read::response_repository_policy_tokens;
pub use prompt_read::{
    prompt_read_tool_definition, PromptReadContext, PromptSource, SessionPromptSource,
    SessionPromptStore, StorePromptSource,
};
pub use scheduled::{
    fresh_multi_step_plan, plan_block, plan_reseat_pointer, step_change_line, PlanSnapshot,
    SessionStepLedger, Step, StepLedger, StepStatus,
};
pub use scratchpad::{
    scratchpad_state_block, working_memory_head, ScratchpadStore, SessionScratchpadStore,
};
pub use self_verify::{
    enabled as self_verify_enabled, outcomes_enabled as verify_outcomes_requested,
    verification_gate_present, verification_receipt,
};
pub use semantic::{
    chunk_source, code_search_tool_definition, cosine, format_index_status, format_search_hits,
    format_search_model, format_search_preview, format_search_rejects, gather_code_files,
    gather_with_manifest, index_files, plan_gather, render_code_evidence, retrieve_evidence,
    retrieve_evidence_steered, retrieve_ranked, retrieve_ranked_with_cap, CodeChunk, CodeSearch,
    Cut, CutClass, Embedder, EmbeddingsClient, EvidenceKind, GatherCaps, GatherManifest,
    IndexStatus, RankedHit, RejectReason, RetrievalResult, RetrievalSteer, SemanticIndex,
    SessionSemanticIndex,
};

/// Align GFM table pipes in Markdown **source** (Step 25.5, #568) — plain text,
/// no ANSI. The headless **wyvern** tier keeps Markdown as source (no rendering),
/// so this tidies ragged pipe tables for transcripts other agents read. It is
/// **independent of the `markdown` feature** (wyvern builds `--no-default-features`)
/// and gated on the optional `markdown-table-formatter` feature: identity unless
/// enabled, so it never pulls comrak/wasm-bindgen into a default build.
#[cfg(feature = "markdown-table-formatter")]
// INERT-CODE-RATCHET: X26 DELETE: markdown table tidy function has only test and documentation consumers.
pub fn tidy_markdown_tables(src: &str) -> String {
    markdown_table_formatter::format_tables(src)
}

/// Identity passthrough when the `markdown-table-formatter` feature is off.
#[cfg(not(feature = "markdown-table-formatter"))]
pub fn tidy_markdown_tables(src: &str) -> String {
    src.to_string()
}

#[cfg(test)]
#[path = "mod_tests/tidy_tables_tests.rs"]
mod tidy_tables_tests;
pub use budget::get_context_remaining_tool_definition;
pub(crate) use disposition_voice::DispositionVoices;
pub use memory_fetch::{
    memory_fetch_tool_definition, MemAddr, MemPayload, MemorySource, StoreMemorySource,
};
pub use note_sink::{save_note_tool_definition, NoteNudge, NoteSink};
pub use observation::{ShellObservation, SHELL_OBSERVATION_PREFIX};
pub use operating_mode::{select_operating_mode_tool_definition, OperatingModeControl};
pub use permissions::{
    append_denial, load_denials, widen_caveats, ChoiceSpec, DenialKind, HumanQuestionOutcome,
    PermissionAction, PermissionDecision, PermissionGate, PermissionRecord, PermissionRequest,
    PersistentDenial, BOUND_REASON_PREFIX,
};
pub use plan_mode::{
    plan_verdict, PlanDraft, PlanDraftSink, PlanEntry, PlanModeControl, PlanVerdict, PresentedPlan,
    PLAN_APPROVAL_CHOICES,
};
pub use recall::{recall_tool_definition, RecallSource, StoreRecallSource};
pub use resume::resume_context_tool_definition;
pub use send_budget::{initial_context_input_budget, is_truncation_suspect};
pub use steering::{ReplaceRejected, Rev, SessionSteeringInbox, SteeringInbox};
pub use tools::{
    execute_tool, execute_tool_with_offload, execute_tool_with_offload_and_prompt_and_artifacts,
    exit_plan_mode_result, filter_advertised_tools, filter_tools_for_disposition,
    full_access_requested, ocap_disabled, persona_tool_allowed, plan_phase_clamp,
    preserve_mcp_resource_url_affinity, run_command_dialect_sentence, set_max_output_tokens,
    set_output_cap_chars_per_token, set_output_head_tokens, shell_dialect_sentence, tool_allowed,
    tool_definitions, venv_cmd_prefix, ExposureSettings, MCP_RESOURCE_URL_PREFIXES_META_KEY,
};
pub use transcript::{
    transcript_lines, transcript_lines_styled, TranscriptLine, TranscriptRole, TranscriptStyle,
};
pub use trim::{ollama_usage, openai_usage, trim_for_summary};
pub use untrusted::{wrap_internal_summary, wrap_untrusted};
pub use warmup::warmup_if_cold;

use crate::retry::{with_backoff_notify_error, RetryPolicy};
use compress::{
    compression_trigger, CompressAction, CompressRequest, CompressTrigger,
    CompressionTriggerLimits, RefusalReason,
};
use crossterm::{
    execute,
    style::{Color as CtColor, Print, ResetColor, SetForegroundColor},
};
#[cfg(test)]
use display::turn_heartbeat_line;
use display::{
    emit_compression_notice, emit_overflow_notice, print_debug, print_retry_indicator, print_trace,
    TurnHeartbeat,
};
use send_budget::estimate_responses_request_tokens;
use send_budget::{
    authoritative_request_budget, calibrate_down, calibrate_up, capped_accepted_prompt_tokens,
    count_guard_has_headroom, emit_accepted, emit_context_window_400,
    estimate_responses_request_real_tokens, exposure_budget_tokens,
    full_message_request_pressure_tokens, initial_send_budget, num_ctx_input_ceiling,
    preflight_full_message_request, preflight_irreducible_request, preflight_responses_request,
    recovered_input_budget, resolve_responses_budget, responses_context_remaining_report,
};
use std::io::{self, Write as _};
use tools::{is_hallucination, merged_tool_definitions};
use trim::{
    estimate_request_tokens, estimate_tokens, estimate_value_tokens, merge_round_usage,
    protected_prompt_head_len, PromptTracker,
};

/// Retry policy selected from endpoint locality.
///
/// Local inference keeps the patient seven-attempt policy needed while a DGX
/// loads or sheds pressure. Hosted requests get one retry: each failed attempt
/// may already have consumed the full configured inference bound and may be billable.
/// All thresholds remain overridable through the standard `NEWT_HTTP_*` vars.
fn tui_retry_policy(endpoint: &str) -> RetryPolicy {
    if crate::owned_hosts::inference_is_local(false, Some(endpoint)) {
        RetryPolicy::for_local_inference()
    } else {
        RetryPolicy::for_hosted_inference()
    }
}

/// Pure status text for the canonical inference spinner.
///
/// `idle_timeout_secs` bounds the gap between response chunks, not the whole
/// attempt — a slow-but-progressing stream can run up to
/// `newt_inference::local::STREAM_TOTAL_TIMEOUT_MULTIPLIER` times longer
/// before the attempt's total read deadline cuts it off, so the label says
/// "idle timeout" rather than implying attempts are bounded at this figure.
fn inference_progress_label(
    model: &str,
    attempt: u32,
    attempts: u32,
    idle_timeout_secs: u64,
) -> String {
    format!(
        "waiting for {model} · attempt {attempt}/{attempts} · {idle_timeout_secs}s idle timeout…"
    )
}

/// `Authorization: Bearer <key>` as client default headers for the Ollama
/// wire (Ollama Cloud enforces auth; LAN Ollama ignores the header). Baking
/// it into the client authenticates every request the client ever makes —
/// the un-forgettable form — instead of relying on each call site to
/// remember `.bearer_auth()`. Empty/absent key → empty map (no header).
/// The value is marked sensitive so debug logging never prints it.
fn ollama_auth_headers(api_key: Option<&str>) -> reqwest::header::HeaderMap {
    let mut headers = reqwest::header::HeaderMap::new();
    if let Some(key) = api_key.map(str::trim).filter(|k| !k.is_empty()) {
        if let Ok(mut value) = reqwest::header::HeaderValue::from_str(&format!("Bearer {key}")) {
            value.set_sensitive(true);
            headers.insert(reqwest::header::AUTHORIZATION, value);
        }
    }
    headers
}

#[cfg(test)]
#[path = "mod_tests/first_request_budget_after_switch_tests.rs"]
mod first_request_budget_after_switch_tests;

/// The outcome of the ONE Responses compaction path (#1528 B2/B3): classify the
/// running `input` into typed provenance, compact via the ONE `compress`, rebuild
/// EXHAUSTIVELY, and validate the fenced request against the budget. Both triggers
/// — the REACTIVE cw-400 recovery and the PROACTIVE pre-dispatch guard — call the
/// same [`compact_responses_input`]; they differ ONLY in how they MAP this outcome
/// (reactive surfaces the provider's original 400; proactive fails closed with a
/// fresh refusal). Making the compaction unrepresentable in two places is the
/// point (reuse discipline): a fix or a guard added here can never be missed at
/// one call site.
enum ResponsesCompaction {
    HarnessFailure(String),
    /// Compression fired and the rebuilt (fenced) request fits the budget — the
    /// caller's `input` was rewritten to the compacted form.
    Compacted,
    /// Compression did not fire (nothing left to reclaim) — `input` unchanged.
    NotFired,
    /// The compressor refused: the protected head alone exceeds the budget.
    Refused,
    /// The compressor refused because the selected context manager is
    /// append-only — a different cause with a different remedy, kept distinct so
    /// the rejection diagnostic cannot assert a head size it never measured.
    AppendOnlyRefused,
    /// The rebuilt request still exceeds the budget AFTER fencing — `input` is left
    /// UNCHANGED (BHV-BUDGET-004: never dispatch an oversized request).
    OverBudgetAfterFence(responses_compaction::PostBridgeBudgetExceeded),
    /// `input` could not be classified (a forbidden `system` item) — fail closed.
    BridgeError,
    /// The staged compaction spill batch could not be committed (a poisoned store or a
    /// content-integrity violation) — fail CLOSED, committing NOTHING (BHV-SPILL-007).
    SpillCommitFailed(crate::agentic::content_spill::SpillError),
}

/// The bail message for a [`CompressAction::Refused`] outcome.
///
/// The two refusal causes need DIFFERENT remedies — one is a stuck pipeline, the
/// other is the operator's own policy choice — so the message is selected by
/// [`RefusalReason`] rather than asserting the anti-thrash cause unconditionally.
/// Sending an append-only operator to `newt tunings reset` wastes their time and
/// hides the one action that resolves it.
fn refusal_bail_message(reason: Option<RefusalReason>, current: usize, model: &str) -> String {
    match reason {
        Some(RefusalReason::AppendOnly) => format!(
            "context (~{current} tokens) exceeds the model's input budget and the \
             append-only context manager never rewrites recorded turns — select \
             `/context manager standard` to re-enable compaction, or start a new \
             conversation / ask a more focused question"
        ),
        _ => format!(
            "context (~{current} tokens) exceeds the model's input budget and \
             auto-compression is disabled after repeated ineffective passes — \
             start a new conversation or ask a more focused question, or run \
             `newt tunings reset {model}` if this model's learned budget looks wrong"
        ),
    }
}

/// Why a proactive / reactive compaction attempt did NOT yield a dispatchable
/// request (#1528 B3, item 4). Carried into the fail-closed error CHAIN (as anyhow
/// context on the authoritative preflight, or the provider error for reactive
/// recovery) so headless / structured callers see the reason WITHOUT depending on
/// terminal rendering. No user-facing notice is emitted for a rejected candidate;
/// this reason IS the single diagnostic.
#[derive(Debug, Clone)]
enum CompactionRejection {
    HarnessFailure(String),
    /// `input` could not be classified into typed provenance (a forbidden `system`
    /// item) — BHV-PROVENANCE-002.
    BridgeClassification,
    /// The compressor refused: the protected head alone exceeds the budget.
    CompressorRefused,
    /// The compressor refused because the selected context manager is append-only.
    AppendOnlyRefused,
    /// Compaction could not reduce the request further (nothing left to reclaim).
    NoProgress,
    /// The fenced rebuild still exceeds the budget after framing (BHV-BUDGET-004).
    PostBridgeBudgetExceeded(responses_compaction::PostBridgeBudgetExceeded),
    /// The compacted candidate fit, but its staged spill batch could not be committed
    /// (a poisoned store or a content-integrity violation) — fail closed (BHV-SPILL-007).
    SpillCommit(crate::agentic::content_spill::SpillError),
}

impl std::fmt::Display for CompactionRejection {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::HarnessFailure(error) => write!(f, "smart harness projection: {error}"),
            Self::BridgeClassification => write!(
                f,
                "proactive compaction could not classify the request (a forbidden system item)"
            ),
            Self::CompressorRefused => write!(
                f,
                "proactive compaction refused: the protected head alone exceeds the input budget"
            ),
            Self::AppendOnlyRefused => write!(
                f,
                "proactive compaction refused: the append-only context manager never rewrites \
                 recorded turns — select `/context manager standard` to re-enable compaction"
            ),
            Self::NoProgress => write!(
                f,
                "proactive compaction made no progress: nothing left to reclaim under the budget"
            ),
            Self::PostBridgeBudgetExceeded(e) => {
                write!(f, "proactive compaction fit the compressor budget but {e}")
            }
            Self::SpillCommit(e) => write!(
                f,
                "proactive compaction could not commit its staged spill batch \
                 ({e:?}) — refusing to install a request that names an uncommitted spill"
            ),
        }
    }
}

impl ResponsesCompaction {
    /// The rejection reason when this outcome is NOT a committed compaction — for
    /// the fail-closed error chain. `Compacted` → `None`; `NotFired` (compaction
    /// made no reduction) → `NoProgress`.
    fn rejection(self) -> Option<CompactionRejection> {
        match self {
            Self::HarnessFailure(error) => Some(CompactionRejection::HarnessFailure(error)),
            Self::Compacted => None,
            Self::NotFired => Some(CompactionRejection::NoProgress),
            Self::Refused => Some(CompactionRejection::CompressorRefused),
            Self::AppendOnlyRefused => Some(CompactionRejection::AppendOnlyRefused),
            Self::BridgeError => Some(CompactionRejection::BridgeClassification),
            Self::OverBudgetAfterFence(e) => Some(CompactionRejection::PostBridgeBudgetExceeded(e)),
            Self::SpillCommitFailed(e) => Some(CompactionRejection::SpillCommit(e)),
        }
    }
}

/// A candidate-local staging buffer for the compaction spill(s) built while
/// compressing a Responses candidate (#1528 B3, §2.6). The compressor STAGES each
/// evicted middle span into this buffer PURELY (the CID is a pure function of the
/// content, so its `compaction:<cid>` handle can ride the summary before any commit);
/// nothing reaches the live store. [`compact_responses_input`] drains it and
/// `commit_batch`es into the live store ONLY on the accept branch — a rejected
/// candidate drops the buffer, leaving the live store untouched (BHV-SPILL-006/007).
pub(crate) type CompactionStageBuffer =
    std::sync::Mutex<Vec<crate::agentic::content_spill::StagedSpill>>;

/// Compact the Responses `input` toward `compaction_budget` via the B2 provenance
/// bridge + the ONE `compress`, then validate the fenced rebuild against
/// `actionable_budget` before committing.
///
/// TRANSACTIONAL (#1528 B3, B3-CG-004 / §2.6): the compressor runs against a CLONE of
/// `compress_state` AND a candidate-local [`CompactionStageBuffer`] — the evicted
/// middle span(s) are STAGED PURELY (no live-store mutation) while the candidate is
/// validated (provenance + post-bridge budget). On success — and only then — the
/// helper commits ALL FOUR effects together: it rewrites `*input`, writes the
/// candidate anti-thrash state back into `*compress_state`, `commit_batch`es the
/// staged spills to the real store, and emits the compaction notice. On ANY
/// reject/refuse/over-budget/bridge-error path, `*input`, `*compress_state`, the spill
/// store, and the notice stream are ALL left UNTOUCHED — the staged buffer is dropped
/// and no `compaction:<cid>` was committed — so no caller can dispatch a
/// half-compacted request or believe an uncommitted compaction occurred. Single-shot
/// (one attempt) — the caller decides whether to gate on an estimate (proactive) or
/// always call (reactive), and how to map a non-`Compacted` outcome (see
/// [`CompactionRejection`]).
#[allow(clippy::too_many_arguments)]
async fn compact_responses_input(
    observed_facts: Option<&semantic_pins::Projection>,
    worktree_session: Option<&crate::worktree_adoption::WorktreeSession>,
    input: &mut Vec<serde_json::Value>,
    instructions: Option<&str>,
    tools: Option<&[serde_json::Value]>,
    actionable_budget: Option<usize>,
    compaction_budget: usize,
    cal: f32,
    estimation: crate::tokens::TokenEstimation,
    task: &str,
    summary_input_cap_floor_chars: usize,
    rewrites_history: bool,
    compaction_store: Option<&dyn crate::agentic::content_spill::SpillStore>,
    summarizer: Option<&SummarizeFn>,
    compress_state: &mut CompressState,
    color: bool,
    smart_harness: Option<&smart_harness::SmartHarness>,
    overflow_recovery: bool,
) -> ResponsesCompaction {
    // #2766: the task location outlives lossy history. Reuse the continuation
    // marker so repeated compactions replace the old hint; include its bytes
    // before the existing transactional request-budget checks in either path.
    let with_task = |mut candidate: Vec<serde_json::Value>| {
        if let Some(hint) =
            worktree_session.and_then(crate::worktree_adoption::WorktreeSession::task_hint)
        {
            candidate.retain(|item| !compress::is_continuation_message(item));
            candidate.push(serde_json::json!({"role":"user", "content":
                format!("{} {}", compress::CONTINUATION_PREFIX, workflow_guidance(hint))}));
        }
        candidate
    };

    if let Some(harness) = smart_harness {
        // Preserve native call IDs and reasoning items through host selection.
        // The legacy summarizer bridge intentionally flattens them to prose.
        let max_bytes =
            match smart_harness::projection_byte_budget(input, compaction_budget, estimation) {
                Ok(max_bytes) => max_bytes,
                Err(error) => return ResponsesCompaction::HarnessFailure(error.to_string()),
            };
        let projected = match harness.project(input, max_bytes).await {
            Ok(messages) => with_task(messages),
            Err(error) => return ResponsesCompaction::HarnessFailure(error.to_string()),
        };
        let required = estimate_responses_request_real_tokens(
            instructions,
            &projected,
            tools,
            estimation,
            cal,
        );
        if let Some(budget) = actionable_budget.filter(|budget| required > *budget) {
            return ResponsesCompaction::OverBudgetAfterFence(
                responses_compaction::PostBridgeBudgetExceeded {
                    actionable_budget: budget,
                    post_bridge_estimate: required,
                    framing_overhead: 0,
                },
            );
        }
        if projected == *input {
            return ResponsesCompaction::NotFired;
        }
        *input = projected;
        return ResponsesCompaction::Compacted;
    }
    // Classify the Responses `input` into TYPED provenance (fail-closed) and render
    // it to chat with `instructions` as a protected system head. A forbidden
    // `system` item in `input` fails closed here (BHV-PROVENANCE-002).
    // Only the exact note owned by this turn bypasses the untrusted-input
    // bridge. Unknown system items still fail closed; no marker classification.
    let (host_notes, conversation): (Vec<_>, Vec<_>) = input
        .iter()
        .cloned()
        .partition(|item| observed_facts.is_some_and(|facts| facts.owns_note(item)));
    let messages = match responses_compaction::responses_input_to_compaction(&conversation) {
        Ok(m) => m,
        Err(_) => return ResponsesCompaction::BridgeError,
    };
    let mut chat = host_notes.clone();
    if let Some(ins) = instructions {
        chat.push(serde_json::json!({ "role": "system", "content": ins }));
    }
    chat.extend(responses_compaction::compaction_to_chat(&messages));
    // Run the compressor against a CANDIDATE state AND a candidate-local staging
    // buffer — the live anti-thrash counters / disabled latch and the session
    // compaction store are mutated only on commit (below). The live `compaction_store`
    // is passed so the compressor can STAMP its session scope onto each span and render
    // the pure `compaction:<cid>` handle; the buffer receives the staged span(s)
    // instead of the live store, so nothing is committed until accept. A `None` store
    // passes through as `None` (no buffer), so with no real store the compressor
    // invents no retrieval handle (correction 1).
    let mut candidate_state = compress_state.clone();
    let stage_buffer: CompactionStageBuffer = std::sync::Mutex::new(Vec::new());
    let request = CompressRequest {
        messages: &chat,
        // Real-token cap minus real-token schema overhead → pipeline chars/4
        // currency (mirrors the Chat path).
        budget: compaction_budget,
        max_messages: None,
        replay_protected_tail_len: context_recovery::protected_tool_tail(&chat),
        task,
        hard_budget: true,
        authoritative: true,
        focus: None,
        est: estimation,
        summary_input_cap_floor_chars,
        rewrites_history,
        compaction_store,
        compaction_stage: compaction_store.map(|_| &stage_buffer),
    };
    let compression = if overflow_recovery {
        context_recovery::compress(request, summarizer, &mut candidate_state, smart_harness).await
    } else {
        smart_harness::compress(request, summarizer, &mut candidate_state, smart_harness).await
    };
    let outcome = match compression {
        Ok(outcome) => outcome,
        Err(error) => return ResponsesCompaction::HarnessFailure(error.to_string()),
    };
    // The notice is NOT emitted yet — only a committed compaction surfaces one.
    if outcome.action == CompressAction::Refused {
        // Carry the CAUSE across, not just the fact: `CompressorRefused` names a
        // protected-head size that the append-only guard returns before ever
        // measuring, and this string is the diagnostic headless callers read.
        return match outcome.refusal {
            Some(RefusalReason::AppendOnly) => ResponsesCompaction::AppendOnlyRefused,
            _ => ResponsesCompaction::Refused,
        };
    }
    if !outcome.fired {
        return ResponsesCompaction::NotFired;
    }
    // Drop the instructions system head we prepended for head protection:
    // Both the base instructions and owned facts stay in the protected head.
    let compacted = &outcome.messages;
    let protected = usize::from(instructions.is_some()) + host_notes.len();
    let rebuilt_chat = &compacted[protected..];
    // Reclassify to typed provenance, then rebuild exhaustively (untrusted-derived
    // → fenced `user`).
    let rebuilt_msgs = responses_compaction::chat_to_compaction(rebuilt_chat);
    let with_notes = |mut items: Vec<serde_json::Value>| {
        let mut result = host_notes.clone();
        result.append(&mut items);
        result
    };
    let rebuilt_input = with_task(with_notes(responses_compaction::compaction_to_responses(
        &rebuilt_msgs,
    )));
    // #1528 B2 (BHV-BUDGET-004): the provenance fences are added AFTER the
    // compressor fit its budget, so validate the REBUILT request against the
    // authoritative budget (the SHARED B1 estimator, same real-token currency
    // dispatch enforces) BEFORE committing. `pre_bridge` estimates the SAME
    // messages WITHOUT the fences, attributing any overflow to the framing.
    if let Some(budget) = actionable_budget {
        let est_tokens = |items: &[serde_json::Value]| {
            estimate_responses_request_real_tokens(instructions, items, tools, estimation, cal)
        };
        let post_bridge = est_tokens(&rebuilt_input);
        let pre_bridge = est_tokens(&with_notes(
            responses_compaction::rebuild_unfenced_for_estimate(&rebuilt_msgs),
        ));
        if let Err(exceeded) =
            responses_compaction::check_post_bridge_budget(budget, pre_bridge, post_bridge)
        {
            // REJECT: the staged buffer is dropped WITHOUT commit, so every staged span
            // is retired unused — nothing is fetchable in the live store, its counts are
            // unchanged; `*input`, `*compress_state`, and the notice stream are likewise
            // UNTOUCHED — the candidate is discarded whole.
            return ResponsesCompaction::OverBudgetAfterFence(exceeded);
        }
    }
    // COMMIT — all FOUR effects, now that the candidate is accepted. Ordered so live
    // input never references an uncommitted spill: install the staged spill batch
    // FIRST — and if that batch commit fails (a poisoned buffer or a content-integrity
    // violation), fail CLOSED, leaving `*input`, `*compress_state`, and the notice
    // stream UNTOUCHED (BHV-SPILL-007). Then swap in the input that names those spills,
    // the anti-thrash state, and the notice.
    if let Some(store) = compaction_store {
        let staged = match stage_buffer.into_inner() {
            Ok(s) => s,
            Err(_) => {
                return ResponsesCompaction::SpillCommitFailed(
                    content_spill::SpillError::PoisonedStore,
                )
            }
        };
        if !staged.is_empty() {
            if let Err(e) = store.commit_batch(&staged) {
                return ResponsesCompaction::SpillCommitFailed(e);
            }
        }
    }
    *input = rebuilt_input;
    *compress_state = candidate_state;
    if let Some(notice) = outcome.notice {
        print_harness_notice(&notice, color);
    }
    ResponsesCompaction::Compacted
}

/// Hook recovering a hard context-window 400:
/// `(error, model, today) → parsed full context window`. The loop composes the
/// returned window with its percentage ceiling and generation output reserve;
/// callbacks must not pre-discount it into an input cap. See
/// [`ChatCtx::recover_cw_400`].
pub type RecoverCw400 = fn(&anyhow::Error, &str, &str) -> Option<u32>;

/// One per-round capability observation, reported through
/// [`ChatCtx::on_round_usage`] at the moment it is observed (Phase 20,
/// `docs/design/model-self-tuning.md` §2.2 — the `recover_cw_400` pattern,
/// generalized to the success direction). Evidence must not wait for a turn
/// epilogue an error can skip: the motivating failure discarded a backend-
/// accepted 8,734-token prompt because the turn later ended in `Err`.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum RoundObservation {
    /// Backend evaluated `prompt_tokens` and the round produced a usable
    /// response (tool calls or non-empty content). `estimated_tokens` is the
    /// loop's chars/4 estimate of the same request, for calibration.
    /// Quality-gated AND truncation-gated at the emission sites: never
    /// emitted when the prompt was within 5% of the request's `num_ctx`
    /// (Ollama may have silently dropped the head of the prompt).
    Accepted {
        prompt_tokens: u32,
        estimated_tokens: usize,
    },
    /// Persistent empty responses at `prompt_tokens` after retries (the
    /// 85%-of-safe-context silent-overflow exit).
    SuspectedOverflow { prompt_tokens: u32 },
    /// A hard HTTP error reported the endpoint's full context window. The TUI
    /// applies this through the same in-memory capability entry as subsequent
    /// accepted-round evidence, avoiding stale whole-cache overwrites.
    ContextWindow400 { context_window: u32 },
    /// Response carried only non-content fields (thinking/reasoning) with
    /// empty content.
    ThinkingOnly,
}

/// Source stream for one incremental shell-output chunk.
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
pub enum ToolOutputStream {
    /// Bytes captured from the tool's standard output stream.
    Stdout,
    /// Bytes captured from the tool's standard error stream.
    Stderr,
}

/// Renderer-neutral, turn-scoped consumer for live tool output.
///
/// The interactive TUI supplies this only when both stdio handles are TTYs.
/// Headless callers pass `None` and retain completion-only output exactly.
/// Newt delivers accepted chunks serially on a bounded presentation worker;
/// slow rendering cannot backpressure a child process or its timeout. Live-only
/// chunks may be dropped when that queue is full. The independently captured
/// result envelope remains authoritative and complete.
pub trait LiveToolOutput: Send + Sync {
    /// Begin a new active-tool frame. No terminal output is required until the
    /// first chunk arrives. This runs on the bounded presentation worker, not
    /// on the tool-execution task. An implementation must ignore a generation
    /// that [`LiveToolOutput::abandon`] has already invalidated.
    fn start(&self, generation: u64);

    /// Consume one raw byte chunk. Display sanitization belongs to the sink;
    /// the authoritative result envelope is captured independently. A
    /// generation can be abandoned after a bounded completion wait, so a
    /// post-finish, abandoned, or stale-generation write must be a no-op.
    fn write(&self, generation: u64, stream: ToolOutputStream, chunk: &[u8]);

    /// Erase/close the active frame before the canonical result is printed.
    /// This is ordered after every accepted write on normal completion. Panics
    /// are contained by the dispatcher; implementations should still leave the
    /// terminal in a canonical state whenever possible.
    fn finish(&self, generation: u64);

    /// Invalidate a generation without producing terminal output.
    ///
    /// Cancellation and bounded teardown call this synchronously before the
    /// canonical result may be rendered. It must be fast, idempotent, and must
    /// make queued callbacks for `generation` no-ops. A later [`Self::start`]
    /// must discard abandoned frame bookkeeping without trying to erase it
    /// from the terminal's then-current cursor position.
    fn abandon(&self, generation: u64);
}

/// Renderer-neutral, turn-scoped consumer for COMPLETED tool output spill view.
///
/// This is the Rich TUI's completed spill renderer — an interactive, scrollable
/// viewport painted BELOW the committed `spill_view_lines` excerpt after a tool
/// result. The excerpt stays the canonical transcript record on every tier; the
/// viewport is a scroll affordance that lives only until the turn's next
/// canonical write dismisses it (`dismiss_completed_spill` at round dispatch, or
/// the next tool header). Only the Rich TUI (feature `rich-tui` + `live-spill`)
/// implements this; the Lean TUI and headless callers pass `None`.
///
/// The dismissal discipline is load-bearing: the viewport holds rows the tty
/// arbiter placed under the transcript and erases exactly those rows, so a
/// committed line that landed on them would go with the frame. Dismissing
/// first is what keeps the transcript whole. A viewport that must SURVIVE
/// canonical output (scroll during the next thinking round, or at the prompt)
/// is the #1303 step 6 retain-overlay, not this trait.
///
/// Key differences from `LiveToolOutput`:
/// - Not incremental — renders a complete, finished tool result
/// - Interactive — supports scrolling, expanding/collapsing, editor-mode nav
/// - Bounded — max 50% of screen height so a single spill can't flood a tmux
/// - Delimited — visual boundaries (⎵/⎶/⎴) mark scrollable region extents
pub trait CompletedSpillRenderer: Send + Sync {
    /// Retain a completed result for an on-demand, session-scoped viewer.
    ///
    /// Returns the stable session-local identifier that committed collapse
    /// markers should name. The default preserves renderers that only provide
    /// the transient inline viewport.
    fn retain_completed(&self, _output: &str) -> Option<u64> {
        None
    }

    /// Host-supported inspection affordance, with the command fallback.
    fn recovery_hint(&self, id: u64) -> String {
        format!("/spill open {id}")
    }

    /// Render a completed tool result as an interactive spill viewport.
    ///
    /// `output` is the complete (stdout+stderr) tool output. `width` is the
    /// terminal column count. `max_height` is the maximum rows this viewport
    /// may occupy (enforced at 50% of terminal height by the caller).
    ///
    /// Returns the number of physical rows painted — 0 when the viewport could
    /// not take the screen (no TTY room, or a LIVE viewport is still up).
    fn render_completed(&self, output: &str, width: usize, max_height: usize) -> usize;

    /// Render a captured file change when the host supports safe styled cells.
    /// Existing hosts retain the completed text fallback and its lifecycle.
    fn render_file_change(
        &self,
        _raw_output: &str,
        output: &str,
        _change: std::sync::Arc<FileChangePresentation>,
        width: usize,
        max_height: usize,
    ) -> usize {
        self.render_completed(output, width, max_height)
    }

    /// Whether a COMPLETED viewport is currently on screen (a live viewport
    /// does not count).
    fn is_active(&self) -> bool;

    /// Erase the completed spill viewport from the terminal — a pure rewind;
    /// the committed excerpt above the frame is the durable record. No-op
    /// when no completed viewport is up.
    fn erase(&self);

    /// Drop the viewport's bookkeeping WITHOUT touching the terminal — the
    /// completed twin of the live path's `abandon`. Used at turn-exit
    /// boundaries where canonical lines may already have landed below a
    /// still-painted frame (an error `?`, a cancel return): rewinding from
    /// there would destroy rows the frame does not own, so the frame is left
    /// as inert residue instead, and — critically — no LATER erase can replay
    /// a stale rewind over the next turn's prompt. No-op when nothing is up.
    fn discard(&self) {}
}

/// Turn-scoped guard: discards any still-tracked completed viewport when the
/// provider function exits by ANY path (normal return, `?`, cancel, panic).
/// This makes the worst failure — a stale `MoveUp` rewind executing on a later
/// turn, over the prompt and the user's typed input — unrepresentable: the
/// bookkeeping cannot outlive the turn that painted the frame.
struct CompletedSpillDismissGuard<'a>(&'a Option<std::sync::Arc<dyn CompletedSpillRenderer>>);

impl Drop for CompletedSpillDismissGuard<'_> {
    fn drop(&mut self) {
        if let Some(renderer) = self.0 {
            renderer.discard();
        }
    }
}

/// Everything one agentic turn needs, resolved once by the caller (the TUI
/// resolves config + capability cache + caveats per turn and threads them in
/// here, so the loop itself never re-reads config from disk).
pub struct ChatCtx<'a> {
    /// Captured shell syntax guidance shared by initial and deferred catalogs.
    pub shell_dialect: &'static str,
    /// Captured session budget shared by tool schemas and execution.
    pub command_budget: crate::RunCommandBudget,
    /// Optional accounted projection and auxiliary completion adjudication.
    pub smart_harness: Option<&'a smart_harness::SmartHarness>,
    pub url: &'a str,
    pub model: &'a str,
    /// Wire protocol of the active backend (Ollama vs OpenAI-compatible).
    pub kind: crate::BackendKind,
    /// Bearer token for authenticated OpenAI-compatible endpoints.
    pub api_key: Option<&'a str>,
    /// Full message list already assembled by `MemoryManager::build_messages`.
    pub messages: &'a [crate::MemMessage],
    pub task: &'a str,
    pub workspace: &'a str,
    /// Operator-selected default for commands only; never changes workspace identity or grants.
    pub default_command_cwd: Option<&'a std::path::Path>,
    /// Session-owned worktree adoption, retained across turns.
    pub worktree_session: Option<&'a crate::worktree_adoption::WorktreeSession>,
    pub color: bool,
    /// Render assistant Markdown as ANSI in the live stream (Step 25.4, #568).
    /// Resolved by the caller as `[tui].markdown` (∧ `/markdown` override) ∧
    /// color. The loop only renders when this is true.
    pub markdown: bool,
    /// Offload oversized tool results to the session spill store (Step 26.3,
    /// #584). The resolved `tool_offload` composable feature (Step 26.1); false
    /// for headless/eval callers (bit-for-bit unchanged when off).
    pub tool_offload: bool,
    /// Session spill store for `tool_offload` (Step 26.3). `None` = no offload
    /// (and `spill:` re-reads resolve to a labelled absence). Shared `&dyn`
    /// (interior mutability) so it serves both the write path and `memory_fetch`.
    pub spill_store: Option<&'a dyn crate::agentic::content_spill::SpillStore>,
    /// step-6.1a (`disclosure-gate-live-path`): the by-VALUE disclosure filter for
    /// the single live tool-result chokepoint (`maybe_offload_tool_result`). Holds
    /// the session-registered secret/canary values; every tool result is passed
    /// through [`DisclosureFilter::redact`](crate::ocap::DisclosureFilter::redact)
    /// before it becomes a `{"role":"tool"}` message, catching the value in any
    /// encoding (re-encoding defeats the shape filter). `None` = no registered
    /// secret (bit-for-bit unchanged) — the session-start registration wiring is a
    /// follow-up; this establishes the chokepoint + its canary ratchet guard.
    pub disclosure: Option<&'a crate::ocap::DisclosureFilter>,
    /// Session compaction store (#661 group B): the compressor stores each
    /// evicted (redacted) middle span here and names a `compaction:<id>` handle
    /// in the marker, so the model can losslessly recover a detail the summary
    /// dropped. SEPARATE store from `spill_store` (own id space). `None` =
    /// lossy-only compaction (headless / progressive disclosure off).
    pub compaction_store: Option<&'a dyn crate::agentic::content_spill::SpillStore>,
    /// Inject the `<state>` scratchpad block + advertise the state tools (Step
    /// 26.4, #583). The resolved `scratchpad` feature; false for headless/eval.
    pub scratchpad: bool,
    /// Session scratchpad store (Step 26.4). `None` = state tools not advertised
    /// and no `<state>` injected. Shared `&dyn` (interior mutability).
    pub scratchpad_store: Option<&'a dyn crate::agentic::scratchpad::ScratchpadStore>,
    /// Semantic searcher for the `code_search` tool (Step 26.5.5). `None` = the
    /// tool is not advertised (semantic off / no index). Bundles embedder+index.
    pub code_search: Option<crate::agentic::semantic::CodeSearch<'a>>,
    /// #1285: the retained `where_is` symbol index for the exact typed-verdict
    /// lookup tool. `None` = no index built (the tool degrades honestly). Built
    /// from the honest gather + language packs — model-free, so it can ride
    /// every session.
    pub where_is: Option<&'a crate::where_is::WhereIsIndex>,
    /// #1387 Code Navigator tool context (usage/graph/project).
    pub nav: Option<crate::navigator::NavToolCtx<'a>>,
    /// Tool-exposure controller policy (Pass 1). `Default` is
    /// [`crate::agentic::tools::ExposureSettings::default`] =
    /// `ExposureProfile::Full`, i.e. the identity controller (advertise the full
    /// authorized catalog). Resolved by the TUI from `[tool_exposure]`; headless
    /// / eval callers take the default. Budget-driven selection uses the LIVE
    /// send budget (probed `safe_context`), never the model name.
    pub exposure: crate::agentic::tools::ExposureSettings,
    /// Experiential store for the record/recall tools (Step 26.6a). `None` = the
    /// tools are not advertised (experiential off). Shared `&dyn` (interior mut).
    pub experience_store: Option<&'a dyn crate::agentic::experiential::ExperienceStore>,
    /// Plan ledger for the update_plan tool (Step 26.6b). `None` = the tool is
    /// not advertised (scheduled off). Shared `&dyn` (interior mut).
    pub step_ledger: Option<&'a dyn crate::agentic::scheduled::StepLedger>,
    pub caveats: &'a crate::caveats::Caveats,
    /// Preferred tools from the active persona's `tools:` metadata. This only
    /// ranks discovery; it never hides a tool or grants/denies its execution.
    pub persona_tools: Option<&'a [String]>,
    /// The psyche **cognition** dial for this turn — how much reasoning effort to
    /// request. `Some(level)` emits OpenAI **Responses** `reasoning.effort` or,
    /// for an explicitly capable Chat Completions endpoint, resolves a local
    /// generation policy. `None` omits cognition-derived fields. The TUI
    /// resolves this from the active persona's `cognition:` front-matter
    /// alongside `persona_tools`; the headless driver preserves semantic intent
    /// separately and passes only the supported projection here.
    pub cognition: Option<crate::role_profile::Cognition>,
    /// Chat Completions extensions explicitly accepted by this endpoint.
    /// Unknown endpoints use the all-unset default and retain the historical
    /// request body even when cognition is active.
    pub chat_completions_capability: crate::model_card::ChatCompletionsCapability,
    /// Responses declarations captured from the same active capability decision.
    pub responses_capability: crate::model_card::ResponsesCapability,
    /// The typed wire choice captured with this context, never reread mid-turn.
    pub openai_api: crate::OpenAiApi,
    /// Explicit output-token allowance (`[[model_tuning]] output_allowance`,
    /// #2312). Overrides the cognition table's output budget without touching
    /// cognition, thinking or sampling; every loop reserves it locally, and it is
    /// sent only where the wire declares a cap. `None` keeps today's defaults.
    pub output_allowance: Option<u32>,
    /// Legacy model-tuning preference. Provider output limits now stop the turn;
    /// this preference cannot purchase an automatic continuation (#2824).
    pub overflow_retry: crate::config::OverflowRetry,
    /// The run's attempt ledger (#2313). Every primary inference request is
    /// recorded as one attempt at the send, from its exact wire bytes. `None`
    /// records nothing.
    pub attempt_ledger: Option<&'a std::sync::Mutex<crate::attempts::AttemptLedger>>,
    /// Whether assistant reasoning may be replayed to the active backend.
    /// Unknown endpoints default to `Never`; local reasoning backends opt in via
    /// their explicit capability profile.
    pub reasoning_replay_scope: crate::model_card::ReasoningReplayScope,
    /// Whether this model streams a lone leading `</think>` closer, so the
    /// filter must start inside the reasoning block (#528).
    ///
    /// Resolved by the caller from the backend's capability layers (inline
    /// declaration + named `card =` binding, decided per serving principal
    /// by `ResolvedCapabilities`) — never from the model name.
    ///
    /// Undeclared resolves to `false` (do not suppress): filtering wrongly
    /// drops real answer text silently, while not filtering wrongly shows
    /// reasoning the operator can see.
    pub emits_leading_reasoning: bool,
    /// Initial tool-call allowance (from `[tui].max_tool_rounds`, default 40).
    /// Recent concrete progress may renew it when `workflow_grace_rounds > 0`.
    pub max_tool_rounds: usize,
    /// Renewable progress-backed round increment, without continuation prompts.
    /// Each renewal requires fresh evidence. `0` makes the normal cap hard.
    pub workflow_grace_rounds: usize,
    /// Max narrate-then-stop rescue nudges per turn (from
    /// `[tui].narration_nudge_cap`, default 1; `[[model_tuning]]` can override
    /// per model). Once spent, the next no-tool narration is accepted as the
    /// turn's final answer. The second and later nudges escalate: they name
    /// the active plan step and demand a bare tool call (lever L3,
    /// docs/design/next-loop-levers.md).
    pub narration_nudge_cap: usize,
    /// Master switch for ACTION-pressure nudges (#1162: the operator's live
    /// dial — `/nudge off` / `NEWT_NUDGE=off`). `false` disables the narration
    /// rescue, workflow repair steering, and pending-plan pushes for the
    /// session; factual-correction nudges are unaffected. Default `true`.
    pub action_nudges: bool,
    /// Validated prompt-comprehension disposition for this turn. The loop
    /// advertises only the corresponding catalog and lets only `Act` retain
    /// execution-pressure nudges; the dispatcher remains the final authority
    /// boundary for fabricated tool names.
    pub prompt_disposition: PromptDisposition,
    /// The resolved prompt-comprehension manifest for this turn, when the
    /// caller owns an intake boundary. It is borrowed only to place its
    /// content-free model card inside the protected active-prompt card;
    /// headless compatibility callers can leave it `None`.
    pub prompt_intake: Option<&'a PromptIntake>,
    /// Legacy line limit for pre-execution previews. Completed tool results use
    /// the `[tui].spill_lines` height published once per turn.
    pub tool_output_lines: usize,
    /// Enable per-round diagnostic output. Set via `NEWT_DEBUG=1` or the
    /// `[tui] debug = true` config key.
    pub debug: bool,
    /// Enable deeper backend compatibility traces. Set via `NEWT_TRACE=1` or
    /// the `[tui] trace = true` config key.
    pub trace: bool,
    /// Ollama `options.num_ctx` — caps KV-cache allocation to prevent VRAM
    /// exhaustion on large models. `None` → model default (often 131k).
    /// Also feeds the pre-send budget as a hard input ceiling for this turn's
    /// requests (issue #282): Ollama silently evaluates only the window's
    /// tail, so anything newt sends must already fit inside the `num_ctx` it
    /// sends it with. OpenAI requests do not serialize `num_ctx`, but local
    /// compatible endpoints still use it as an authoritative declared window
    /// for preflight, compaction, reporting, and 400 recovery.
    pub num_ctx: Option<u32>,
    /// TCP connect timeout. Short (5 s default) so a down endpoint fails fast
    /// rather than blocking the full `inference_timeout_secs`.
    pub connect_timeout_secs: u64,
    /// Inference timeout (120 s default): a total bound for single-response
    /// requests and a maximum idle gap for streamed generation.
    pub inference_timeout_secs: u64,
    /// Message list size at which the agent trims the middle of the in-flight
    /// conversation to prevent context overflow mid-turn.
    pub mid_loop_trim_threshold: usize,
    /// Policy deciding whether the message-count guard alone may trigger a
    /// compaction while an authoritative input ceiling is known. Resolved from
    /// `[context].compaction_trigger_policy` by the interactive caller;
    /// headless callers use the safe `headroom_aware` default.
    pub compaction_trigger_policy: crate::CompactionTriggerPolicy,
    /// Estimated-token threshold that also triggers a mid-loop trim, regardless
    /// of message count. Guards against a single huge tool result blowing past
    /// the context window in one round (from `[tui].mid_loop_trim_tokens`).
    /// `None` disables token-based trimming. See issue #223.
    pub mid_loop_trim_tokens: Option<usize>,
    /// Highest input-token count this model has accepted without a 400, from
    /// `model-capabilities.json`. Used as the pre-send budget gate: requests
    /// estimated to exceed it are trimmed *before* dispatch. `None` falls back
    /// to `safe_context`. See issue #223.
    pub max_ok_input: Option<u32>,
    /// Shell command run after every successful file write to give the model
    /// immediate ground-truth feedback (e.g. "cargo check -q --workspace").
    /// `None` disables auto-checking. Set per-workspace in `.newt/config.toml`.
    pub build_check_cmd: Option<String>,
    /// Empirically derived safe context size for this model (input tokens).
    /// Used to detect likely overflow when the model returns an empty response.
    /// Sourced from `model-capabilities.json` via `ensure_context_window`.
    /// `None` disables overflow detection.
    pub safe_context: Option<u32>,
    /// Hook invoked when a dispatch fails, to recover a hard context-window
    /// 400: `(error, model, today) → parsed full context window`. The loop
    /// derives the effective input cap after reserving its configured maximum
    /// output; callbacks must not return a pre-discounted input budget. The
    /// loop emits [`RoundObservation::ContextWindow400`] so the TUI's existing
    /// observation owner can persist the discovery. `None` disables numbered
    /// recovery.
    pub recover_cw_400: Option<RecoverCw400>,
    /// Model-writable note store behind the `save_note` tool (Step 19.3,
    /// #248). `None` ⇒ the tool is not advertised and the loop never writes
    /// memory (eval / headless callers unaffected). The TUI passes a sink
    /// over its session `MemoryManager`, so `save_note` and `/remember`
    /// share one store, one security scan, one char budget.
    pub note_sink: Option<&'a mut dyn NoteSink>,
    /// Turn-counted memory-nudge state ([`NoteNudge`]), owned by the caller
    /// across user turns and lent to the loop per call. Consulted only when
    /// `note_sink` is present; `None` disables the nudge.
    pub note_nudge: Option<&'a mut NoteNudge>,
    /// Read-only search over PAST conversations behind the `recall` tool
    /// (Step 17.5, #246). `None` ⇒ the tool is not advertised and the loop
    /// never searches (eval / headless callers unaffected). The TUI passes
    /// a [`StoreRecallSource`] over its session `ConversationStore` —
    /// workspace-fenced, current conversation excluded.
    pub recall_source: Option<&'a dyn RecallSource>,
    /// Read-only pull of an ADDRESSED memory item behind the `memory_fetch`
    /// tool (progressive-disclosure memory, Workstream A MVP, #319). `None` ⇒
    /// the tool is not advertised and the loop never fetches — eval / headless
    /// / ACP callers (which pass `memory_source: None`) are unaffected,
    /// bit-for-bit. The TUI passes a [`StoreMemorySource`] over its session
    /// `NoteStore` + `ConversationStore` (workspace-fenced), so `note:` and
    /// `turn:` addresses resolve against the same surfaces `/remember` and
    /// `recall` use. Gated exactly like `recall_source`.
    pub memory_source: Option<&'a dyn MemorySource>,
    /// Compression summarizer (Step 18.4, #247): given the redacted summary
    /// request, returns the summary text — typically one tools-disabled
    /// completion against the same backend (the TUI wires this, mirroring
    /// the `Summarizing` provider's `with_summarizer` injection). `None`
    /// (eval / headless) ⇒ the compression pipeline degrades to the static
    /// "Summary generation was unavailable" marker instead of an LLM summary.
    pub summarizer: Option<&'a SummarizeFn>,
    /// Session-scoped compression anti-thrash state ([`CompressState`]),
    /// owned by the caller across user turns and lent per call (the
    /// `note_nudge` pattern). `None` ⇒ a fresh per-turn state.
    pub compress_state: Option<&'a mut CompressState>,
    /// Per-turn tool-event recorder (Step 17.6, #246): when present, the
    /// loop pushes one [`crate::ToolEvent`] per executed tool call — name,
    /// privacy-preserving args digest (never raw args), outcome, duration
    /// claim — at the same site that renders tool activity live. The TUI
    /// lends a fresh `Vec` per turn (the `note_nudge` pattern) and persists
    /// it into the turn's `events` column. `None` (eval / headless) ⇒
    /// nothing is recorded.
    pub tool_events: Option<&'a mut Vec<crate::ToolEvent>>,
    /// Per-turn phantom-reach recorder (#717): when present, the loop pushes one
    /// [`crate::PhantomReach`] for each phantom tool/capability reach (alias
    /// resolve, hallucination, or a real-tool empty-by-design miss). Lent fresh
    /// per turn like `tool_events`; persisted into the turn's `phantom_reaches`.
    /// `None` (eval / headless) ⇒ nothing recorded.
    pub phantom_reaches: Option<&'a mut Vec<crate::PhantomReach>>,
    /// Out-param: why the loop ended the turn ([`crate::TurnEndReason`]) —
    /// narration-acceptance forensics, round cap, empty reply. Lent fresh per
    /// turn like `tool_events`; the TUI folds it into `TurnMetrics` (footer +
    /// usage.jsonl). `None` (eval / headless) ⇒ nothing reported. All smart
    /// providers report terminal control outcomes, including Responses.
    pub end_reason: Option<&'a mut Option<crate::TurnEndReason>>,
    /// Out-param: set when the turn ended at its tool-round cap, whatever end
    /// reason that exit reports. #2374: a result-aware cap exit reports
    /// `RepairExhausted`, and the TUI still pauses the objective there. `None`
    /// ⇒ not reported.
    pub round_cap_hit: Option<&'a mut bool>,
    /// Out-param: per-turn observability for the solve contract (W0 #1511) —
    /// the backend-reported served `model` plus per-round tool-call parse
    /// signals ([`observability::ParseSignal`]). Lent fresh per turn like
    /// `tool_events`; the headless driver folds it into the `TurnOutcome` and
    /// `newt solve` serializes it. `None` (TUI / eval) ⇒ nothing recorded.
    /// The Responses-API loop does not report it (same as `end_reason`).
    pub solve_obs: Option<&'a mut observability::SolveObservation>,
    /// Prompted ocap grants (issue #263): when present, a capability denial
    /// inside `execute_tool` consults the human — allow once / session allow
    /// / deny — instead of failing outright; the loop blocks like a long
    /// tool call while the prompt is pending. `None` (the default — every
    /// headless caller: ACP worker, `newt-eval`) keeps each denial exactly
    /// as before, so nothing non-interactive can ever hang on a prompt.
    pub permission_gate: Option<&'a mut dyn PermissionGate>,
    /// Per-round capability observation hook (Phase 20,
    /// `docs/design/model-self-tuning.md` §2.2): the loop reports each
    /// round's evidence — accepted prompt sizes (with the matching chars/4
    /// estimate for calibration), persistent-empty suspected overflows, the
    /// thinking-only response quirk — at the moment of observation, so the
    /// caller can persist it even when the turn later bails or errors (the
    /// motivating failure discarded an accepted 8,734-token prompt because
    /// the only write-back lived in the TUI's `Ok`-arm epilogue). `None`
    /// (ACP worker, eval, cowork driver) preserves today's behavior exactly
    /// (spec §5).
    pub on_round_usage: Option<&'a mut dyn FnMut(RoundObservation)>,
    /// Learned observed/estimated prompt-token ratio for this model
    /// (Phase 20 §2.3), applied wherever chars/4 estimates meet
    /// backend-reported token budgets — compression triggers, targets, and
    /// the tool-schema overhead. `None` or out-of-clamp values degrade to
    /// 1.0 (no calibration; pre-Phase-20 behavior).
    pub estimate_ratio: Option<f32>,
    /// `[context.estimation]` token-estimation heuristic (chars-per-token),
    /// extracted from config so the loop never re-reads it — drives every
    /// chars→token estimate and the budget→chars summary-cap conversion.
    pub estimation: crate::tokens::TokenEstimation,
    /// `[context] summary_input_cap_floor_chars` — floor for the summarizer
    /// input cap so a tight budget never starves the summarizer of material.
    pub summary_input_cap_floor_chars: usize,
    /// `[context] input_ceiling_pct` — percentage-based input limit inside the
    /// declared context window. The effective ceiling is the tighter of this
    /// limit and the space left after the generation policy's maximum output.
    /// Historically hardcoded at 80 (20% headroom). Applied by
    /// `num_ctx_input_ceiling`.
    pub input_ceiling_pct: u32,
    /// `[context] low_budget_pct` — remaining-budget percent below which the
    /// loop treats the turn as "low budget" and nudges toward wrapping up.
    /// Historically hardcoded at 15.
    pub low_budget_pct: usize,
    /// #307 named-permission-preset exec FLOOR. When a `/posture` preset is active
    /// its exec clamp is threaded here so the `--disable-ocap` / `--yolo`
    /// bypass in `execute_tool` cannot raise exec authority above the preset:
    /// an out-of-floor command falls through to the confined shell and is
    /// denied. `None` (no active posture, and every headless caller) leaves the
    /// bypass bit-for-bit. The floor is also already `meet`-ed into `caveats`,
    /// so the confined-shell and gate paths enforce it too; this field is the
    /// one extra place the otherwise caveats-blind bypass must consult.
    pub exec_floor: Option<&'a crate::caveats::Scope<String>>,
    /// `retry` technique (R2 action arm): a turn-scoped copy-on-first-write ledger
    /// ([`crate::verify_gate::WriteLedger`]) the file-write tools record into before
    /// each `write_file` / `edit_file`, so the caller can revert exactly the files
    /// newt wrote this turn (and only those) after the gate runs. Shared via
    /// [`RefCell`](std::cell::RefCell) so the loop records while the caller reads.
    /// `None` (every headless caller, and any profile without `retry`) ⇒ nothing is
    /// recorded and no file is ever reverted — bit-for-bit today's behavior.
    pub write_ledger: Option<&'a std::cell::RefCell<crate::verify_gate::WriteLedger>>,
    /// #1707/#1709: the session-scoped pending multi-contributor commit
    /// attribution ledger ([`crate::attribution::AttributionLedger`]). A
    /// non-read-only tool call that SUCCEEDS records `ctx.model` under the
    /// current harness identity here; the caller renders it into the NEXT
    /// commit's `Co-authored-by:` trailers and clears it only once that
    /// commit actually lands. Shared via [`RefCell`](std::cell::RefCell) for
    /// the same reason as `write_ledger`: the loop records while the caller
    /// (and the git-commit path) reads. `None` (every headless / eval
    /// caller) ⇒ nothing is recorded — bit-for-bit today's behavior there.
    pub attribution: Option<&'a std::cell::RefCell<crate::attribution::AttributionLedger>>,
    /// User-interrupt flag (Esc / Ctrl-C during a turn). When set mid-turn the
    /// loop abandons at its next checkpoint — the round-loop top and provider
    /// response awaits — and
    /// returns early. `None` (every headless / eval caller) ⇒ no interrupt
    /// path, bit-for-bit today's behavior. The caller owns the `AtomicBool`,
    /// trips it from a keyboard watcher, and inspects it after the call to tell
    /// an interrupted turn from a genuinely empty reply.
    pub cancel: Option<&'a std::sync::atomic::AtomicBool>,
    /// The run's remaining call budget (#2313). Checked once per dispatch, at
    /// the same point every attempt is keyed from its exact wire bytes
    /// ([`attempt_capture::send`]). `None` (every existing caller today) is
    /// bit-for-bit unchanged behavior: no reservation, no refusal.
    pub run_allowance: Option<&'a run_allowance::RunAllowance>,
    /// Optional TTY-owned live tool-output sink (#1235). Owned in an `Arc`
    /// because shell stdout/stderr drains may publish from worker threads.
    /// `None` is the mandatory headless/non-TTY path.
    pub live_tool_output: Option<std::sync::Arc<dyn LiveToolOutput>>,
    /// Optional TTY-owned COMPLETED spill renderer for Rich TUI (#1640).
    /// Only the Rich TUI (feature `rich-tui` + `live-spill`) implements this;
    /// the Lean TUI and headless callers pass `None` and retain the static
    /// completion-only output from `display::spill_view_lines`.
    pub completed_spill_renderer: Option<std::sync::Arc<dyn CompletedSpillRenderer>>,
    /// #2315: the operator asked for result-aware verification
    /// (`NEWT_VERIFY_OUTCOMES`). The host reads it once when it builds the
    /// context; the loop never reads the process env for it. The gate also
    /// needs `NEWT_SELF_VERIFY` on.
    pub verify_outcomes: bool,
    /// The injected embedded-git capability (PR4, #461). `Some` ⇒ the `git`
    /// tool is advertised and dispatches through it (`LocalGitTool` in
    /// `newt-git`, injected by the binary). `None` (every headless / eval
    /// caller, and any session not in a git repo) ⇒ the tool is never
    /// advertised — bit-for-bit today's behavior. The trait-injection seam, not
    /// a direct dep, because `newt-git` depends on `newt-core` (circular).
    pub git_tool: Option<&'a dyn GitTool>,
    /// The injected crew/team orchestration capability (#479). `Some` ⇒ the
    /// `compose_roster` + `crew` tools are advertised and dispatch through it
    /// (`LocalCrewRunner` in `newt-cli`, injected by the `/team` toggle). `None`
    /// ⇒ never advertised. Trait-injection seam like `git_tool` (newt-scheduler
    /// depends on newt-core, so the dep can't be direct).
    pub crew_runner: Option<&'a dyn CrewRunner>,
    /// Whether the selected context manager may rewrite already-recorded
    /// messages. `false` is the append-only strategy — see
    /// [`crate::ContextManager::rewrites_history`]. Defaults to `true`
    /// (today's `standard` preset) so every existing caller is unchanged.
    pub rewrites_history: bool,
    /// Session-local working-style selector behind `/mode auto`. `Some` only
    /// when the human configured Auto mode, so every other session omits the
    /// model-facing selector entirely. A selection affects a future turn and
    /// cannot change this turn's disposition or caveats.
    pub operating_mode_control: Option<&'a dyn OperatingModeControl>,
    /// Session-local state behind `enter_plan_mode` / `exit_plan_mode`.
    ///
    /// The dispatcher checks this collaborator before every tool call, so
    /// entering Plan immediately clamps subsequent calls in the same model
    /// round. `None` means the model-entered Plan phase is unavailable.
    pub plan_mode_control: Option<&'a dyn PlanModeControl>,
    /// #2424: where `render_report` stores its draft instead of printing it
    /// while the Plan disposition is active. `None` behaves as the plain
    /// `render_report` path always has (no plan mode wired at all, e.g.
    /// eval/headless).
    pub plan_draft_sink: Option<&'a dyn PlanDraftSink>,
    /// #952/#1669: operator steering submitted while this turn is running.
    ///
    /// Drained at the TOP of each tool round — before the next model call, and
    /// after any tool already in flight has finished — and appended as genuine
    /// operator user messages, in submission order. So a correction typed
    /// mid-turn reaches the agent's next reasoning cycle instead of waiting for
    /// the round cap, without disturbing a request already on the wire.
    ///
    /// This is the same shape as `cancel`, one step up: `cancel` signals "stop"
    /// with a bit, this delivers "do that differently" with a payload. It is
    /// NOT cancellation and never abandons the turn.
    ///
    /// `None` (every headless / eval caller) ⇒ nothing is ever drained and the
    /// request bodies are bit-for-bit today's.
    pub steering: Option<&'a dyn SteeringInbox>,
}

/// Record organic save_note use after repeat rejection and before dispatch.
/// Reset even if the subsequent attempt fails or is cancelled; retain the
/// optional sink/nudge gates.
fn record_organic_note_use(
    name: &str,
    note_sink: &Option<&mut dyn NoteSink>,
    note_nudge: &mut Option<&mut NoteNudge>,
) {
    if name == "save_note" && note_sink.is_some() {
        if let Some(n) = note_nudge.as_deref_mut() {
            n.note_saved();
        }
    }
}

/// #1948: observe completed calls and append at most one clean-build warning
/// per turn. Keep this after repeat recording and before event timing.
fn append_clean_build_warning(
    messages: &mut Vec<serde_json::Value>,
    clean_build: &mut crate::loop_watch::CleanBuildWatch,
    args: &serde_json::Value,
    harness: Option<&smart_harness::SmartHarness>,
) -> anyhow::Result<()> {
    if let Some(warning) = clean_build.observe(
        args.get("command")
            .and_then(serde_json::Value::as_str)
            .unwrap_or_default(),
    ) {
        let text = format!("{} {warning}", compress::LOOP_GUIDANCE_PREFIX);
        if let Some(harness) = harness {
            harness.host_message(&text)?;
        }
        messages.push(serde_json::json!({"role":"user", "content":text}));
    }
    Ok(())
}

/// Record a completed call only when the event sink is present. Keep elapsed
/// sampling here, after backend bookkeeping and before phantom classification.
fn record_completed_tool_event(
    tool_events: &mut Option<&mut Vec<crate::ToolEvent>>,
    name: &str,
    args: &serde_json::Value,
    ok: bool,
    // #2315: required, so no funnel can record a shell call without deciding
    // what its execution slot holds.
    execution: Option<crate::ExecOutcome>,
    tool_t0: std::time::Instant,
) {
    if let Some(rec) = tool_events.as_deref_mut() {
        rec.push(crate::ToolEvent {
            execution,
            ..crate::ToolEvent::from_call(
                name,
                args,
                ok,
                u64::try_from(tool_t0.elapsed().as_millis()).ok(),
            )
        });
    }
}

/// #717 / #479 (G4): record alias, hallucination, and real-tool empty-miss
/// reaches, falling back to gated-off crew/team reaches. Classify only when
/// the phantom sink is present; preserve the primary classifier's precedence.
fn record_phantom_reach(
    phantom_reaches: &mut Option<&mut Vec<crate::PhantomReach>>,
    name: &str,
    args: &serde_json::Value,
    result: &str,
    ok: bool,
    advertise_team: bool,
) {
    if let Some(pr) = phantom_reaches.as_deref_mut() {
        if let Some(resolution) = tools::classify_phantom_reach(name, args, result, ok)
            .or_else(|| tools::classify_gated_off_reach(name, advertise_team))
        {
            pr.push(crate::PhantomReach {
                name_as_called: name.to_string(),
                resolution,
                active_context_features: Vec::new(),
            });
        }
    }
}

/// retry technique (R2 action arm): before a `write_file`/`edit_file` is dispatched,
/// capture the target's pre-write bytes into the turn ledger. Recorded at the loop's
/// dispatch site (not inside `execute_tool`) so the seam stays narrow and only the
/// two file-writing tools are ever tracked. [`WriteLedger::note_before_write`] is
/// idempotent on the turn's first write of a path, so the *pre-turn* state is what
/// is preserved. A no-op when no ledger is lent — every headless caller and any
/// profile without `retry` — so behavior is bit-for-bit unchanged there.
fn ledger_note_write(
    write_ledger: Option<&std::cell::RefCell<crate::verify_gate::WriteLedger>>,
    name: &str,
    args: &serde_json::Value,
    workspace: &str,
) {
    let Some(led) = write_ledger else {
        return;
    };
    if name != "write_file" && name != "edit_file" {
        return;
    }
    if let Some(p) = args.get("path").and_then(|v| v.as_str()) {
        // Key on the lexically-normalized path so a raw model path like
        // `examples/../foo.py` matches the gate's filesystem-normalized `foo.py`
        // and the revert lookup actually hits — otherwise a non-normalized path
        // would silently evade revert (the fabrication persists, the gate is gamed).
        let abs = lexical_normalize(&std::path::Path::new(workspace).join(p));
        led.borrow_mut().note_before_write(abs);
    }
}

/// #1707/#1709: record `model` as a contributor to the pending commit
/// attribution ledger when this just-completed call `ok` and was not a
/// read-only query — reusing [`is_read_only_call`], the SAME classifier that
/// already decides `round_wrote` for read-only-round steering, rather than
/// re-deriving a second "is this a write" predicate. Called AFTER dispatch
/// (unlike [`ledger_note_write`], which snapshots BEFORE for revert
/// purposes): a denied or failed call materially changed nothing and must
/// not be credited.
fn ledger_note_attribution(
    attribution: Option<&std::cell::RefCell<crate::attribution::AttributionLedger>>,
    model: &str,
    name: &str,
    args: &serde_json::Value,
    ok: bool,
) {
    let Some(ledger) = attribution else {
        return;
    };
    if !ok || is_read_only_call(name, args) {
        return;
    }
    ledger.borrow_mut().record(
        model,
        crate::build_info::harness_name(),
        crate::build_info::PACKAGE_VERSION,
    );
}

/// Reconcile one tool call with the host's confirmed commit signal.
///
/// The TUI drains commit telemetry only after the entire agent run returns, so
/// the counter cannot reset during this scope. Preparation, signing, output
/// text, and a final shell exit status are not publication evidence. A native
/// commit may land before a later command fails or the tool is cancelled.
///
/// Native shell calls may also write after committing. Consume the pre-call
/// contributors but conservatively retain the active model for those possible
/// effects, even after a failing tail. This may retain the active model after
/// a commit-only shell call; it never carries earlier models forward or erases
/// later tool-call contributions. The embedded tool has one operation per
/// call and does not need that conservative retention.
struct AttributionEpoch<'a> {
    attribution: Option<&'a std::cell::RefCell<crate::attribution::AttributionLedger>>,
    git_tool: Option<&'a dyn GitTool>,
    confirmed_before: usize,
    model: &'a str,
    name: &'a str,
    finished: bool,
}

impl<'a> AttributionEpoch<'a> {
    fn new(
        attribution: Option<&'a std::cell::RefCell<crate::attribution::AttributionLedger>>,
        git_tool: Option<&'a dyn GitTool>,
        model: &'a str,
        name: &'a str,
    ) -> Self {
        Self {
            attribution,
            git_tool,
            confirmed_before: git_tool.map_or(0, GitTool::confirmed_commit_count),
            model,
            name,
            finished: false,
        }
    }

    fn consume_confirmed(&self) -> bool {
        let confirmed = self
            .git_tool
            .is_some_and(|tool| tool.confirmed_commit_count() > self.confirmed_before);
        if confirmed {
            if let Some(ledger) = self.attribution {
                let mut ledger = ledger.borrow_mut();
                ledger.clear();
                if self.name != "git" {
                    ledger.record(
                        self.model,
                        crate::build_info::harness_name(),
                        crate::build_info::PACKAGE_VERSION,
                    );
                }
            }
        }
        confirmed
    }

    fn finish(mut self, args: &serde_json::Value, ok: bool) {
        if !self.consume_confirmed() {
            ledger_note_attribution(self.attribution, self.model, self.name, args, ok);
        }
        self.finished = true;
    }
}

impl Drop for AttributionEpoch<'_> {
    fn drop(&mut self) {
        if !self.finished {
            // Covers a confirmed publication before an error or cancellation
            // skips normal result accounting. A confirmation arriving only
            // after this scope has gone can conservatively leave old credit;
            // it must never clear credit speculatively during preparation.
            self.consume_confirmed();
        }
    }
}

/// Drain operator steering into `messages` as genuine user turns (#952/#1669).
///
/// Called at the top of every tool round, after the cancel checkpoint and
/// before the round's model call, so a correction typed mid-turn is in context
/// for the agent's next reasoning cycle rather than waiting for the round cap.
///
/// The messages are the operator's own words in submission order — not a
/// harness nudge and not system metadata — because that is what they are. They
/// deliberately use the SAME `{"role": "user"}` shape the round-start nudges
/// already push a few lines above each call site, so nothing downstream needs
/// to learn a new message kind.
///
/// Returns how many were delivered, for the caller's trace/telemetry. A no-op
/// returning 0 when no inbox is lent, which is every headless caller.
fn drain_steering_into(
    steering: Option<&dyn SteeringInbox>,
    messages: &mut Vec<serde_json::Value>,
    color: bool,
) -> usize {
    let Some(inbox) = steering else {
        return 0;
    };
    let pending = inbox.drain_for_round();
    for text in &pending {
        messages.push(serde_json::json!({ "role": "user", "content": text }));
    }
    if !pending.is_empty() {
        print_debug(
            &format!("delivered {} operator steering message(s)", pending.len()),
            color,
        );
    }
    pending.len()
}

/// Lexically normalize a path — collapse `.`, resolve `..`, drop empty components —
/// **without** touching the filesystem, so a ledger key built from a raw
/// model-supplied path matches the gate's `read_dir`-normalized path. Purely
/// lexical: it deliberately does not resolve symlinks (the gate never follows them
/// and revert is workspace-boundary-guarded), so it cannot itself escape the tree.
fn lexical_normalize(path: &std::path::Path) -> std::path::PathBuf {
    use std::path::Component;
    let mut out = std::path::PathBuf::new();
    for comp in path.components() {
        match comp {
            Component::ParentDir => {
                // Only pop a real path segment; never climb above a root/prefix.
                if matches!(out.components().next_back(), Some(Component::Normal(_))) {
                    out.pop();
                } else {
                    out.push("..");
                }
            }
            Component::CurDir => {}
            other => out.push(other.as_os_str()),
        }
    }
    out
}

#[cfg(test)]
#[path = "mod_tests/retry_ledger_tests.rs"]
mod retry_ledger_tests;

/// True when a backend 400 says the model can't accept a `tools` field.
/// Ollama phrases it `"<model> does not support tools"`; OpenAI-compatible
/// servers vary, so we also accept the looser `"not support tools"`. Used to
/// drop tools and retry once, then keep them off for the turn (deepseek-r1).
fn is_tools_unsupported_error(e: &anyhow::Error) -> bool {
    let s = e.to_string().to_lowercase();
    s.contains("does not support tools") || s.contains("not support tools")
}

/// True when Ollama accepted the `tools` field but its internal XML tool-call
/// parser rejected the model's generated `<function>/<parameter>` markup before
/// returning an assistant message. This is a malformed generation, not proof
/// that the model lacks tool support, so retry with tools still advertised and
/// a corrective nudge instead of disabling tools for the whole turn.
fn is_ollama_tool_xml_error(e: &anyhow::Error) -> bool {
    let s = e.to_string().to_lowercase();
    s.contains("ollama") && s.contains("xml syntax error")
}

fn ollama_tool_xml_retry_nudge() -> &'static str {
    "The previous assistant turn failed inside Ollama's XML tool-call parser. \
     Keep using tools, but emit exactly one valid native tool call with well-formed \
     arguments now. Do not answer in prose or wrap the call in explanatory XML."
}

/// Main agentic loop: call model → execute tool calls → feed results back → repeat.
/// Returns `(reply_text, was_streamed, token_usage, hallucination_count)`.
/// When `was_streamed` is true the text was already printed token-by-token.
///
/// Token-usage semantics (Step 18.1): `input_tokens` is the **largest single
/// prompt** the backend evaluated across the turn's rounds — the truthful
/// "how full did the context get" figure that feeds the capability ratchet —
/// NOT the per-round sum, which double-counts history (every round's prompt
/// re-includes all prior rounds; the B3 baseline measured 5.4× inflation).
/// `output_tokens` is the sum across rounds (each completion is new).
/// `true` once the caller's interrupt flag is set (Esc / Ctrl-C). Cheap relaxed
/// load — the flag is a one-way latch, so no ordering guarantees are needed.
fn is_cancelled(cancel: Option<&std::sync::atomic::AtomicBool>) -> bool {
    cancel.is_some_and(|c| c.load(std::sync::atomic::Ordering::Relaxed))
}

/// Take down any completed-spill viewport before the turn writes anything new.
///
/// The viewport's erase rewinds relative to the cursor, so it MUST come down
/// before the next canonical line (round dispatch → spinner detail / retry
/// indicator / streamed text, or the next tool header) lands below it and
/// breaks the rewind math. The committed excerpt above the frame is the
/// durable record, so dismissal loses nothing. Idempotent — an inner
/// recovery-loop retry re-calling this is a no-op.
fn dismiss_completed_spill(renderer: &Option<std::sync::Arc<dyn CompletedSpillRenderer>>) {
    if let Some(renderer) = renderer {
        renderer.erase();
    }
}

/// Resolve as soon as the interrupt flag is set, polling at ~50 ms — fine for a
/// human keypress and cheap enough to lose the race to any real I/O future.
/// Never resolves when `cancel` is `None`, so a `select!` against it collapses
/// to just the other arm (no behavior change for headless callers).
async fn cancelled(cancel: Option<&std::sync::atomic::AtomicBool>) {
    match cancel {
        None => std::future::pending().await,
        Some(flag) => {
            // Poll briskly so an interrupt is felt promptly (well under the
            // ~100 ms human threshold) — the cost is negligible next to a model
            // round-trip.
            while !flag.load(std::sync::atomic::Ordering::Relaxed) {
                tokio::time::sleep(std::time::Duration::from_millis(15)).await;
            }
        }
    }
}

/// Race a model future against the interrupt flag: `Some(v)` if it finished,
/// `None` if the user interrupted first (the future is dropped, cancelling any
/// in-flight request).
async fn cancellable<F: std::future::Future>(
    cancel: Option<&std::sync::atomic::AtomicBool>,
    fut: F,
) -> Option<F::Output> {
    tokio::select! {
        biased;
        _ = cancelled(cancel) => None,
        v = fut => Some(v),
    }
}

fn present_synthetic_tool_result<W: std::io::Write>(
    display: &mut display::ToolDisplay<W>,
    name: &str,
    args: &serde_json::Value,
    workspace: &std::path::Path,
    result: &str,
) {
    // Presentation-only (a completed result being re-rendered, not a live
    // dispatch decision) — the real authority was already enforced when
    // this call originally ran, so an unrestricted fence here costs
    // nothing and avoids threading `Caveats` through a display-only path.
    let (name, detail) =
        tools::tool_presentation(name, args, workspace, &crate::caveats::Scope::All);
    display.call(&name, &detail);
    display.result(result);
}

fn print_synthetic_tool_result(
    name: &str,
    args: &serde_json::Value,
    workspace: &str,
    result: &str,
    color: bool,
    completed_spill_renderer: &Option<std::sync::Arc<dyn CompletedSpillRenderer>>,
) {
    // A completed viewport from an earlier tool in the SAME batch may still
    // be painted; this synthetic block's header must not land below it (the
    // same erase-first discipline as the wired ToolDisplay::call). Dismissing
    // here rather than wiring the renderer in keeps synthetic results
    // static-only — an audit line does not need an interactive viewport.
    dismiss_completed_spill(completed_spill_renderer);
    let mut tool_display = display::ToolDisplay::new(
        io::stdout(),
        color,
        display::term_cols(),
        display::spill_lines(),
        display::spill_summary(),
    );
    present_synthetic_tool_result(
        &mut tool_display,
        name,
        args,
        std::path::Path::new(workspace),
        result,
    );
}

/// The legacy `animate` / `show_thinking` gate expressed as a [`LineCaps`]
/// override.
///
/// **Temporary, by design.** The real gate is `LineCaps::detect()`, which
/// requires two real terminals; `animate` is `color && thinking_stream_enabled()`
/// and never checked a TTY at all. Passing the legacy answer through the
/// arbiter's override seam keeps *when* the spinner appears bit-for-bit
/// identical while *how* it is drawn, ticked and erased moves onto the shared
/// implementation. Protocol mode still vetoes absolutely, so the override can
/// never re-open the JSON-RPC hazard.
///
/// Retiring this — so `thinking = "off"` informs the opt-out only and capability
/// is decided in one place — is the final step of the migration.
fn legacy_caps(animate: bool) -> crate::tty::LineCaps {
    if animate {
        crate::tty::LineCaps::Own
    } else {
        crate::tty::LineCaps::None
    }
}

/// Announce that a validated tool call is about to run.
///
/// The one semantic tool-activity signal for every wire (chat-completions,
/// OpenAI, Anthropic, Responses): integrations learn what the agent is doing
/// from the agent, not by scraping rendered output. Free when nobody is
/// listening — the name is only allocated for a live observer.
fn announce_tool_activity(name: &str) {
    if crate::lifecycle::observed() {
        crate::lifecycle::emit(crate::lifecycle::LifecycleEvent::ToolActivity {
            tool: name.to_string(),
        });
    }
}

/// U4b: the no-progress brake's start-of-round gate, shared by every loop arm
/// that owns rounds (the SAME place the read-only nudge lives: the arm's
/// `WorkflowRuntimeState`). A steer is one user message, allowed only when nudges
/// are (`$steer_allowed`); the STOP is a cost bound and always applies. A stop
/// ends the turn as a typed `NoProgress` with a harness-written notice and NO
/// model summary call (a summary before the round cap would break BHV-ROUND-002).
/// Under the smart harness the stop is recorded like a cap exit (`$record`, then
/// `outcome`), so the frame stays consistent.
macro_rules! no_progress_gate {
    (
        $runtime:expr, $steer_allowed:expr, $messages:expr, $end_reason:expr,
        $solve_obs:expr, $usage:expr, $halluc:expr, $smart:expr, ($workspace:expr, $read:expr, $evidence:expr, $disclosure:expr, $claims:expr, $verification:expr), |$h:ident| $record:expr
    ) => {
        match $runtime.no_progress_verdict($steer_allowed) {
            NoProgress::Continue => {}
            NoProgress::Steer(text) => {
                $messages.push(serde_json::json!({ "role": "user", "content": text }));
            }
            NoProgress::Stop => {
                let notice = finalize_final_text(FinalReply::harness($runtime.no_progress_notice()), $workspace, $read, $evidence, $disclosure, $claims, $verification);
                if let Some($h) = $smart {
                    $record;
                    $h.outcome(crate::TurnEndReason::NoProgress, &notice)?;
                }
                if let Some(slot) = &mut $end_reason {
                    **slot = Some(crate::TurnEndReason::NoProgress);
                }
                observability::observe_harness_reply(&mut $solve_obs);
                return Ok((notice, false, $usage, $halluc));
            }
        }
    };
}

pub async fn chat_complete(
    ctx: ChatCtx<'_>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    chat_complete_with_prompt(ctx, None, None, mcp).await
}

/// Provenance-aware variant of [`chat_complete`]. Callers with a durable
/// receipt and conversation-fenced resolver pass them here; legacy/headless
/// callers retain source compatibility through [`chat_complete`] and receive
/// one stable in-memory receipt synthesized for the turn.
pub async fn chat_complete_with_prompt(
    ctx: ChatCtx<'_>,
    turn_prompt_context: Option<&crate::TurnPromptContext>,
    prompt_source: Option<&dyn PromptSource>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    chat_complete_with_prompt_and_artifacts(
        ctx,
        turn_prompt_context,
        prompt_source,
        None,
        None,
        mcp,
    )
    .await
}

/// Prompt- and artifact-aware variant used by the interactive harness.
///
/// The separate source/sink arguments keep legacy embedders source-compatible
/// while letting persistent and ephemeral TUI sessions expose the same
/// append-only artifact surface. Both implementations are bound to the active
/// conversation before they reach this function.
pub async fn chat_complete_with_prompt_and_artifacts(
    ctx: ChatCtx<'_>,
    turn_prompt_context: Option<&crate::TurnPromptContext>,
    prompt_source: Option<&dyn PromptSource>,
    artifact_source: Option<&dyn artifact_read::ArtifactSource>,
    artifact_sink: Option<&dyn artifact_read::PromptArtifactSink>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    // #2312: the one dispatch entry refuses an unusable explicit allowance
    // before any wire is chosen, for every host.
    validate_output_allowance(ctx.output_allowance, ctx.num_ctx)?;
    // Anthropic speaks its own wire (/v1/messages) — request, tool_use, and
    // usage shapes all differ — so it gets its own loop (the fourth parallel
    // loop beside Ollama / Chat Completions / Responses).
    if ctx.kind == crate::BackendKind::Anthropic {
        return anthropic_chat_complete_with_prompt_and_artifacts(
            ctx,
            turn_prompt_context,
            prompt_source,
            artifact_source,
            artifact_sink,
            mcp,
        )
        .await;
    }
    // OpenAI-compatible endpoints speak a different wire format (request,
    // tool_calls, and usage shapes all differ), so they get their own loop.
    if ctx.kind == crate::BackendKind::Openai {
        // A backend with `api = "responses"` speaks the newer Responses API
        // (gpt-5-codex et al., served only there); the default stays on
        // /v1/chat/completions.
        if ctx.openai_api == crate::OpenAiApi::Responses {
            return openai_responses_complete_with_prompt_and_artifacts(
                ctx,
                turn_prompt_context,
                prompt_source,
                artifact_source,
                artifact_sink,
                mcp,
            )
            .await;
        }
        return openai_chat_complete_with_prompt_and_artifacts(
            ctx,
            turn_prompt_context,
            prompt_source,
            artifact_source,
            artifact_sink,
            mcp,
        )
        .await;
    }
    let ChatCtx {
        shell_dialect,
        command_budget,
        verify_outcomes,
        smart_harness,
        url,
        model,
        kind: _,
        api_key,
        messages: mem_messages,
        task,
        workspace,
        default_command_cwd,
        worktree_session,
        color,
        markdown: _,
        tool_offload,
        spill_store,
        disclosure,
        compaction_store,
        scratchpad,
        scratchpad_store,
        code_search,
        where_is,
        nav,
        exposure,
        experience_store,
        step_ledger,
        caveats,
        persona_tools,
        // Ollama has no Chat Completions capability projection. Bound these
        // fields to `_` so its request body remains unchanged.
        cognition: _,
        chat_completions_capability: _,
        responses_capability: _,
        openai_api: _,
        output_allowance,
        overflow_retry: _,
        attempt_ledger,
        reasoning_replay_scope: _,
        max_tool_rounds,
        workflow_grace_rounds,
        narration_nudge_cap,
        action_nudges,
        prompt_disposition,
        prompt_intake,
        tool_output_lines,
        debug,
        trace,
        num_ctx,
        connect_timeout_secs,
        inference_timeout_secs,
        mid_loop_trim_threshold,
        compaction_trigger_policy,
        mid_loop_trim_tokens,
        max_ok_input,
        build_check_cmd,
        safe_context,
        recover_cw_400,
        mut note_sink,
        mut note_nudge,
        recall_source,
        memory_source,
        summarizer,
        compress_state,
        mut tool_events,
        mut phantom_reaches,
        mut end_reason,
        mut round_cap_hit,
        mut solve_obs,
        mut permission_gate,
        mut on_round_usage,
        estimate_ratio,
        estimation,
        summary_input_cap_floor_chars,
        rewrites_history,
        input_ceiling_pct,
        low_budget_pct,
        exec_floor,
        write_ledger,
        attribution,
        cancel,
        run_allowance,
        live_tool_output,
        completed_spill_renderer,
        git_tool,
        crew_runner,
        operating_mode_control,
        plan_mode_control,
        plan_draft_sink,
        steering,
        emits_leading_reasoning,
    } = ctx;
    // Any completed viewport this turn paints must not outlive the turn's
    // bookkeeping: on EVERY exit (return, `?`, cancel, panic) the guard
    // discards it — without terminal writes — so a stale rewind can never
    // replay over a later turn's prompt.
    let _completed_spill_guard = CompletedSpillDismissGuard(&completed_spill_renderer);
    // Explain / Research / Ask turns may still use bounded read-only tools, but
    // must never inherit the harness's execution-pressure repairs.
    let action_nudges = action_nudges && prompt_disposition == PromptDisposition::Act;
    if let Some(harness) = smart_harness {
        harness.start_turn()?;
    }
    // Smart mode retains full tool output before the existing shell cap runs.
    let spill_store = smart_harness.map(|h| h.spill_store()).or(spill_store);
    let tool_offload = tool_offload || smart_harness.is_some();
    let smart_verify = action_nudges && prompt_disposition == PromptDisposition::Act;
    let action_nudges = action_nudges && smart_harness.is_none();
    let max_tool_rounds = prompt_disposition.tool_round_limit(max_tool_rounds);
    // Headless callers may pass no session state — compression still works,
    // with per-turn anti-thrash accounting.
    let mut local_compress_state = CompressState::new();
    let compress_state = match compress_state {
        Some(s) => s,
        None => &mut local_compress_state,
    };
    // Ollama Cloud speaks the same wire as LAN Ollama but behind bearer auth.
    // The key is baked into the client's default headers so every request on
    // this path (the round probe, `/api/show`, the cap-exit summary)
    // authenticates — a per-site `.bearer_auth()` would be the N-call-sites
    // trap (#1312) that produced the silent 401 this fixes.
    let auth = ollama_auth_headers(api_key);
    let client = reqwest::Client::builder()
        .default_headers(auth)
        .connect_timeout(std::time::Duration::from_secs(connect_timeout_secs))
        .timeout(std::time::Duration::from_secs(inference_timeout_secs))
        .build()?;
    let chat_url = format!("{}/api/chat", url.trim_end_matches('/'));
    let retry = tui_retry_policy(url);
    // The save_note tool is advertised only when a sink exists (Step 19.3);
    // recall only when a source exists (Step 17.5); memory_fetch only when a
    // memory source exists (#319) — same presence gating.
    let advertise_save_note = note_sink.is_some();
    let advertise_recall = recall_source.is_some();
    let advertise_memory_fetch = memory_source.is_some();
    // Step 26.4 (#583): state tools only when the feature is on AND a store exists.
    let advertise_scratchpad = scratchpad_store.is_some() && scratchpad;
    // Step 26.5.5 (#582): the code_search tool when a searcher is present.
    let advertise_code_search = code_search.is_some();
    // Step 26.6a (#585): the experiential tools when a store is present.
    let advertise_experiential = experience_store.is_some();
    // Step 26.6b (#586): the scheduled plan tools when a ledger is present.
    let advertise_scheduled = step_ledger.is_some();
    // Native Git is the default interface; the injected adapter remains internal.
    let advertise_git = false;
    let advertise_team = crew_runner.is_some();
    let advertise_operating_mode = operating_mode_control.is_some();
    let advertise_plan_mode = plan_mode_control.is_some();
    let advertise_plan_mode_active =
        plan_mode_control.is_some_and(|control| control.is_plan_mode());

    // Convert MemMessage list to Ollama JSON format.
    // The memory manager already included the current task as the last user message.
    let mem_messages = observed_report::replay_messages(mem_messages);
    let mut messages: Vec<serde_json::Value> = mem_messages
        .iter()
        .map(|m| serde_json::json!({"role": m.role.as_str(), "content": m.content}))
        .collect();
    if let Some(harness) = smart_harness {
        messages = harness.initial_messages(messages)?;
    }
    if let (Some(session), Some(context)) = (worktree_session, turn_prompt_context) {
        session
            .report
            .lock()
            .expect("report state")
            .begin(context.active().root_prompt_id());
    }
    let ephemeral_prompt = prompt_read::headless_prompt_fallback(turn_prompt_context, task);
    let turn_prompt_context = turn_prompt_context.or(ephemeral_prompt.as_ref());
    let prompt_context =
        prompt_read::PromptReadContext::new(turn_prompt_context, task, prompt_source);
    let artifact_context = turn_prompt_context
        .map(|turn| artifact_read::ArtifactReadContext::from_turn(turn, artifact_source));
    let active_task = prompt_context.active_text();
    prompt_read::ensure_active_prompt_card(&mut messages, prompt_context, prompt_intake);
    // #2313: one ledger attempt per primary request, keyed at the send.
    let attempt_turn = turn_prompt_context
        .map(|turn| turn.active_operator_prompt().id().to_string())
        .unwrap_or_default();
    // An explicit inference budget applies even without an audit sink.
    let fallback_ledger = std::sync::Mutex::new(crate::attempts::AttemptLedger::default());
    let attempt_ledger = attempt_ledger.or_else(|| run_allowance.map(|_| &fallback_ledger));
    let attempts = attempt_ledger.map(|ledger| attempt_capture::AttemptScope {
        ledger,
        turn: &attempt_turn,
        model,
        backend: url,
        cancel,
        run_allowance,
    });

    // In-band memory nudge (Step 19.3): after `[memory] note_nudge_interval`
    // user turns with zero organic save_note use, append a one-line reminder
    // to this turn's user message. Only when a sink exists — without one the
    // save_note tool isn't even advertised.
    if note_sink.is_some() {
        if let Some(line) = note_nudge.as_deref_mut().and_then(NoteNudge::begin_turn) {
            if let Some(harness) = smart_harness {
                harness.host_message(&line)?;
                messages.push(serde_json::json!({"role":"user", "content":line}));
            } else {
                append_nudge_line(&mut messages, &line);
            }
        }
    }

    let mut accumulated_usage: Option<crate::TokenUsage> = None;
    let mut hallucination_count: u32 = 0;
    // Step 27.3/#771: guard against exact-repeat tool loops this run.
    // #2315: result-aware verification for this turn, decided once.
    let result_aware = self_verify::enabled() && verify_outcomes;
    let mut repeat_calls = RepeatCallGuard::default();
    // Plan-before-act: the ledger as this turn began (see `PlanRoundFacts`).
    let plan_at_turn_start = step_ledger
        .map(|ledger| ledger.snapshot())
        .unwrap_or_default();
    let mut read_history = tools::ReadHistory::default();
    // #2315: what each check actually did, fed at the per-tool-result funnel.
    let mut verification = self_verify::VerificationLedger::for_turn(task, result_aware);
    // #2683: HEAD before this turn's own tool calls run, so a "committed"
    // claim in the final report can be checked against whether HEAD actually
    // moved. `None` (off-repo, or the read scope refuses the probe) must
    // never manufacture a false refutation — see `claim_check::TurnGitEvidence`.
    let turn_claims =
        claim_check::TurnClaims::capture(workspace, &caveats.fs_read, worktree_session)
            .with_evidence(observed_report::review::Evidence {
                sink: artifact_sink,
                context: artifact_context,
                spill: spill_store,
            });
    // #1948: DETECTION beside the guard — it notices a clean-then-build
    // loop and says so once; it never blocks or rewrites the call.
    let mut clean_build = crate::loop_watch::CleanBuildWatch::default();
    let mut overflow_retries: u32 = 0;
    let mut suspicious_empty_retries: u32 = 0;
    // Consecutive context-window recoveries (parse limit → trim → retry).
    let mut cw_retries: u32 = 0;
    let mut output_recovery = output_limit_recovery::Recovery::default();
    // Some models reject ANY request carrying a `tools` field (e.g.
    // deepseek-r1). Once one 400s with "does not support tools", drop tools for
    // the rest of the session so even a bare "hello" works; notice it once.
    let mut tools_supported = true;
    let mut tools_unsupported_notified = false;
    // Pre-send token budget gate: trim before dispatch when the current context
    // size exceeds the model's empirically-confirmed max input (or the safe
    // context) — capped by the `num_ctx` every request this turn will carry
    // (#282: on a fresh capability cache the cached numbers are unset or huge,
    // so without the ceiling the first turn dispatched 10× over the real
    // window with zero events — B6). Mutable because a recovered 400 tightens
    // it mid-turn. See #223.
    // #2312: no cognition table on this wire — only an explicit allowance reserves.
    let mut effective_input_ceiling =
        num_ctx_input_ceiling(num_ctx, input_ceiling_pct, output_allowance);
    // An explicit allowance rides every request as `num_predict`.
    let ollama_options = ollama_options(num_ctx, output_allowance);
    observability::observe_output_allowance(
        &mut solve_obs,
        output_allowance,
        output_allowance.is_some(),
    );
    let mut send_budget: Option<usize> =
        initial_send_budget(max_ok_input, safe_context, effective_input_ceiling);
    // Step 20.3: is the send budget backed by an authoritative ceiling, or
    // does it rest on the proven-good high-water mark (`max_ok_input`) alone?
    // `safe_context` (a believed/declared window) and the per-request
    // `num_ctx` ceiling are authoritative; a cw-400 recovery flips this true
    // mid-turn. Cloud endpoints with no `/api/show` seed neither, so their
    // guard is non-authoritative and fails open instead of refusing.
    let mut send_budget_authoritative = safe_context.is_some() || effective_input_ceiling.is_some();
    // Tool schemas ride along in every request body; count them once (18.1).
    // Stable for the whole turn: the builtin + MCP tool set doesn't change
    // mid-turn, so hoisting out of the round loop is safe.
    let tools = merged_tool_definitions(
        mcp,
        advertise_save_note,
        advertise_recall,
        advertise_memory_fetch,
        advertise_git.then_some(&caveats.fs_read),
        advertise_team,
        advertise_scratchpad,
        advertise_code_search,
        advertise_experiential,
        advertise_scheduled,
        advertise_operating_mode,
        advertise_plan_mode,
        advertise_plan_mode_active,
        command_budget,
        shell_dialect,
    );
    // Put the persona's preferred tools first without removing other tools.
    // Dispatch separately checks explicit permissions and delegation authority.
    let tools = filter_advertised_tools(tools, persona_tools);
    let tools = filter_tools_for_disposition(
        smart_harness::advertise(tools, smart_harness),
        prompt_disposition,
    );
    // #TEC Pass 1: the exposure stage. Clip the AUTHORIZED catalog to what the
    // model's LIVE usable budget can afford (probed `safe_context` → send
    // budget), never by model name. `ExposureProfile::Full` (the default) is
    // identity, so this is bit-for-bit unchanged unless `[tool_exposure]` opts
    // in. Applied before the token estimate so what we count equals what we
    // send. Dispatch still authorizes on the full set — exposure ≠ authority.
    let (mut tools, hidden_tools) = crate::agentic::tools::select_exposed(
        tools,
        &exposure,
        exposure_budget_tokens(send_budget, safe_context),
        &std::collections::BTreeSet::new(),
        estimation,
    );
    let mut tool_tokens = estimate_value_tokens(&tools, estimation);
    // Price the stable tool catalog in real-token space. Reprice it whenever
    // usage or an overflow updates the session's calibration.
    let mut cal = compress_state.calibration.ratio(estimate_ratio);
    let mut tool_tokens_real = calibrate_up(tool_tokens, cal);
    preflight_irreducible_request(
        &messages,
        Some(&tools),
        authoritative_request_budget(send_budget, send_budget_authoritative, mid_loop_trim_tokens),
        cal,
        estimation,
        model,
    )?;
    // Animate the in-place "thinking…/compressing…" status line only on a TTY
    // with streaming enabled (never in a pipe / `newt worker`). Constant for the
    // turn — both the compression and probe waits reuse it.
    let animate = color && thinking_stream_enabled();
    // Truthful context-size tracker: anchors on the backend's last-reported
    // prompt token count, chars/4 + schema estimate as fallback (Step 18.1).
    let mut prompt_tracker = PromptTracker::new();
    let today = chrono::Local::now().format("%Y-%m-%d").to_string();
    // Consecutive rounds where the model only called read-only tools (no writes).
    // When this hits READ_ONLY_NUDGE_AFTER, a brief injected message tells the
    // model to stop exploring and start writing.
    let mut read_only_rounds: usize = 0;
    // "Narrate-then-stop" rescue: a weak model often ANNOUNCES its next action
    // in prose ("Let me edit …") and emits no tool call. The loop would treat
    // that zero-tool round as a final answer and end the turn, forcing a human
    // "continue". `narration_nudges` bounds the auto-continue that instead
    // nudges the model to actually call the tool (≤ `narration_nudge_cap` per
    // turn); the trigger is the configurable NudgeClassifier, so a genuine
    // conclusion (with or without prior tool calls this turn) is never nudged.
    let mut narration_nudges: usize = 0;
    let mut readonly_completion_retried = false;
    // State-driven final-answer gate: a no-tool reply is suspicious when the
    // active plan still has open steps. Nudge once to update_plan / act / block.
    let mut pending_plan_nudges: usize = 0;
    // A stricter sibling: when a model concludes "the file changed under me"
    // without proving it, force one read-only ground-truth check round instead
    // of letting it hand the stale-context claim back to the human.
    let mut stale_file_nudges: usize = 0;
    let mut unverified_exec_blocker_nudges: usize = 0;
    let mut run_command_denial_observed = false;
    // #2628: the args of the most recently denied run_command — cleared when
    // request_permissions consumes and re-runs it, or on the next turn.
    let mut pending_rerun: Option<tools::PendingRerun> = None;
    let mut capability_evidence = capability_check::Evidence::default();
    let mut probe_correction_used = false;
    let nudge_classifier = crate::NudgeClassifier::load_default();
    // #1152/#1162: action-pressure nudges (narration rescue, workflow repair
    // steering, pending-plan pushes) fire ONLY when the user's turn actually
    // invited action. A question or acknowledgment gets none — narration IS
    // the deliverable, and pressuring a model answering a question is how the
    // "I'm genuinely finished" defense loop (#1158) gets seeded.
    let action_turn = action_nudges && crate::classifiers::user_turn_invites_action(active_task);
    // The exec-denial ground-truth retry trusts the harness-validated Act
    // disposition. The generic narration nudges keep their narrower
    // leading-verb classifier, but a compound action question must not disable
    // the capability-wall correction merely because prose precedes its verb.
    let exec_grounding_turn = action_nudges && prompt_disposition == PromptDisposition::Act;
    let workflow_steerer = crate::WorkflowSteerer::load_default();
    let mut workflow_runtime = WorkflowRuntimeState {
        initiative: crate::initiative::effective_initiative(),
        no_progress: crate::initiative::installed_no_progress(),
        ..Default::default()
    };
    // The matching workflow's round-cap grace horizon override, resolved once
    // from the turn's opening context (diagnostic workflows need more
    // read-only rounds between checkpoints than routine edits — see
    // `diagnose_failure.toml`'s `progress_horizon_rounds`).
    workflow_runtime.set_progress_horizon(
        workflow_steerer.progress_horizon(&workflow_classifier_text(&messages, "")),
    );
    let mut ollama_xml_retry_nudges: usize = 0;
    // Phase 20 §2.2: the thinking-only quirk is reported at most once per
    // turn — re-detection adds no information and would thrash the cache.
    let mut thinking_only_reported = false;
    // #867 Part A: ledger of REAL workspace paths surfaced by tool results,
    // collected as the rounds happen so it survives the cap-exit trim.
    let mut observed_paths = claim_check::ObservedPaths::default();
    let mut observed_resolver = claim_check::workspace_resolver(workspace);

    // All providers use the same progress-backed renewable allowance.
    // A zero grace setting keeps the operator's round cap hard.
    let mut current_tool_round_limit = max_tool_rounds;
    // #1965: the turn's only whole-turn wall-clock signal. The evidenced
    // 32-minute turn emitted none — this file has per-tool `Instant` timers
    // and nothing watching the turn as a whole.
    let turn_started = std::time::Instant::now();
    let mut turn_heartbeat = TurnHeartbeat::default();
    let mut selected_source = selected_target::Projection::default();
    let mut observed_facts = semantic_pins::Projection::default();
    'round_loop: for round in 0..usize::MAX {
        let round = round.saturating_sub(output_recovery.skipped_rounds);
        selected_source.refresh(
            &mut messages,
            step_ledger,
            workspace,
            &caveats.fs_read,
            worktree_session,
            false,
        );
        observed_facts.planning = output_budget::guidance(
            output_allowance,
            step_ledger,
            &selected_target::root(workspace, worktree_session),
            &caveats.fs_read,
            estimation,
        );
        semantic_pins::refresh(
            &mut observed_facts,
            smart_harness,
            &mut messages,
            prompt_context,
            selected_source.current(),
            &turn_claims,
            workspace,
            &caveats.fs_read,
        )?;
        // #2331: a call to an authorized tool whose schema was off the wire
        // promoted it; its schema rides every request from here on.
        if hidden_tools.append_promoted(&mut tools) {
            tool_tokens = estimate_value_tokens(&tools, estimation);
            tool_tokens_real = calibrate_up(tool_tokens, cal);
        }
        // Bounded to ONE line per interval, and the policy is pure over the
        // elapsed it is handed — this reads the clock, `due` does not.
        let turn_elapsed = turn_started.elapsed();
        if let Some(line) = turn_heartbeat.notice(turn_elapsed, round, current_tool_round_limit) {
            print_newt(&line, color, false);
        }
        // FIRST statement of every round: the previous round's completed
        // viewport must come down before ANY canonical line this round can
        // print — the grace-window debug note, the round separator, the
        // compression notices, the cancel checkpoint's return to a caller
        // that prints. Erasing here is safe precisely because nothing has
        // written since the frame was painted.
        dismiss_completed_spill(&completed_spill_renderer);
        if !workflow_runtime.admit_round(
            round,
            &mut current_tool_round_limit,
            workflow_grace_rounds,
        ) {
            break;
        }
        // Interrupt checkpoint (Esc / Ctrl-C): bail before spending another
        // round on the model or a tool. The reply is empty — the caller sees
        // `cancel` set and treats the turn as abandoned regardless.
        if is_cancelled(cancel) {
            return Ok((
                smart_harness::cancelled(smart_harness, &mut end_reason)?,
                false,
                accumulated_usage,
                hallucination_count,
            ));
        }
        // #952/#1669: operator steering, delivered BEFORE this round's model
        // call and AFTER any tool that was already running finished above.
        // Steering changes what the agent does NEXT; it never abandons the
        // turn (that is `cancel`, checked immediately above).
        if drain_steering_into(steering, &mut messages, color) > 0 {
            workflow_runtime.note_operator_steering();
        }
        if round > 0 {
            // Brief separator between rounds so user can follow the flow.
            if color {
                execute!(
                    io::stdout(),
                    SetForegroundColor(CtColor::DarkGrey),
                    Print("…\n"),
                    ResetColor
                )
                .ok();
            }
        }

        // Conditional plan re-seat (#630 b): re-show the ACTIVE step each round
        // so a weak model doesn't lose track of a multi-step plan as the round-0
        // <plan> snapshot goes stale (validated on dgx1: re-seat 12/12 vs baseline
        // 8/12 under drift). Compact + gated to multi-step in-progress plans.
        // Supersedes the env-gated NEWT_RESEAT_PLAN experiment that #629 carried
        // to main by accident.
        // U4b: the brake's gate runs EVERY round, outside the nudge gate: nudges may
        // be off, a bound may not (only the steer honours `action_nudges`).
        if round > 0 {
            no_progress_gate!(
                workflow_runtime,
                action_nudges,
                messages,
                end_reason,
                solve_obs,
                accumulated_usage,
                hallucination_count,
                smart_harness,
                (
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification
                ),
                |harness| harness.record_messages(&messages)?
            );
        }
        if round > 0 && action_nudges {
            if let Some(ptr) = step_ledger.and_then(plan_reseat_pointer) {
                messages.push(serde_json::json!({ "role": "user", "content": ptr }));
            }
        }

        // Read-only round nudge: if the model has spent several consecutive
        // rounds only reading (list_dir / read_file / web_fetch / search /
        // use_skill) without writing anything, inject a brief reminder to
        // stop exploring and call edit_file or write_file.  This breaks the
        // "endless exploration → empty response" failure mode seen with some
        // local models (e.g. nemotron3:33b).
        // Use the turn's captured level and configured rounds, matching the
        // other action-nudge loops without changing this counter's timing.
        let read_only_nudge_after = workflow_runtime.initiative.read_only_nudge_after();
        if action_nudges && read_only_rounds >= read_only_nudge_after {
            let remaining = (workflow_grace_rounds == 0)
                .then_some(current_tool_round_limit.saturating_sub(round + 1));
            // Sustained read-only exploration on a task that classifies as a
            // diagnose/fix workflow is exactly the shape `crew`/`team`
            // delegation exists for — offer it here (only when sub-agent
            // dispatch is actually available this session) instead of only
            // ever telling the model to act inline.
            let delegate_hint = workflow_steerer
                .delegate_hint(&workflow_classifier_text(&messages, ""), advertise_team);
            messages.push(serde_json::json!({
                "role": "user",
                "content": read_only_action_nudge(
                    read_only_rounds,
                    remaining,
                    step_ledger,
                    delegate_hint.as_deref(),
                )
            }));
            read_only_rounds = 0;
        }

        // Context compression (Step 18.4, #247): one shared pipeline —
        // structural prune → boundary → redacted LLM summary → marker
        // assembly — serves both the mid-loop trigger (message count OR
        // current tokens: the VRAM guard and issue #223's token guard) and
        // the pre-send budget guard (`max_ok_input`/`safe_context`). The
        // current-token figure is prompt-tokens-preferred (Step 18.1). The
        // old amputation trim survives only as the pipeline's no-summarizer
        // static-marker path.
        {
            // Phase 20 §2.3: `current` is calibrated into real-token space —
            // the same currency as the (backend-derived) send budget and the
            // configured token threshold it is compared against.
            let advertised_tools = tools_supported.then_some(&tools);
            let current = full_message_request_pressure_tokens(
                prompt_tracker.current(&messages, advertised_tools, cal, estimation),
                &messages,
                advertised_tools,
                cal,
                estimation,
            );
            // The count-only budget is priced in message-token space — the
            // same chars/4 currency the pipeline compares its budget against
            // (F1); `current` (schema/template-inclusive) still drives the
            // token triggers.
            let message_tokens = estimate_tokens(&messages, estimation);
            // A learned `max_ok_input` alone is a proven-good floor, not a
            // context-window ceiling. Only a configured token cap or a
            // budget backed by a known/recovered window suppresses a
            // count-only compaction under the default policy.
            let has_authoritative_headroom = count_guard_has_headroom(
                current,
                authoritative_request_budget(
                    send_budget,
                    send_budget_authoritative,
                    mid_loop_trim_tokens,
                ),
                max_ok_input,
            );
            if let Some(trigger) = compression_trigger(
                messages.len(),
                current,
                message_tokens,
                CompressionTriggerLimits {
                    count_threshold: mid_loop_trim_threshold,
                    token_threshold: mid_loop_trim_tokens,
                    send_budget,
                    tool_tokens: tool_tokens_real,
                    policy: compaction_trigger_policy,
                    has_authoritative_headroom,
                },
            ) {
                // A hard trigger's budget is real-token currency; the
                // pipeline measures and reclaims in chars/4 — convert once
                // (Phase 20 §2.3). Count-only budgets are already priced in
                // message-token space (F1) and pass through unconverted.
                let pipeline_budget = if trigger.hard_budget {
                    calibrate_down(trigger.budget, cal)
                } else {
                    trigger.budget
                };
                // Step 20.3: does this budget rest on an authoritative ceiling
                // or the lone proven-good HWM? A fired token threshold is
                // user-authoritative; otherwise the guard fired, authoritative
                // only when the send budget is backed by a believed window.
                let token_fired = mid_loop_trim_tokens.is_some_and(|t| t > 0 && current > t);
                // Compression makes its own summarizer model call — animate the
                // line with a "compressing context…" stage so it doesn't sit
                // frozen, and race it against the interrupt flag so Esc bails
                // out of a slow summarize instead of waiting for it to finish.
                let outcome = match crate::tty::with_spinner(
                    legacy_caps(animate),
                    "compressing context…",
                    crate::tty::Sink::Stdout,
                    color,
                    cancellable(
                        cancel,
                        smart_harness::compress(
                            CompressRequest {
                                messages: &messages,
                                budget: pipeline_budget,
                                max_messages: trigger.max_messages,
                                replay_protected_tail_len: 0,
                                task: active_task,
                                hard_budget: trigger.hard_budget,
                                authoritative: token_fired || send_budget_authoritative,
                                focus: None,
                                est: estimation,
                                summary_input_cap_floor_chars,
                                rewrites_history,
                                compaction_store,
                                compaction_stage: None,
                            },
                            summarizer,
                            compress_state,
                            smart_harness,
                        ),
                    ),
                )
                .await
                {
                    Some(o) => o?,
                    None => {
                        return Ok((
                            smart_harness::cancelled(smart_harness, &mut end_reason)?,
                            false,
                            accumulated_usage,
                            hallucination_count,
                        ))
                    }
                };
                if let Some(notice) = outcome.notice {
                    print_harness_notice(&notice, color);
                }
                if outcome.action == CompressAction::Refused {
                    // Refuse the send rather than let the backend silently
                    // truncate the task away (baseline B6). The remedy differs by
                    // cause — a poisoned learned budget and an append-only preset
                    // are both known reasons to land here — so the message is
                    // built from `outcome.refusal`, never assumed.
                    anyhow::bail!("{}", refusal_bail_message(outcome.refusal, current, model));
                }
                if outcome.fired {
                    // N2: a hard-budget compression whose assembled result is
                    // still over budget says so before the full-request
                    // preflight below refuses its dispatch. The comparison is
                    // in the SAME (chars/4) currency the pipeline measured
                    // `tokens_after` in (Phase 20 §2.3).
                    let suffix = if trigger.hard_budget && outcome.tokens_after > pipeline_budget {
                        ", still over budget"
                    } else {
                        ""
                    };
                    emit_compression_notice(
                        color,
                        outcome.tokens_before,
                        outcome.tokens_after,
                        outcome.action,
                        suffix,
                    );
                    if debug {
                        print_debug(
                            &format!(
                                "compression: {} → {} messages (budget ~{} tokens, \
                                 +~{tool_tokens} tool-schema tokens ride along)",
                                messages.len(),
                                outcome.messages.len(),
                                pipeline_budget,
                            ),
                            color,
                        );
                    }
                    messages = outcome.messages;
                    prompt_tracker.invalidate();
                    apply_post_compaction_continuation(
                        worktree_session,
                        &mut messages,
                        &mut narration_nudges,
                        outcome.action,
                        step_ledger,
                        prompt_context,
                        round > 0 && action_nudges,
                        |candidate| {
                            preflight_full_message_request(
                                candidate,
                                tools_supported.then_some(&tools),
                                authoritative_request_budget(
                                    send_budget,
                                    send_budget_authoritative,
                                    mid_loop_trim_tokens,
                                ),
                                cal,
                                estimation,
                                model,
                            )
                            .is_ok()
                        },
                    );
                    // Persist provenance only after the transformed working
                    // set and its continuation have been installed.
                    record_compaction_artifact(
                        &mut repeat_calls,
                        artifact_sink,
                        artifact_context,
                        outcome.action,
                        outcome.tokens_before,
                        outcome.tokens_after,
                        pipeline_budget,
                        round,
                        trigger.primary_cause.artifact_reason(),
                        Some(&trigger),
                        send_budget_authoritative,
                        compress_state.floor_trend(),
                        color,
                    );
                }
            }
        }

        // Compression is best-effort; an irreducible fresh result (including
        // spill-exempt prompt_read output) may remain larger than the window.
        // Re-price the exact request after every compression/nudge and refuse
        // before the wire rather than relying on a backend 400 or silent head
        // truncation. Only schemas actually advertised on this request count.
        // #1528: inner recovery loop — a cw-400 (or a tools-unsupported error)
        // retries THIS logical round IN PLACE. Only a COMPLETED dispatch `break`s
        // out and lets `round` advance, so recovery never consumes a tool-capable
        // round (critical at current_tool_round_limit == 1 or near the cap): the recovered
        // request is re-sent WITH tools, never demoted to the tools-disabled summary.
        let probe_started = std::time::Instant::now();
        let (json, round_est_raw): (serde_json::Value, usize) = loop {
            preflight_full_message_request(
                &messages,
                tools_supported.then_some(&tools),
                authoritative_request_budget(
                    send_budget,
                    send_budget_authoritative,
                    mid_loop_trim_tokens,
                ),
                cal,
                estimation,
                model,
            )?;

            // Phase 20 §2.2: chars/4 estimate of EXACTLY the request about to be
            // dispatched (the message list as sent, plus tool schemas) — paired
            // with the backend's reported prompt size in the `Accepted`
            // observation so the caller can learn the calibration ratio.
            let round_est_raw =
                estimate_request_tokens(&messages, tools_supported.then_some(&tools), estimation);

            // Tool-call rounds: stream:false (fast, just JSON).
            // Final text round: stream:true so the user sees tokens arrive.
            // We don't know which round is last, so we probe with stream:false first
            // and switch to streaming only when the model returns no tool calls.
            if let Some(harness) = smart_harness {
                harness.record_messages(&messages)?;
            }
            let mut body_no_stream = serde_json::json!({
                "model": model,
                "messages": messages,
                "stream": false,
                "tools": tools.clone(),
            });
            if let Some(options) = &ollama_options {
                body_no_stream["options"] = options.clone();
            }
            // Drop tools entirely for a model that rejects them (set below on a
            // "does not support tools" 400) — an empty array still trips strict
            // models, so remove the key.
            if !tools_supported {
                if let Some(o) = body_no_stream.as_object_mut() {
                    o.remove("tools");
                }
            }

            // Retry the send+status+parse as one unit — a connection drop at any
            // of these steps is transient and worth retrying with backoff. Raced
            // against the interrupt flag so Esc bails out of a slow / stuck probe
            // (the common "the model isn't answering" case) without waiting for it.
            // Wrapped in the thinking animation so this otherwise-silent wait shows
            // a live hourglass + clock instead of a frozen line.
            let dispatch = match crate::tty::with_spinner(
                legacy_caps(animate),
                "thinking…",
                crate::tty::Sink::Stdout,
                color,
                cancellable(
                    cancel,
                    with_backoff_notify_error(
                        &retry,
                        || async {
                            // W0 (#1511): classify while the error is TYPED — the
                            // DispatchError keeps the historical message text and
                            // carries the structural class to the driver boundary.
                            let (resp, attempt) = attempt_capture::send(
                                attempts,
                                "primary",
                                smart_harness::request(
                                    client.post(&chat_url),
                                    &body_no_stream,
                                    smart_harness,
                                    "ollama",
                                )?,
                                "request failed",
                            )
                            .await?;
                            let json = smart_harness::response(resp, smart_harness, "Ollama")
                                .await
                                .inspect_err(|error| {
                                    attempt_capture::failed(attempt.as_ref(), error);
                                })?;
                            attempt_capture::complete(attempt.as_ref(), ollama_usage(&json));
                            Ok(json)
                        },
                        |attempt, delay, error| {
                            print_retry_indicator(attempt, retry.max_retries, delay, error, color);
                        },
                    ),
                ),
            )
            .await
            {
                Some(d) => d,
                // Interrupted mid-probe: abandon the turn.
                None => {
                    return Ok((
                        smart_harness::cancelled(smart_harness, &mut end_reason)?,
                        false,
                        accumulated_usage,
                        hallucination_count,
                    ))
                }
            };
            match dispatch {
                Ok(j) => {
                    // Success renews recovery attempts, not the learned budget.
                    cw_retries = 0;
                    break (j, round_est_raw);
                }
                Err(e) => {
                    // No-tools recovery: a model that rejects the `tools` field
                    // (deepseek-r1) 400s even on "hello". Drop tools, notice once,
                    // and re-dispatch the same turn — self-limiting because the
                    // rebuilt body omits tools. A malformed XML tool-call error is
                    // different: Ollama accepted tools but choked on the model's
                    // generated markup, so keep tools available and retry with a
                    // bounded corrective nudge.
                    let tools_unsupported = is_tools_unsupported_error(&e);
                    let malformed_xml_tool_call = is_ollama_tool_xml_error(&e);
                    if tools_supported && tools_unsupported {
                        tools_supported = false;
                        if !tools_unsupported_notified {
                            tools_unsupported_notified = true;
                            let notice = format!(
                                "{model} does not support tools — tools disabled for this turn"
                            );
                            print_newt(&notice, color, false);
                        }
                        continue;
                    }
                    if tools_supported && malformed_xml_tool_call && ollama_xml_retry_nudges < 2 {
                        ollama_xml_retry_nudges += 1;
                        print_newt(
                            &format!(
                                "{model} produced malformed Ollama XML tool-call syntax — \
                             retrying with a stricter tool-call nudge"
                            ),
                            color,
                            false,
                        );
                        let nudge = ollama_tool_xml_retry_nudge();
                        if let Some(harness) = smart_harness {
                            harness.host_message(nudge)?;
                        }
                        messages.push(serde_json::json!({"role":"user", "content":nudge}));
                        // Retry the SAME logical round (inner dispatch loop): the
                        // corrective nudge must reach a tool-CAPABLE round, else at
                        // max_tool_rounds == 1 it is only ever sent to the
                        // tools-disabled summary. Bounded by `ollama_xml_retry_nudges`.
                        continue;
                    }
                    // Graceful context-window overflow recovery: parse the model's
                    // real limit, tighten the budget, compress, and retry once (#223;
                    // compress-not-trim since Step 18.4). A numberless overflow with
                    // no parseable limit (llama.cpp served over the Ollama-compat
                    // `/api/chat`) falls back to a cap derived from the current send
                    // budget / the `num_ctx` ceiling, so the turn self-heals.
                    let overflow = cw_overflow::is_context_overflow(&e.to_string());
                    // Record the rejected size BEFORE increasing estimation slack.
                    let refused_tokens = cw_overflow::parse_context_window_error(&e.to_string())
                        .map(|(tokens, _)| usize::try_from(tokens).unwrap_or(usize::MAX))
                        .unwrap_or_else(|| calibrate_up(round_est_raw, cal));
                    if overflow {
                        cal = compress_state.calibration.overflow(cal);
                        tool_tokens_real = calibrate_up(tool_tokens, cal);
                    }
                    if cw_retries < 2 {
                        let recovered_window = recover_cw_400.and_then(|f| f(&e, model, &today));
                        if let Some(recovered_budget) = recovered_window
                            .map(|context_window| {
                                recovered_input_budget(
                                    context_window,
                                    input_ceiling_pct,
                                    output_allowance,
                                    effective_input_ceiling,
                                )
                            })
                            .or_else(|| {
                                cw_overflow::core_recover_overflow(
                                    &e.to_string(),
                                    send_budget,
                                    effective_input_ceiling,
                                )
                                .map(|cap| cap as usize)
                            })
                            .or_else(|| {
                                overflow.then_some(
                                    send_budget.unwrap_or_else(|| calibrate_up(round_est_raw, cal)),
                                )
                            })
                            .and_then(|budget| {
                                cw_overflow::recovery_target(
                                    budget,
                                    refused_tokens,
                                    effective_input_ceiling,
                                )
                            })
                        {
                            if let Some(context_window) = recovered_window {
                                emit_context_window_400(&mut on_round_usage, context_window);
                            }
                            // A recovered full window is composed through the same
                            // effective-ceiling operation as the declared window;
                            // numberless recovery already derives an input cap.
                            let new_budget = effective_input_ceiling
                                .map_or(recovered_budget, |c| recovered_budget.min(c));
                            let new_budget = authoritative_request_budget(
                                Some(new_budget),
                                true,
                                mid_loop_trim_tokens,
                            )
                            .unwrap_or(new_budget);
                            emit_overflow_notice(
                                color,
                                &display::OverflowReason::Refused {
                                    request_estimate: Some(
                                        refused_tokens.min(u32::MAX as usize) as u32
                                    ),
                                    window: recovered_window,
                                    trim_to: new_budget.min(u32::MAX as usize) as u32,
                                },
                                model,
                                cw_retries + 1,
                            );
                            // A recovered cap can only tighten — the request still
                            // carries the same `num_ctx`, so its ceiling holds (#282).
                            send_budget = Some(new_budget);
                            effective_input_ceiling = Some(new_budget);
                            // The endpoint's parsed hard limit is authoritative —
                            // a refuse on it is correct from here on (Step 20.3).
                            send_budget_authoritative = true;
                            let compression = context_recovery::compress(
                                CompressRequest {
                                    // Real-token budget minus real-token schema
                                    // overhead, converted into the pipeline's
                                    // chars/4 currency (Phase 20 §2.3).
                                    messages: &messages,
                                    budget: context_recovery::target(
                                        &messages,
                                        calibrate_down(
                                            new_budget.saturating_sub(tool_tokens_real),
                                            cal,
                                        ),
                                        estimation,
                                    ),
                                    max_messages: None,
                                    replay_protected_tail_len:
                                        context_recovery::protected_tool_tail(&messages),
                                    task: active_task,
                                    hard_budget: true,
                                    authoritative: true,
                                    focus: None,
                                    est: estimation,
                                    summary_input_cap_floor_chars,
                                    rewrites_history,
                                    compaction_store,
                                    compaction_stage: None,
                                },
                                summarizer,
                                compress_state,
                                smart_harness,
                            );
                            let Some(outcome) = cancellable(cancel, compression).await else {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Ok((
                                    smart_harness::cancelled(smart_harness, &mut end_reason)?,
                                    false,
                                    accumulated_usage,
                                    hallucination_count,
                                ));
                            };
                            let outcome = match outcome {
                                Ok(outcome) => outcome,
                                Err(error) => {
                                    context_recovery::record(
                                        &mut solve_obs,
                                        smart_harness,
                                        round,
                                        cw_retries + 1,
                                        round_est_raw,
                                        None,
                                    )?;
                                    return Err(e.context(format!(
                                        "context re-projection failed: {error}"
                                    )));
                                }
                            };
                            if let Some(notice) = outcome.notice {
                                print_harness_notice(&notice, color);
                            }
                            if outcome.action == CompressAction::Refused
                                || !outcome.fired
                                || outcome.tokens_after >= outcome.tokens_before
                            {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Err(e);
                            }
                            if outcome.fired {
                                messages = outcome.messages;
                                prompt_tracker.invalidate();
                                apply_post_compaction_continuation(
                                    worktree_session,
                                    &mut messages,
                                    &mut narration_nudges,
                                    outcome.action,
                                    step_ledger,
                                    prompt_context,
                                    round > 0 && action_nudges,
                                    |candidate| {
                                        preflight_full_message_request(
                                            candidate,
                                            tools_supported.then_some(&tools),
                                            authoritative_request_budget(
                                                send_budget,
                                                send_budget_authoritative,
                                                mid_loop_trim_tokens,
                                            ),
                                            cal,
                                            estimation,
                                            model,
                                        )
                                        .is_ok()
                                    },
                                );
                                record_compaction_artifact(
                                    &mut repeat_calls,
                                    artifact_sink,
                                    artifact_context,
                                    outcome.action,
                                    outcome.tokens_before,
                                    outcome.tokens_after,
                                    calibrate_down(
                                        new_budget.saturating_sub(tool_tokens_real),
                                        cal,
                                    ),
                                    round,
                                    "context_window_400",
                                    None,
                                    false,
                                    compress_state.floor_trend(),
                                    color,
                                );
                            }
                            let projected = estimate_request_tokens(
                                &messages,
                                tools_supported.then_some(&tools),
                                estimation,
                            );
                            if projected >= round_est_raw
                                || calibrate_up(projected, cal) > new_budget
                            {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Err(e);
                            }
                            context_recovery::record(
                                &mut solve_obs,
                                smart_harness,
                                round,
                                cw_retries + 1,
                                round_est_raw,
                                Some(calibrate_up(projected, cal)),
                            )?;
                            cw_retries += 1;
                            continue;
                        }
                    }
                    if overflow {
                        context_recovery::record(
                            &mut solve_obs,
                            smart_harness,
                            round,
                            cw_retries + 1,
                            round_est_raw,
                            None,
                        )?;
                    }
                    return Err(e);
                }
            }
        };

        // Merge token usage from this non-streaming probe round (input = max
        // single prompt, output = sum — Step 18.1) and anchor the context-size
        // tracker on the backend-reported prompt size of this dispatch.
        let round_usage = ollama_usage(&json);
        if let Some(prompt_tokens) = json["prompt_eval_count"]
            .as_u64()
            .and_then(|n| u32::try_from(n).ok())
        {
            if !is_truncation_suspect(prompt_tokens, num_ctx) {
                compress_state
                    .calibration
                    .observe(Some(prompt_tokens), round_est_raw);
                cal = compress_state.calibration.ratio(estimate_ratio);
                tool_tokens_real = calibrate_up(tool_tokens, cal);
            }
            prompt_tracker.record(prompt_tokens, messages.len());
        }
        accumulated_usage = merge_round_usage(accumulated_usage, round_usage);

        // Phase 20 §2.2: a prompt within 5% of the request's `num_ctx` may
        // have been silently head-truncated by Ollama — such a round is
        // window evidence of NOTHING and must neither raise the budget nor
        // emit an `Accepted` observation. #1967: the ONE shared predicate —
        // do not re-derive this threshold at another writer.
        let truncation_suspect =
            round_usage.is_some_and(|u| is_truncation_suspect(u.input_tokens, num_ctx));
        // Mid-turn budget raise on window evidence alone: the backend just
        // evaluated this many prompt tokens inside the `num_ctx` it was sent,
        // so one over-budget acceptance stops the compress-every-round thrash
        // within the same turn (Phase 20 §2.2). Never lowers; stays under the
        // per-request input ceiling.
        if let (Some(u), Some(budget), false) = (round_usage, send_budget, truncation_suspect) {
            // #1528 B4: the accepted-side raise clamps to the hard ceiling and
            // only ever moves UP — the SAME `capped_accepted_prompt_tokens` clamp
            // the OpenAI chat loop uses (one owner, one unit test), so the soft
            // send budget can never exceed `effective_input_ceiling` (the hard leg)
            // and a success never lowers it.
            let raised = capped_accepted_prompt_tokens(u.input_tokens, effective_input_ceiling);
            if raised > budget {
                send_budget = Some(raised);
                if debug {
                    print_debug(
                        &format!(
                            "send budget raised to ~{raised} tokens (backend accepted \
                             {}-token prompt)",
                            u.input_tokens
                        ),
                        color,
                    );
                }
            }
        }

        let message = &json["message"];
        // #2372: the probe is the only generation of this round, so reasoning
        // leaves it here, once, with the stream filter's own policy (#385;
        // #528's leading shape only when the backend declares it) — every final
        // path below (answer, smart exit, read-only handoff) sees the same text.
        let (probe_content, inline_reasoning) = crate::reasoning::ThinkFilter::filter_complete(
            message["content"].as_str().unwrap_or(""),
            emits_leading_reasoning,
        );

        if json["done_reason"] == "length" {
            if output_recovery.retry(
                message["tool_calls"]
                    .as_array()
                    .is_some_and(|calls| !calls.is_empty()),
                &mut messages,
                smart_harness,
            )? {
                continue;
            }
            let text = finalize_final_text(
                generation_bounds::output_limit_notice(probe_content, round_usage),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            if let Some(slot) = &mut end_reason {
                **slot = Some(crate::TurnEndReason::Failed);
            }
            if let Some(harness) = smart_harness {
                harness.outcome(crate::TurnEndReason::Failed, &text)?;
            }
            return Ok((text, false, accumulated_usage, hallucination_count));
        }

        let native_calls = message["tool_calls"].as_array();
        // Recover tool calls a weak model emitted in CONTENT instead of the
        // native `tool_calls` field — the #1 weak-model failure (see
        // `tool_recovery`). Only attempted when the native array is empty;
        // recovered calls are produced in native shape and flow unchanged into
        // the executor + `is_hallucination` + dup-guard + caveat path below.
        let recovered = if native_calls.map(|t| t.is_empty()).unwrap_or(true) {
            tool_recovery::recover_tool_calls(&probe_content)
        } else {
            tool_recovery::Recovery::default()
        };
        let tool_calls: Option<&Vec<serde_json::Value>> = match native_calls {
            Some(t) if !t.is_empty() => Some(t),
            _ if !recovered.calls.is_empty() => Some(&recovered.calls),
            _ => None,
        };
        let has_tools = tool_calls.map(|tc| !tc.is_empty()).unwrap_or(false);
        // W0 (#1511): record what the backend SAYS it served plus this
        // round's parse status for the solve contract. `json["model"]` is the
        // served reality (the contract's `effective_model` source, never an
        // echo of our request); the signal is the ADR §5
        // recovered_tool_call{dialect} / no_parseable_tool_call trace event.
        if let Some(obs) = solve_obs.as_deref_mut() {
            if let Some(m) = json["model"].as_str().filter(|m| !m.is_empty()) {
                obs.served_model = Some(m.to_string());
            }
            let native = native_calls.is_some_and(|t| !t.is_empty());
            if let Some(sig) = observability::round_parse_signal(
                round,
                !probe_content.is_empty(),
                native,
                recovered.dialect,
                Vec::new(),
            ) {
                obs.parse_signals.push(sig);
            }
        }
        if debug && !recovered.calls.is_empty() {
            print_debug(
                &format!(
                    "recovered {} tool call(s) from content (non-native emission)",
                    recovered.calls.len()
                ),
                color,
            );
        }

        if debug {
            let content_excerpt = if probe_content.is_empty() {
                "(empty)".to_string()
            } else {
                let chars: String = probe_content.chars().take(80).collect();
                if probe_content.len() > 80 {
                    format!("{chars}…")
                } else {
                    chars
                }
            };
            let tc_count = tool_calls.map(|tc| tc.len()).unwrap_or(0);
            let usage_str = match round_usage {
                Some(u) => format!("{} in / {} out", u.input_tokens, u.output_tokens),
                None => "no usage".into(),
            };
            print_debug(
                &format!(
                    "round {round} probe: tool_calls={tc_count} usage=[{usage_str}] content={content_excerpt:?}"
                ),
                color,
            );
        }

        if !has_tools {
            if let Some(mut nudge) = capability_evidence.correction(
                &probe_content,
                &tools,
                &mut probe_correction_used,
                tools_supported
                    && workflow_runtime.has_next_round(
                        round,
                        current_tool_round_limit,
                        workflow_grace_rounds,
                    )
                    && !is_cancelled(cancel),
            ) {
                if let Some(harness) = smart_harness {
                    nudge = harness.correct_answer(&probe_content, &nudge)?;
                }
                messages.push(serde_json::json!({"role":"assistant", "content":probe_content}));
                messages.push(serde_json::json!({"role":"user", "content":nudge}));
                accumulated_usage = merge_round_usage(accumulated_usage, round_usage);
                continue 'round_loop;
            }
            if let Some(harness) = smart_harness {
                let more = workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                );
                let control = harness
                    .classify(&probe_content, narration_nudge_cap, more, cancel)
                    .await?;
                let control = harness
                    .verify_answer(
                        control,
                        self_verify::Concluding {
                            messages: &messages,
                            workspace,
                            task,
                            rounds_left: more,
                            round,
                            ledger: &verification,
                            solve_obs: solve_obs.as_deref_mut(),
                        },
                        smart_verify,
                        &probe_content,
                    )
                    .await?;
                let (text, reason) = match control {
                    smart_harness::Control::Continue(nudge) => {
                        messages
                            .push(serde_json::json!({"role":"assistant", "content":probe_content}));
                        messages.push(serde_json::json!({"role":"user", "content":nudge}));
                        continue 'round_loop;
                    }
                    smart_harness::Control::Answer => (
                        FinalReply::from(probe_content.clone()),
                        crate::TurnEndReason::Completed,
                    ),
                    smart_harness::Control::Finish { text, reason } => (text, reason),
                };
                if let Some(slot) = &mut end_reason {
                    **slot = Some(reason);
                }
                let text = finalize_final_text(
                    text,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                harness.outcome(reason, &text)?;
                return Ok((text, false, accumulated_usage, hallucination_count));
            }

            // Format-hallucination tracker: the content looked like a tool-call
            // attempt but could not be recovered into one — count it so cap-exit
            // and metrics see a tooling failure, not a clean final answer.
            if recovered.tool_shaped {
                hallucination_count += 1;
                if debug {
                    print_debug(
                        "format-hallucination: tool call emitted as unrecoverable text",
                        color,
                    );
                }
            }
            if !is_cancelled(cancel)
                && readonly_completion_pending(
                    prompt_disposition,
                    &nudge_classifier,
                    &probe_content,
                )
            {
                let more_rounds = workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                );
                if retry_readonly_completion(
                    &mut messages,
                    &probe_content,
                    None,
                    &mut readonly_completion_retried,
                    more_rounds,
                ) {
                    continue 'round_loop;
                }
                let out = readonly_completion_handoff(
                    &probe_content,
                    &mut end_reason,
                    more_rounds,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                return Ok((out, false, accumulated_usage, hallucination_count));
            }
            // The probe's text is the final answer candidate (#2372). It runs
            // through the no-tool final-answer gates so "Let me inspect..."
            // is nudged instead of forcing a human "continue".
            macro_rules! maybe_nudge_no_tool_content {
                ($content:expr, $usage:expr) => {{
                    let content = $content;
                    if !content.is_empty() {
                        let nudge_classification = nudge_classifier.classify(content);
                        let workflow_classifier_text =
                            workflow_classifier_text(&messages, content);
                        let workflow_hint = nudge_classification
                            .is_plan_update()
                            .then(|| workflow_steerer.plan_update_hint(&workflow_classifier_text))
                            .flatten();
                        let classifier_plan_direction = nudge_classification
                            .is_plan_update()
                            .then(|| {
                                nudge_classifier.direction_for(crate::NudgeClass::PlanUpdate)
                            })
                            .flatten();
                        let plan_nudge_hint =
                            combine_nudge_hints(classifier_plan_direction, workflow_hint.as_deref());
                        if should_ground_unverified_run_command_blocker(
                            content,
                            &tools,
                            run_command_denial_observed,
                            exec_grounding_turn,
                            unverified_exec_blocker_nudges,
                            workflow_runtime.has_next_round(round, current_tool_round_limit, workflow_grace_rounds),
                        ) {
                            if debug {
                                print_debug(
                                    "unsupported run_command blocker — requiring a ground-truth probe",
                                    color,
                                );
                            }
                            messages.push(serde_json::json!({
                                "role": "assistant",
                                "content": content
                            }));
                            messages.push(serde_json::json!({
                                "role": "user",
                                "content": format!(
                                    "{} {}",
                                    compress::LOOP_GUIDANCE_PREFIX,
                                    run_command_ground_truth_nudge()
                                )
                            }));
                            unverified_exec_blocker_nudges += 1;
                            // #2313: the rejected reply was still generated.
                            accumulated_usage = merge_round_usage(accumulated_usage, $usage);
                            continue 'round_loop;
                        }
                        if action_nudges
                            && pending_plan_nudges < PENDING_PLAN_NUDGE_CAP
                            && workflow_runtime.has_next_round(round, current_tool_round_limit, workflow_grace_rounds)
                        {
                            if let Some(nudge) = pending_plan_completion_nudge(
                                step_ledger,
                                nudge_classification.is_plan_update(),
                                plan_nudge_hint.as_deref(),
                            ) {
                                if debug {
                                    print_debug(
                                        "active plan has unfinished steps — nudging before final answer",
                                        color,
                                    );
                                }
                                messages.push(serde_json::json!({
                                    "role": "assistant",
                                    "content": content
                                }));
                                messages.push(serde_json::json!({
                                    "role": "user",
                                    "content": format!(
                                        "{} {}",
                                        compress::LOOP_GUIDANCE_PREFIX, nudge
                                    )
                                }));
                                pending_plan_nudges += 1;
                                accumulated_usage = merge_round_usage(accumulated_usage, $usage);
                                continue 'round_loop;
                            }
                        }
                        if stale_file_nudges < STALE_FILE_NUDGE_CAP
                            && workflow_runtime.has_next_round(round, current_tool_round_limit, workflow_grace_rounds)
                            && action_nudges
                            && looks_like_unverified_stale_file_blocker(content)
                        {
                            if debug {
                                print_debug(
                                    "unverified stale-file blocker — nudging to check ground truth",
                                    color,
                                );
                            }
                            messages.push(serde_json::json!({
                                "role": "assistant",
                                "content": content
                            }));
                            messages.push(serde_json::json!({
                                "role": "user",
                                "content": format!(
                        "{} {}",
                        compress::LOOP_GUIDANCE_PREFIX,
                        stale_file_ground_truth_nudge()
                    ),
                            }));
                            stale_file_nudges += 1;
                            accumulated_usage = merge_round_usage(accumulated_usage, $usage);
                            continue 'round_loop;
                        }
                        if narration_nudges < narration_nudge_cap
                            && workflow_runtime.has_next_round(round, current_tool_round_limit, workflow_grace_rounds)
                            && nudge_classification.is_pending_action()
                            && action_turn
                        {
                            if debug {
                                print_debug(
                                    "narrated intent with no tool call — nudging to act and continuing",
                                    color,
                                );
                            }
                            // #1158: drop the PRIOR nudge exchange first so
                            // successive nudges replace rather than pile up.
                            strip_trailing_nudge_exchange(&mut messages);
                            // Record the model's own narration, then the
                            // corrective, so the next round sees both (mirrors
                            // the has-tools assistant turn).
                            messages.push(serde_json::json!({
                                "role": "assistant",
                                "content": content
                            }));
                            // First nudge: the (tunable) classifier direction.
                            // Later nudges (cap > 1): generic text already
                            // failed to convert intent into action, so
                            // escalate — name the active step, demand a bare
                            // tool call.
                            let direction = if narration_nudges == 0 {
                                nudge_classifier
                                    .direction_for(nudge_classification.class)
                                    .map(workflow_guidance)
                                    .unwrap_or_else(narration_action_nudge)
                            } else {
                                escalated_narration_action_nudge(
                                    narration_nudges + 1,
                                    narration_nudge_cap,
                                    step_ledger,
                                )
                            };
                            messages.push(serde_json::json!({
                                "role": "user",
                                "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, direction),
                            }));
                            narration_nudges += 1;
                            accumulated_usage = merge_round_usage(accumulated_usage, $usage);
                            continue 'round_loop;
                        }
                        // Every rescue gate passed on this content: it is
                        // about to be accepted as the final answer. Record
                        // WHY — before this, a narration acceptance was
                        // indistinguishable from a normal completion, even
                        // under NEWT_DEBUG (2026-07-08 ornith:35b forensics).
                        //
                        // #1261: the reason MIRRORS the rescue gate above —
                        // including its `action_turn` guard. On a turn where
                        // the rescue can never arm (non-Act disposition forces
                        // `action_nudges = false`, or the prompt does not
                        // invite action), prose is this turn's LEGITIMATE
                        // ending: reporting "rescue budget spent" there blamed
                        // the model for a harness decision — the budget was
                        // untouched and no cap value could have changed
                        // anything (the diagnosed ornith:35b Explain turn).
                        let accepted_reason = if nudge_classification.is_pending_action()
                            && action_turn
                        {
                            if !workflow_runtime.has_next_round(round, current_tool_round_limit, workflow_grace_rounds) {
                                crate::TurnEndReason::NarrationFinalRound
                            } else {
                                crate::TurnEndReason::NarrationCapExhausted
                            }
                        } else {
                            crate::TurnEndReason::Completed
                        };
                        if debug && accepted_reason != crate::TurnEndReason::Completed {
                            print_debug(
                                &format!(
                                    "no-tool narration accepted as final answer ({accepted_reason:?})"
                                ),
                                color,
                            );
                        }
                        if let Some(slot) = &mut end_reason {
                            **slot = Some(accepted_reason);
                        }
                    }
                }};
            }
            // Esc after the answer arrived: the operator asked to stop, so the
            // turn ends empty (the round-boundary contract) while the paid
            // round's usage stands.
            if is_cancelled(cancel) {
                return Ok((
                    smart_harness::cancelled(smart_harness, &mut end_reason)?,
                    false,
                    accumulated_usage,
                    hallucination_count,
                ));
            }
            // #2372: the probe's content is the answer. It is never generated a
            // second time for display: the host renders the accepted reply, so
            // the operator sees, the caller returns and the ledger counts one
            // generation. Its reasoning — the native `thinking` channel and any
            // inline block, both — is folded under the same gate the display
            // stream's spinner had: a colour terminal, never a pipe.
            if color {
                let native_thinking = json["message"]["thinking"]
                    .as_str()
                    .map(str::trim)
                    .filter(|thinking| !thinking.is_empty())
                    .map(str::to_string);
                let reasoning = match (native_thinking, inline_reasoning.clone()) {
                    (Some(native), Some(inline)) => Some(format!("{native}\n{inline}")),
                    (native, inline) => native.or(inline),
                };
                commit_reasoning_fold(
                    reasoning,
                    probe_started.elapsed(),
                    completed_spill_renderer.as_deref(),
                    color,
                );
            }
            if probe_content.is_empty() {
                let merged = accumulated_usage;
                let empty_round_usage = round_usage;
                let generated_unusable_output = empty_round_usage
                    .as_ref()
                    .map(|u| u.output_tokens > 0)
                    .unwrap_or(false);

                if generated_unusable_output
                    && suspicious_empty_retries < SUSPICIOUS_EMPTY_RETRY_CAP
                {
                    if trace {
                        print_trace(&ollama_response_shape(&json), color);
                    }
                    if debug {
                        let fields = ollama_non_content_fields(&json);
                        let field_note = if fields.is_empty() {
                            "no known non-content fields".to_string()
                        } else {
                            format!("non-content fields: {}", fields.join(", "))
                        };
                        print_debug(
                        &format!(
                            "empty assistant content with generated tokens — retrying ({}/{SUSPICIOUS_EMPTY_RETRY_CAP}; {field_note})",
                            suspicious_empty_retries + 1
                        ),
                        color,
                    );
                    }
                    // Phase 20 §2.2: empty content carrying non-content
                    // fields is the thinking-only quirk — report it at
                    // detection (at most once per turn) so the prompt-
                    // inflating corrective retry isn't re-learned from
                    // scratch every session.
                    if !thinking_only_reported && !ollama_non_content_fields(&json).is_empty() {
                        thinking_only_reported = true;
                        if let Some(hook) = on_round_usage.as_deref_mut() {
                            hook(RoundObservation::ThinkingOnly);
                        }
                    }
                    messages.push(serde_json::json!({
                        "role": "user",
                        "content": suspicious_empty_retry_nudge(suspicious_empty_retries, &json)
                    }));
                    accumulated_usage = merged;
                    suspicious_empty_retries += 1;
                    continue 'round_loop;
                }

                // Both probe and stream are empty — likely context overflow.
                // `input_tokens` is the largest single prompt evaluated this
                // turn (Step 18.1), so the 85%-of-safe-context check now
                // compares one real prompt against the window instead of a
                // multi-round sum that inflated past it after ~2 rounds.
                let overflow_likely = merged
                    .as_ref()
                    .zip(safe_context)
                    .map(|(u, safe)| u.input_tokens >= safe * 85 / 100)
                    .unwrap_or(false);
                if overflow_likely && overflow_retries < 2 {
                    emit_overflow_notice(
                        color,
                        &display::OverflowReason::EmptyReplyNearWindow {
                            prompt_tokens: merged.as_ref().map_or(0, |u| u.input_tokens),
                            window: safe_context.unwrap_or(0),
                            trigger_pct: 85,
                        },
                        model,
                        overflow_retries + 1,
                    );
                    // Compress toward 3/4 of the safe window — comfortably
                    // under the 85% trigger (was a blunt count trim before
                    // Step 18.4). The retry happens regardless: it is
                    // already bounded by `overflow_retries`. The target
                    // arithmetic stays in real-token space (`safe_context`
                    // and the schema overhead are real-token figures),
                    // then converts once into the pipeline's chars/4
                    // currency (Phase 20 §2.3).
                    let target = calibrate_down(
                        safe_context
                            .map(|s| (s as usize).saturating_mul(3) / 4)
                            .unwrap_or(0)
                            .saturating_sub(tool_tokens_real),
                        cal,
                    );
                    let compression = smart_harness::compress(
                        CompressRequest {
                            messages: &messages,
                            budget: target,
                            max_messages: None,
                            replay_protected_tail_len: 0,
                            task: active_task,
                            hard_budget: true,
                            // A suspected silent overflow is a real failure
                            // signal — refuse semantics apply (Step 20.3).
                            authoritative: true,
                            focus: None,
                            est: estimation,
                            summary_input_cap_floor_chars,
                            rewrites_history,
                            compaction_store,
                            compaction_stage: None,
                        },
                        summarizer,
                        compress_state,
                        smart_harness,
                    );
                    let Some(outcome) = cancellable(cancel, compression).await else {
                        return Ok((
                            smart_harness::cancelled(smart_harness, &mut end_reason)?,
                            false,
                            accumulated_usage,
                            hallucination_count,
                        ));
                    };
                    let outcome = outcome?;
                    if let Some(notice) = outcome.notice {
                        print_harness_notice(&notice, color);
                    }
                    if outcome.fired {
                        messages = outcome.messages;
                        prompt_tracker.invalidate();
                        apply_post_compaction_continuation(
                            worktree_session,
                            &mut messages,
                            &mut narration_nudges,
                            outcome.action,
                            step_ledger,
                            prompt_context,
                            round > 0 && action_nudges,
                            |candidate| {
                                preflight_full_message_request(
                                    candidate,
                                    tools_supported.then_some(&tools),
                                    authoritative_request_budget(
                                        send_budget,
                                        send_budget_authoritative,
                                        mid_loop_trim_tokens,
                                    ),
                                    cal,
                                    estimation,
                                    model,
                                )
                                .is_ok()
                            },
                        );
                        record_compaction_artifact(
                            &mut repeat_calls,
                            artifact_sink,
                            artifact_context,
                            outcome.action,
                            outcome.tokens_before,
                            outcome.tokens_after,
                            target,
                            round,
                            "silent_overflow_recovery",
                            None,
                            false,
                            compress_state.floor_trend(),
                            color,
                        );
                    } else if !rewrites_history {
                        // Append-only: this fallback is a structural rewrite
                        // of prior turns, so the preset forbids it — and here
                        // that matters MORE than under `standard`, not less.
                        // Compress never fires under append-only, so what was
                        // the rare branch becomes the only branch: leaving it
                        // ungated would make the preset that promises the
                        // transcript is never rewritten rewrite it on every
                        // suspected overflow. The retry is then identical to
                        // the request that just came back empty, so there is
                        // nothing to gain by looping — let the retry budget
                        // run out and the silent-overflow report stand.
                    } else {
                        // N1: the retry must differ from the request that
                        // just returned empty — when compress was a no-op
                        // (Fit / nothing reclaimable), fall back to one
                        // structural prune with a tight protected tail.
                        let fallback = crate::prune::prune(
                            &messages,
                            &crate::prune::PruneConfig {
                                keep_last: 2,
                                ..Default::default()
                            },
                        );
                        if fallback.chars_reclaimed > 0 {
                            let tokens_before = estimate_tokens(&messages, estimation);
                            let tokens_after = estimate_tokens(&fallback.messages, estimation);
                            messages = fallback.messages;
                            prompt_tracker.invalidate();
                            record_compaction_artifact(
                                &mut repeat_calls,
                                artifact_sink,
                                artifact_context,
                                CompressAction::Pruned,
                                tokens_before,
                                tokens_after,
                                target,
                                round,
                                "silent_overflow_structural_fallback",
                                None,
                                false,
                                compress_state.floor_trend(),
                                color,
                            );
                        }
                    }
                    accumulated_usage = merged;
                    overflow_retries += 1;
                    continue 'round_loop;
                }
                // Phase 20 §2.2: persistent empties past the retry budget
                // at ≥85% of the safe window are silent-overflow evidence
                // — reported at the exit, with the merged prompt figure,
                // before either return below.
                if overflow_likely {
                    if let (Some(hook), Some(u)) = (on_round_usage.as_deref_mut(), merged.as_ref())
                    {
                        hook(RoundObservation::SuspectedOverflow {
                            prompt_tokens: u.input_tokens,
                        });
                    }
                }
                if generated_unusable_output {
                    if trace {
                        print_trace(&ollama_response_shape(&json), color);
                    }
                    // Phase 20 §2.2: the diagnostic exit is also a
                    // thinking-only detection site (at most once per
                    // turn; the function returns right after, so the
                    // turn-local flag needs no update here).
                    if !thinking_only_reported && !ollama_non_content_fields(&json).is_empty() {
                        if let Some(hook) = on_round_usage.as_deref_mut() {
                            hook(RoundObservation::ThinkingOnly);
                        }
                    }
                    if let Some(slot) = &mut end_reason {
                        **slot = Some(crate::TurnEndReason::Empty);
                    }
                    observability::observe_harness_reply(&mut solve_obs);
                    return Ok((
                        finalize_final_text(
                            FinalReply::harness(suspicious_empty_ollama_diagnostic(&json)),
                            workspace,
                            &caveats.fs_read,
                            &capability_evidence,
                            disclosure,
                            &turn_claims,
                            &verification,
                        ),
                        false,
                        merged,
                        hallucination_count,
                    ));
                }
                let msg = "(model returned an empty response — try rephrasing, or check the model with `newt doctor`)";
                if let Some(slot) = &mut end_reason {
                    **slot = Some(crate::TurnEndReason::Empty);
                }
                observability::observe_harness_reply(&mut solve_obs);
                return Ok((
                    finalize_final_text(
                        FinalReply::harness(msg.to_owned()),
                        workspace,
                        &caveats.fs_read,
                        &capability_evidence,
                        disclosure,
                        &turn_claims,
                        &verification,
                    ),
                    false,
                    merged,
                    hallucination_count,
                ));
            }
            maybe_nudge_no_tool_content!(probe_content.as_str(), None);
            // Phase 20 §2.2: non-empty probe content is usable output.
            emit_accepted(
                &mut on_round_usage,
                round_usage,
                truncation_suspect,
                round_est_raw,
            );
            // #1964: this normal (non-cap) finish gets the same claim check +
            // disclosure gate as a cap-exit summary.
            let probe_content = finalize_final_text(
                probe_content,
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            return Ok((probe_content, false, accumulated_usage, hallucination_count));
        }

        // Has tool calls — add the assistant turn, then VALIDATE the whole batch
        // before emitting acceptance or running any tool (#1528 B4). A tool-call
        // batch is usable output only once it is fully validated; the accepted
        // observation is emitted AFTER whole-batch validation and BEFORE the first
        // tool side effect, below.
        messages.push(message.clone());
        let mut round_wrote = false;
        let mut round_modified_workspace = false;
        let mut round_progress = false;
        let mut round_succeeded = false;
        let tcs = tool_calls.unwrap();
        // Phase 1 (invariant #3, BATCH level): validate the ENTIRE batch before
        // any side effect. This Ollama/Anthropic-native wire carries no per-call
        // ids, so ids are not required — but a malformed sibling still rejects the
        // WHOLE batch: echo the reason for every call and execute nothing, so no
        // valid call mutates the workspace ahead of an unvalidated batch.
        let extracted: Vec<(Option<&str>, Option<&str>, &serde_json::Value)> = tcs
            .iter()
            .map(|tc| {
                if tc["function"].is_null() {
                    (None, tc["name"].as_str(), &tc["input"])
                } else {
                    (
                        None,
                        tc["function"]["name"].as_str(),
                        &tc["function"]["arguments"],
                    )
                }
            })
            .collect();
        let validated = match tools::validate_tool_call_batch(&extracted, false) {
            Ok(v) => Some(v),
            // This wire carries no ids (`require_call_id = false`), so the batch
            // can only ever be `ContentInvalid`; `reason()` reads either class.
            Err(rejection) => {
                let reason = rejection.reason().to_string();
                if let Some(harness) = smart_harness {
                    harness.reject_tools(&reason, true)?;
                }
                for _tc in tcs {
                    print_synthetic_tool_result(
                        "(rejected tool-call batch)",
                        &serde_json::Value::Null,
                        workspace,
                        &reason,
                        color,
                        &completed_spill_renderer,
                    );
                    if let Some(rec) = tool_events.as_deref_mut() {
                        rec.push(crate::ToolEvent::from_call(
                            "(rejected tool-call batch)",
                            &serde_json::Value::Null,
                            false,
                            Some(0),
                        ));
                    }
                    smart_harness::push_tool_message(
                        &mut messages,
                        serde_json::json!({
                            "role": "tool",
                            "content": format!("tool-call batch rejected before execution: {reason}"),
                        }),
                        smart_harness,
                        true,
                        "(rejected tool-call batch)",
                    )?;
                }
                None
            }
        };
        // #1528 B4: a FULLY-VALIDATED tool-call batch is usable output — emit the
        // accepted-prompt observation now, AFTER whole-batch validation and BEFORE
        // the first tool side effect below. A content-invalid batch leaves
        // `validated == None`; it is NOT provider-accept evidence and must not
        // ratchet the learned budget (RR1 fail-closed).
        let batch = smart_harness
            .zip(validated.as_ref())
            .map(|(harness, calls)| harness.tool_batch(calls, &messages))
            .transpose()?;
        let mut tool_warnings = Vec::new();
        if validated.is_some() {
            emit_accepted(
                &mut on_round_usage,
                round_usage,
                truncation_suspect,
                round_est_raw,
            );
            commit_tool_round_narration(
                &probe_content,
                false,
                completed_spill_renderer.as_deref(),
                color,
            );
        }
        // Phase 2: every call in the batch is valid — execute in order. `flatten`
        // yields nothing (so this runs zero tools) when the batch was rejected.
        for (call_index, (_tc, vc)) in tcs.iter().zip(validated.iter().flatten()).enumerate() {
            let name = vc.name.as_str();
            let args = vc.args.clone();
            announce_tool_activity(name);
            // Per-tool head: any frame from the PREVIOUS tool in this batch
            // comes down before this iteration's first writer (the debug /
            // trace echoes below print BEFORE the wired `call()` erase).
            dismiss_completed_spill(&completed_spill_renderer);
            if is_hallucination(name, &args) {
                hallucination_count += 1;
            }
            // #2637: an exact bare re-read is NEVER refused — serve it
            // silently from the memo when the file's actual current content
            // still matches; otherwise fall through to a real read below.
            if let Some(content) =
                repeat_calls.cached_read(name, &args, ReadScope { workspace, caveats })
            {
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &content,
                    color,
                    &completed_spill_renderer,
                );
                if let Some(rec) = tool_events.as_deref_mut() {
                    rec.push(crate::ToolEvent::from_cache(name, &args));
                }
                let offloaded =
                    maybe_offload_tool_result(name, content, tool_offload, spill_store, disclosure);
                smart_harness::push_tool_resolution(
                    &mut messages,
                    serde_json::json!({ "role": "tool", "content": offloaded }),
                    batch.as_ref(),
                    call_index,
                )?;
                continue;
            }
            // Step 27.3/#771: short-circuit selected exact repeats — steer
            // instead of re-executing a dead or already-useful call. The bogus
            // emission is still counted above; we just don't run it again.
            if let Some(steer) = repeat_calls.repeat_steer(name, &args) {
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &steer,
                    color,
                    &completed_spill_renderer,
                );
                if let Some(rec) = tool_events.as_deref_mut() {
                    rec.push(crate::ToolEvent::from_call(name, &args, false, Some(0)));
                }
                smart_harness::push_tool_resolution(
                    &mut messages,
                    serde_json::json!({ "role": "tool", "content": steer }),
                    batch.as_ref(),
                    call_index,
                )?;
                continue;
            }
            let invocation = batch
                .as_ref()
                .map(|batch| batch.start(call_index, disclosure))
                .transpose()?;
            if !is_read_only_call(name, &args) {
                round_wrote = true;
            }
            record_organic_note_use(name, &note_sink, &mut note_nudge);
            // retry technique: snapshot the file's pre-write bytes before the
            // write tool runs, so the post-turn gate can revert exactly newt's writes.
            let before_change =
                progress_workspace_state(name, &args, workspace, &caveats.fs_read).await;
            ledger_note_write(write_ledger, name, &args, workspace);
            let tool_t0 = std::time::Instant::now();
            let execution = std::sync::OnceLock::new();
            let retry_authorized = std::sync::OnceLock::new();
            let routed_to = std::sync::OnceLock::new();
            let governed_pr = std::sync::OnceLock::new();
            let report_capture = std::sync::Mutex::new(observed_report::Capture::default());
            let command_directory = std::sync::OnceLock::new();
            let attribution_epoch = AttributionEpoch::new(attribution, git_tool, model, name);
            // #727: intercept the read-only budget self-read here. Its answer is
            // dynamic per-turn loop state — the num_ctx input ceiling and the
            // conversation's token estimate — which are in scope in the loop, not
            // inside execute_tool. `prompt_tracker.current` is real-token currency,
            // the same the ceiling is in. The rendered string then flows through
            // all the normal bookkeeping below (ok, tool_events, phantom_reaches,
            // spill), so aliases recorded as Rewrites stay correct.
            let result = if tools::is_context_remaining_call(name) {
                let report = budget::render_context_budget(
                    prompt_tracker.current(&messages, Some(&tools), cal, estimation),
                    effective_input_ceiling,
                    num_ctx,
                    input_ceiling_pct,
                    low_budget_pct,
                );
                if let Some(invocation) = &invocation {
                    invocation.host();
                    invocation.observe(&report, None, spill_store)?;
                }
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &report,
                    color,
                    &completed_spill_renderer,
                );
                report
            } else {
                // #297 follow-up: race the tool dispatch against the turn's
                // cancel flag. A mid-tool interrupt (Esc / Ctrl-C) now drops the
                // in-flight future here instead of waiting for the tool to
                // return. Exec retains `kill_on_drop`, but dropping a future
                // is not proof the child tree stopped or side effects ceased.
                // A started call without an observed return remains uncertain.
                // `is_cancelled` between rounds still
                // catches the abandoned turn; this closes the *during-a-tool*
                // window that a foreground child on the tty used to wedge.
                // #1947: distil the ledger BEFORE the call. What a
                // `render_report` in THIS call can be checked against is what
                // the turn has already done — the events for this very call
                // are pushed after it returns.
                let tool_evidence = tool_events
                    .as_deref()
                    .map(|e| capability_check::Evidence::from_events(e));
                let Some(result) = tools::execute_tool_with_collaborators(
                    name,
                    &args,
                    workspace,
                    color,
                    tool_output_lines,
                    caveats,
                    mcp,
                    tools::ToolCollaborators {
                        command_budget,
                        shell_dialect,
                        read_history: Some(&mut read_history),
                        default_command_cwd,
                        worktree_session,
                        invocation: invocation.as_ref(),
                        build_check_cmd: build_check_cmd.as_deref(),
                        tool_evidence: tool_evidence.as_ref(),
                        // Reborrow + re-coerce: shortens the trait-object
                        // lifetime to this call (Option<&mut dyn _> is
                        // invariant, so the longer ChatCtx lifetime can't
                        // unify directly).
                        note_sink: note_sink
                            .as_deref_mut()
                            .map(|s| &mut *s as &mut dyn NoteSink),
                        recall_source,
                        memory_source,
                        prompt_context: Some(prompt_context),
                        artifact_context,
                        artifact_sink,
                        // #263 prompted grants — same reborrow pattern.
                        permission_gate: permission_gate
                            .as_deref_mut()
                            .map(|g| &mut *g as &mut dyn PermissionGate),
                        exec_floor,
                        git_tool,
                        crew_runner,
                        scratchpad_store,
                        code_search,
                        where_is,
                        nav,
                        experience_store,
                        step_ledger,
                        operating_mode_control,
                        plan_mode_control,
                        plan_draft_sink,
                        spill_store,
                        persona_tools,
                        hidden_tools: Some(&hidden_tools),
                        live_tool_output: live_tool_output.clone(),
                        completed_spill_renderer: completed_spill_renderer.clone(),
                        execution: Some(&execution),
                        retry_authorized: Some(&retry_authorized),
                        governed_pr: Some(&governed_pr),
                        report_capture: Some(&report_capture),
                        command_directory: Some(&command_directory),
                        routed_to: Some(&routed_to),
                        pending_rerun: Some(&mut pending_rerun),
                    },
                    tool_offload,
                    prompt_disposition,
                    cancel,
                )
                .await?
                else {
                    return Ok((
                        smart_harness::cancelled(smart_harness, &mut end_reason)?,
                        false,
                        accumulated_usage,
                        hallucination_count,
                    ));
                };
                result
            };
            // 17.6: record the call for the turn's events column — args are
            // digested (never stored raw), duration is a display claim.
            // Step 27.3/#771: classify once; remember outcomes that should make
            // an exact repeat self-correct next round.
            let ok = tools::tool_ok(&result, execution.get().copied());
            round_succeeded |= ok;
            attribution_epoch.finish(&args, ok);
            run_command_denial_observed |= run_command_result_is_denial(name, ok, &result);
            capability_evidence.record(name, ok, execution.get().copied());
            let after_change = if before_change.is_some() {
                progress_workspace_state(name, &args, workspace, &caveats.fs_read).await
            } else {
                None
            };
            round_modified_workspace |=
                workflow_runtime.record_workspace_change(before_change, after_change);
            round_progress |= workflow_runtime.record_observation(
                name,
                &args,
                &result,
                ok,
                execution.get().copied(),
                routed_to.get(),
            );
            repeat_calls.record(
                name,
                &args,
                ok,
                &result,
                execution.get().copied(),
                ReadScope { workspace, caveats },
            );
            repeat_calls.permit_authorized_retry(name, &args, &retry_authorized);
            append_clean_build_warning(
                if batch.is_some() {
                    &mut tool_warnings
                } else {
                    &mut messages
                },
                &mut clean_build,
                &args,
                None,
            )?;
            record_completed_tool_event(
                &mut tool_events,
                name,
                &args,
                ok,
                execution.get().copied(),
                tool_t0,
            );
            turn_claims.observe_report(
                workspace,
                &caveats.fs_read,
                &report_capture.lock().expect("report capture"),
                execution.get().copied(),
                governed_pr.get(),
            );
            if let Some(outcome) = governed_pr.get() {
                verification.record_publication_outcome(outcome);
            }
            if ok {
                if let Some(directory) = command_directory.get() {
                    verification.record_command_directory(directory);
                }
            }
            verification
                .observe_routed(
                    name,
                    &args,
                    ok,
                    execution.get().copied(),
                    workspace,
                    routed_to.get(),
                )
                .await;
            record_phantom_reach(
                &mut phantom_reaches,
                name,
                &args,
                &result,
                ok,
                advertise_team,
            );
            // #867 Part A: ledger the verified paths this result surfaced
            // BEFORE the offload may spill the text out of the transcript.
            observed_paths.record(&result, &mut observed_resolver);
            smart_harness::push_tool_return(
                &mut messages,
                serde_json::json!({
                    "role": "tool",
                    // Step 26.3 (#584): offload an oversized result (redact → spill →
                    // teaser+handle) when tool_offload is on; unchanged otherwise.
                    "content": smart_harness::tool_result(name, result, tool_offload, spill_store, disclosure, invocation.as_ref())?
                }),
                invocation.as_ref(),
            )?;
        }
        for message in tool_warnings {
            smart_harness::push_tool_message(
                &mut messages,
                message,
                smart_harness,
                true,
                "build guidance",
            )?;
        }
        if round_wrote {
            read_only_rounds = 0;
        } else {
            read_only_rounds = read_only_rounds.saturating_add(1);
        }
        if let Some(harness) = smart_harness {
            harness.record_messages(&messages)?;
        }
        if round_succeeded {
            output_recovery.completed_tool_round();
        }
        workflow_runtime.record_round_outcome(round_modified_workspace, round_progress);
        if let Some(text) = pending_plan_approval_handoff(
            plan_mode_control,
            PlanRoundFacts {
                disposition: prompt_disposition,
                step_ledger,
                plan_at_turn_start: &plan_at_turn_start,
                progressed: round_modified_workspace || round_progress,
            },
            smart_harness,
            cancel,
            &mut end_reason,
        )? {
            dismiss_completed_spill(&completed_spill_renderer);
            let text = finalize_final_text(
                FinalReply::harness(text),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
    }

    // Reached the round cap. The cap exhausts immediately after a TOOL round,
    // so the last tool's completed viewport is still painted and nothing has
    // written since — take it down NOW, before the summary dispatch's retry
    // indicators and the caller's summary text land below it.
    dismiss_completed_spill(&completed_spill_renderer);
    // Trim the bloated message list so the final
    // summary request doesn't overflow the model's context window, then
    // make ONE tools-disabled completion so the user gets a real partial answer.
    let protected_head = protected_prompt_head_len(&messages, prompt_read::ACTIVE_PROMPT_PREFIX);
    let trimmed = trim_for_summary(&messages, protected_head, 6);
    // Step 27.5: salvage the plan/state ledger + the failed-call count so the
    // summary reflects progress and the fallback advice is honest.
    let progress = cap_exit_progress(worktree_session, step_ledger, scratchpad_store);
    // #2374: a failed check at the round limit is a scored repair exhaustion.
    let cap_reason = verification
        .cap_exit_reason(
            workspace,
            smart_harness.is_some() && smart_verify,
            current_tool_round_limit,
            solve_obs.as_deref_mut(),
        )
        .await;
    if let Some(hit) = &mut round_cap_hit {
        **hit = true;
    }
    if let Some(harness) = smart_harness {
        harness.record_messages(&messages)?;
        let text = cap_exit_fallback(
            current_tool_round_limit,
            accumulated_usage,
            repeat_calls.total_failures(),
            progress.as_deref(),
        );
        let text = finalize_final_text(
            text,
            workspace,
            &caveats.fs_read,
            &capability_evidence,
            disclosure,
            &turn_claims,
            &verification,
        );
        harness.outcome(cap_reason, &text)?;
        if let Some(slot) = &mut end_reason {
            **slot = Some(cap_reason);
        }
        return Ok((text, false, accumulated_usage, hallucination_count));
    }

    let cap = CapExit {
        max_tool_rounds: current_tool_round_limit,
        accumulated: accumulated_usage,
        wasted_calls: repeat_calls.total_failures(),
        progress,
        observed: observed_paths.into_vec(),
        request_budget: authoritative_request_budget(
            send_budget,
            send_budget_authoritative,
            mid_loop_trim_tokens,
        ),
        calibration: cal,
        estimation,
        ollama_options,
        prompt_measurement: Default::default(),
        fell_back: Default::default(),
    };
    let result = final_summary_ollama(&client, &chat_url, model, trimmed, &cap, attempts).await;
    let (text, streamed, usage) = cap.recover_rejection(
        result,
        &mut solve_obs,
        compress_state,
        current_tool_round_limit,
        cw_retries + 1,
    )?;
    let text = finalize_final_text(
        text,
        workspace,
        &caveats.fs_read,
        &capability_evidence,
        disclosure,
        &turn_claims,
        &verification,
    );
    if let Some(slot) = &mut end_reason {
        **slot = Some(cap_reason);
    }
    Ok((text, streamed, usage, hallucination_count))
}

/// Returns `true` when `name` is a tool that doesn't modify the workspace.
/// Used to count consecutive read-only rounds and inject a write-nudge.
/// `save_note` writes *memory*, not the workspace — a round that only saved
/// a note must not suppress the stop-exploring-start-writing nudge; `recall`
/// (17.5) reads past conversations and is likewise pure exploration.
/// First line of a tool result, capped — used as the remembered error reason in
/// [`RepeatCallGuard`] so the steering message is short.
fn first_line(s: &str) -> String {
    s.lines().next().unwrap_or("").chars().take(200).collect()
}

/// Per-run guard against a weak model looping on a tool call whose result should
/// already be actionable. Step 27.3 covered failures: the forensic session showed
/// the model re-issuing the *identical* failed `run_command` three times and
/// re-reading the same file ~8×, burning rounds. Later field reports added
/// success-shaped loops: no-result probes (`recall`, `state_get`), successful
/// `web_fetch` calls with real content, and successful read-only shell probes.
///
/// Keyed by `(name, canonical args)`, it short-circuits selected exact repeats
/// with steering instead of re-executing them. The classifier sees every call
/// outcome, but most successes deliberately stay repeatable; only failures,
/// success-shaped no-results, successful `web_fetch`, and successful read-only
/// shell probes are memoized. Failure counts remain available for end-of-run
/// diagnosis, but failures with different arguments do not establish that a
/// whole tool is unavailable. A successful workspace repair releases failure
/// memos so the same command can check the corrected state.
#[derive(Debug, Clone, PartialEq, Eq)]
enum RepeatMemo {
    Failure {
        first_line: String,
        /// A confinement refusal or typed failed native execution can be
        /// rechecked after a confirmed grant. This does not infer authority
        /// or a failure's cause from native stderr.
        retry_after_grant: bool,
    },
    NoResult {
        reason: String,
    },
    EvidenceObserved {
        subject: String,
        advice: &'static str,
    },
    /// Procedural content is still in context. Reuse succeeds cheaply; unlike
    /// persistent outcome evidence, compaction/workspace changes release it.
    SkillRead,
    /// #2555/#2637: a successful, argument-bare `read_file` (no explicit
    /// `offset`/`limit`) — the shape that loops when a weak model re-pages
    /// the same file. Per the harness-design doctrine this NEVER refuses the
    /// repeat: `RepeatCallGuard::cached_read` re-verifies `content_id`
    /// against the file's ACTUAL current bytes (never the recorded-tool-call
    /// bookkeeping) and, on a match, replays `content` silently; on a
    /// mismatch it drops the memo and a real read runs. Also released by ANY
    /// workspace change (the existing `Failure` release already covers that)
    /// and by compaction (`RepeatCallGuard::release_read_memos`) — a
    /// post-compaction re-read is legitimate because the working-set card no
    /// longer holds the page. An explicit `offset`/`limit` call is never
    /// memoized at all (see `classify_repeat_memo`), so a deliberate paging
    /// scan always runs.
    ReadRange {
        path: String,
        content_id: content_addressable::RawContentId,
        content: String,
    },
}

/// #2637: the confinement context a `ReadRange` freshness check runs
/// through — bundled so `record`/`classify_repeat_memo`/`cached_read` take
/// one param instead of two (clippy's `too_many_arguments`), not because
/// `workspace` and `caveats` are conceptually one thing.
#[derive(Clone, Copy)]
struct ReadScope<'a> {
    workspace: &'a str,
    caveats: &'a crate::caveats::Caveats,
}

impl ReadScope<'_> {
    /// Content identity of `path`'s ACTUAL current bytes, through the same
    /// confinement/authorization path a real `read_file` uses
    /// (`tools::authorized_read`) — never a hand-rolled fs read, and never
    /// trusting that no recorded workspace-changing tool ran since the last
    /// memo as proof of "unchanged" (an editor or background process can
    /// change a file without going through any tool this guard observes).
    /// `None` when the read cannot be authorized right now (no gate offered
    /// here) — callers treat that as "freshness unprovable", never as a grant.
    fn content_id_of(&self, path: &str) -> Option<content_addressable::RawContentId> {
        tools::authorized_read("read_file", path, self.workspace, self.caveats, None)
            .ok()
            .map(|contents| content_addressable::RawContentId::from_content(contents.as_bytes()))
    }
}

#[derive(Default)]
struct RepeatCallGuard {
    /// `(name + canonical args)` → the prior outcome that should steer an exact repeat.
    repeat_memos: std::collections::HashMap<String, RepeatMemo>,
    /// `name` → how many times it has failed this run (any args).
    fails_by_tool: std::collections::HashMap<String, usize>,
}

impl RepeatCallGuard {
    fn permit_authorized_retry(
        &mut self,
        name: &str,
        args: &serde_json::Value,
        ready: &std::sync::OnceLock<()>,
    ) {
        if ready.get().is_some() {
            self.repeat_memos.remove(&Self::key(name, args));
        }
    }

    fn key(name: &str, args: &serde_json::Value) -> String {
        // The model emits byte-identical args when it loops (confirmed by the
        // identical forensic args digests), so the compact JSON is a stable key.
        format!("{name}\u{1}{args}")
    }

    /// Steering message if this exact `(name, args)` already produced a memoized
    /// outcome that should not be repeated this run, else `None` (let it execute).
    fn repeat_steer(&self, name: &str, args: &serde_json::Value) -> Option<String> {
        let key = Self::key(name, args);
        let raw: String = match self.repeat_memos.get(&key)? {
            RepeatMemo::Failure {
                first_line: prev, ..
            } => format!(
                "You already called `{name}` with these exact arguments and it failed: {prev}. \
                 Inspect the error and correct its cause before retrying this call."
            ),
            RepeatMemo::NoResult { .. } if name == "plan_get" => {
                scheduled::EMPTY_PLAN_GUIDANCE.to_string()
            }
            RepeatMemo::NoResult { reason } => format!(
                "You already ran `{name}` with these exact arguments this turn and {reason}. \
                 Don't repeat the identical call — create or update the missing state, change \
                 the arguments when the tool accepts them, or use a different tool."
            ),
            RepeatMemo::EvidenceObserved { subject, advice } => format!(
                "You already observed {subject} with `{name}` and received output. Do NOT repeat \
                 the identical call — {advice}"
            ),
            // #2637: never refuse a bare re-read. `RepeatCallGuard::cached_read`
            // is called before this at every call site and either serves the
            // memo silently (content unchanged) or drops it and lets a real
            // read run (content changed / freshness unprovable) — this arm is
            // unreachable in practice, kept only so the match stays exhaustive.
            RepeatMemo::ReadRange { .. } | RepeatMemo::SkillRead => return None,
        };
        // disclosure-gate-live-path (#5): the steer is a SYNTHETIC model-ingress
        // message re-injected as a `{"role":"tool"}` turn, bypassing the
        // tool-result funnel — and the `Failure` arm interpolates `prev`, the raw
        // first line of a FAILED tool result. Value-filter the composed steer so a
        // registered session secret that landed in that line cannot reach the model
        // on the repeat. This is the one chokepoint every repeat_steer caller
        // shares, so no push site can leak it.
        Some(crate::ocap::redact_session_ingress(&raw))
    }

    fn successful_fetch_url(name: &str, args: &serde_json::Value, result: &str) -> Option<String> {
        if name != "web_fetch" {
            return None;
        }
        let url = args.get("url")?.as_str()?.trim();
        if url.is_empty() || result.trim().is_empty() {
            None
        } else {
            Some(url.chars().take(200).collect())
        }
    }

    fn successful_read_only_shell_command(
        name: &str,
        args: &serde_json::Value,
        result: &str,
    ) -> Option<String> {
        if name != "run_command" || result.trim().is_empty() {
            return None;
        }
        let command = args.get("command")?.as_str()?.trim();
        if is_read_only_shell_probe(command) {
            Some(command.chars().take(200).collect())
        } else {
            None
        }
    }

    /// #718: classify a SUCCESS-shaped result that is empty *by design* — it
    /// passes `tool_result_ok` (ok=true) so the failure path never sees it, yet
    /// the model loops the identical call. Pure; keyed on the exact result
    /// prefixes (`recall.rs` keeps "no matches in past conversations";
    /// `scratchpad.rs` returns "no such key: ..."). `None` when the result
    /// carries real content (nothing to steer).
    fn no_result_reason(name: &str, result: &str) -> Option<&'static str> {
        match name {
            "recall" if result.starts_with("no matches in past conversations") => Some(
                "it returned no matches (and recall cannot see the current conversation \
                 — use resume_context for THIS conversation)",
            ),
            "state_get" if result.starts_with("no such key") => {
                Some("the key is not set (state_get returned \"no such key\")")
            }
            "plan_get" if result.starts_with("no active plan") => Some(
                "it found no active plan; call update_plan now with a short ordered plan if the \
                 work has more than one step",
            ),
            _ => None,
        }
    }

    /// Classify a just-executed call into the subset of outcomes that should
    /// steer an exact repeat. This function sees all calls, but deliberately
    /// returns `None` for ordinary successes so valid repeated work (builds,
    /// tests, rereads after edits, write-capable commands) can keep running.
    fn classify_repeat_memo(
        name: &str,
        args: &serde_json::Value,
        ok: bool,
        result: &str,
        execution: Option<crate::ExecOutcome>,
    ) -> Option<RepeatMemo> {
        if !ok {
            let lower = result.to_ascii_lowercase();
            return Some(RepeatMemo::Failure {
                first_line: first_line(result),
                retry_after_grant: CONFINEMENT_DENIAL_NEEDLES
                    .iter()
                    .any(|needle| lower.contains(needle))
                    || (matches!(name, "run_command" | "lifecycle")
                        && matches!(
                            execution,
                            Some(crate::ExecOutcome::Failed | crate::ExecOutcome::Denied)
                        )),
            });
        }
        if let Some(reason) = Self::no_result_reason(name, result) {
            return Some(RepeatMemo::NoResult {
                reason: reason.to_string(),
            });
        }
        if let Some(url) = Self::successful_fetch_url(name, args, result) {
            return Some(RepeatMemo::EvidenceObserved {
                subject: format!("`{url}`"),
                advice: "use the fetched content above, fetch a different URL, inspect local \
                         files, or answer the user.",
            });
        }
        if let Some(command) = Self::successful_read_only_shell_command(name, args, result) {
            return Some(RepeatMemo::EvidenceObserved {
                subject: format!("read-only shell probe `{command}`"),
                advice: "use the observed output above, change the query, inspect a different \
                         file, or make the next edit/test decision.",
            });
        }
        if name == "use_skill" && !result.trim().is_empty() {
            return Some(RepeatMemo::SkillRead);
        }
        if let Some(path) = Self::bare_read_file_path(name, args) {
            // #2637 review P1: the identity must describe exactly the bytes
            // SERVED (`result`), never a separate reread of the path —
            // rereading here races an out-of-band edit landing between the
            // tool's real read (which produced `result`) and this
            // classification, joining two different observations under one
            // hash (read A → edit → hash B → memo says "A, id(B)" → a later
            // unchanged B serves stale A). Hashing `result` itself has no
            // such window: there is only one read.
            let content_id = content_addressable::RawContentId::from_content(result.as_bytes());
            return Some(RepeatMemo::ReadRange {
                path,
                content_id,
                content: result.to_string(),
            });
        }
        None
    }

    /// #2555: the path of a `read_file` call with NO explicit `offset`/`limit`
    /// — the shape a weak model repeats byte-for-byte when it re-pages a file
    /// it already has. A call that names an explicit range is a deliberate
    /// scan and is never memoized (it always runs, whatever the outcome).
    fn bare_read_file_path(name: &str, args: &serde_json::Value) -> Option<String> {
        if name != "read_file" || args.get("offset").is_some() || args.get("limit").is_some() {
            return None;
        }
        Some(args.get("path")?.as_str()?.to_string())
    }

    /// #2637: silently serve an exact bare `read_file` repeat when it is
    /// PROVEN unchanged right now, per the harness doctrine (never refuse a
    /// successful re-read; make the redundant one cheap and silent instead).
    /// A mismatch or an unprovable freshness check drops the memo and returns
    /// `None`, so the caller falls through to a real read — which then
    /// re-memoizes from the real outcome. This never itself denies access.
    fn cached_read(
        &mut self,
        name: &str,
        args: &serde_json::Value,
        read_scope: ReadScope<'_>,
    ) -> Option<String> {
        // Skills are already served procedural content, not refusal evidence.
        // A short success avoids repeating their body while it remains in context.
        if name == "use_skill"
            && matches!(
                self.repeat_memos.get(&Self::key(name, args)),
                Some(RepeatMemo::SkillRead)
            )
        {
            let skill = args
                .get("name")
                .and_then(serde_json::Value::as_str)
                .unwrap_or("");
            return Some(format!("Skill `{skill}` is loaded in the current context."));
        }
        let path = Self::bare_read_file_path(name, args)?;
        let key = Self::key(name, args);
        let Some(RepeatMemo::ReadRange {
            content_id,
            content,
            ..
        }) = self.repeat_memos.get(&key)
        else {
            return None;
        };
        if read_scope.content_id_of(&path).as_ref() == Some(content_id) {
            Some(content.clone())
        } else {
            self.repeat_memos.remove(&key);
            None
        }
    }

    /// Record a just-executed call's outcome. Failures are also counted for
    /// run diagnostics; success-shaped memos are not hard failures.
    fn record(
        &mut self,
        name: &str,
        args: &serde_json::Value,
        ok: bool,
        result: &str,
        execution: Option<crate::ExecOutcome>,
        // #2637 review P1: no longer used to mint the `ReadRange` content id
        // (that now hashes `result` directly — see `classify_repeat_memo`),
        // kept so every call site still threads the confinement scope it
        // would need if a future memo kind requires it.
        _read_scope: ReadScope<'_>,
    ) {
        if tools::permission_grant_succeeded(name, args, ok, result, execution) {
            self.repeat_memos.retain(|_, memo| {
                !matches!(
                    memo,
                    RepeatMemo::Failure {
                        retry_after_grant: true,
                        ..
                    }
                )
            });
        }
        // #2374/F37: a failure memo describes the tree it ran against. After a
        // real workspace change the identical call is the re-check the repair
        // loop needs, so the memo is released in every mode. #2555: a
        // `ReadRange` memo is released the same way — ANY workspace change
        // (not just an edit of the memoized file) invalidates "nothing has
        // changed since", because the model's next read is asking about the
        // tree it just modified.
        if ok && may_change_workspace(name, args) {
            self.repeat_memos.retain(|_, memo| {
                !matches!(
                    memo,
                    RepeatMemo::Failure { .. }
                        | RepeatMemo::ReadRange { .. }
                        | RepeatMemo::SkillRead
                )
            });
        }
        if name == "update_plan" && ok {
            self.repeat_memos.retain(|key, _| {
                !key.starts_with("plan_get\u{1}") && !key.starts_with("update_plan\u{1}")
            });
        }
        if !ok {
            *self.fails_by_tool.entry(name.to_string()).or_default() += 1;
        }
        if let Some(memo) = Self::classify_repeat_memo(name, args, ok, result, execution) {
            self.repeat_memos.insert(Self::key(name, args), memo);
        }
    }

    /// Total failed tool executions this run (across all tools) — a signal that
    /// a cap exit was thrash, not lack of rounds (Step 27.5).
    fn total_failures(&self) -> usize {
        self.fails_by_tool.values().sum()
    }

    /// #2555/#2799: release context-held file and skill read memos. Called at the ONE checkpoint
    /// each backend loop's compaction reaches once it actually fires
    /// (`record_compaction_artifact` for the three legacy chat loops;
    /// `compact_responses_input`'s `Compacted` outcome for the Responses
    /// loop) — never on a rejected/no-op compaction attempt, which changed
    /// nothing the model could have already seen.
    fn release_read_memos(&mut self) {
        self.repeat_memos.retain(|_, memo| {
            !matches!(memo, RepeatMemo::ReadRange { .. } | RepeatMemo::SkillRead)
        });
    }
}

#[derive(Debug, Clone, Copy)]
enum ProgressSnapshot {
    File(content_addressable::ContentId),
    Tree(content_addressable::ContentId),
}

/// Reuse the object-bound file receipt capture for named mutations and the
/// bounded tree observer for shell commands. Unavailable observations prove
/// nothing; read-only calls never scan a workspace.
async fn progress_workspace_state(
    name: &str,
    args: &serde_json::Value,
    workspace: &str,
    fs_read: &crate::caveats::Scope<String>,
) -> Option<ProgressSnapshot> {
    if !matches!(
        name,
        "run_command" | "write_file" | "edit_file" | "delete_file" | "lifecycle" | "git"
    ) || !may_change_workspace(name, args)
    {
        return None;
    }
    let root = std::path::PathBuf::from(workspace);
    let target = matches!(name, "write_file" | "edit_file" | "delete_file")
        .then(|| args.get("path").and_then(serde_json::Value::as_str))
        .flatten()
        .map(|path| lexical_normalize(&root.join(path)));
    let fs_read = fs_read.clone();
    tokio::task::spawn_blocking(move || {
        if let Some(target) = target {
            use tools::file_capture::TextSnapshot;
            let version = match tools::file_capture::capture(&fs_read, &target) {
                TextSnapshot::Present(text) => Some(Some(
                    content_addressable::RawContentId::from_content(text.as_bytes()),
                )),
                TextSnapshot::Absent => Some(None),
                TextSnapshot::Unavailable(_) => None,
            };
            if let Some(version) = version {
                let bytes = content_addressable::canonical::to_canonical_dagcbor(&(
                    target.to_string_lossy(),
                    version,
                ))
                .ok()?;
                return Some(ProgressSnapshot::File(
                    content_addressable::ContentId::from_canonical_bytes(&bytes),
                ));
            }
        }
        if !crate::caveats::permits_path(&fs_read, &root.to_string_lossy()) {
            return None;
        }
        self_verify::workspace_tree_state(&root).map(ProgressSnapshot::Tree)
    })
    .await
    .ok()
    .flatten()
}

#[derive(Debug, Default)]
struct WorkflowRuntimeState {
    /// Runtime-only sets: the existing content-addressable crate identifies
    /// evidence, so rereads and short cycles cannot purchase more inference.
    observed_results: std::collections::HashSet<content_addressable::RawContentId>,
    verified_checks: std::collections::HashSet<content_addressable::ContentId>,
    observed_trees: std::collections::HashSet<content_addressable::ContentId>,
    progress_revision: usize,
    last_cap_progress_revision: usize,
    rounds_since_progress: Option<usize>,
    /// Override for [`WORKFLOW_RECENT_PROGRESS_ROUNDS`], set once per turn from
    /// the matching [`crate::WorkflowSteerer`] workflow's
    /// `progress_horizon_rounds` (diagnostic workflows legitimately need more
    /// read-only rounds between plan/edit checkpoints than routine edits do —
    /// see `diagnose_failure.toml`). `None` uses the shared default.
    progress_horizon_rounds: Option<usize>,
    /// How much to let the model look before pushing it to act. Set once per
    /// turn from [`crate::initiative::effective_initiative`]; `Default` is
    /// `Measured`, the behaviour-preserving level.
    initiative: crate::initiative::Initiative,
    /// Consecutive tool rounds this turn that modified nothing in the workspace.
    /// Reset on any workspace-write round; drives the initiative action-forcing
    /// nudge.
    consecutive_read_only_rounds: usize,
    /// U4b: the no-progress brake's thresholds (`[initiative.no_progress]`),
    /// captured once per turn beside `initiative`.
    no_progress: crate::initiative::NoProgressRounds,
    /// Completed rounds since the last progress. Counted by the GATE at the start
    /// of each round, not by `record_round_outcome`, so a round that `continue`s
    /// (narration nudge, id-less re-ask) is counted too. Separate from
    /// `consecutive_read_only_rounds` on purpose: that counter RESETS whenever its
    /// nudge fires, so it cannot measure a whole stall.
    rounds_without_change: usize,
    /// The one steer for this stall has been sent.
    no_progress_steered: bool,
    /// Fresh evidence, an observed workspace change, or a newly verified check
    /// in the completed round; consumed by the next gate.
    round_progressed: bool,
}

/// What the no-progress brake wants done at the start of a round.
enum NoProgress {
    Continue,
    /// Inject this one steer.
    Steer(String),
    /// End the turn: `TurnEndReason::NoProgress`, harness-written notice.
    Stop,
}

impl WorkflowRuntimeState {
    /// Set once per turn from the matching workflow's horizon override, if
    /// any. A no-op call (`None`) leaves the shared default in effect.
    fn set_progress_horizon(&mut self, rounds: Option<usize>) {
        self.progress_horizon_rounds = rounds;
    }

    fn progress_horizon(&self) -> usize {
        self.progress_horizon_rounds
            .unwrap_or(WORKFLOW_RECENT_PROGRESS_ROUNDS)
    }

    fn record_workspace_change(
        &mut self,
        before: Option<ProgressSnapshot>,
        after: Option<ProgressSnapshot>,
    ) -> bool {
        let (before, after) = match (before, after) {
            (Some(ProgressSnapshot::File(before)), Some(ProgressSnapshot::File(after)))
            | (Some(ProgressSnapshot::Tree(before)), Some(ProgressSnapshot::Tree(after))) => {
                (before, after)
            }
            // A capture that hit a bound on only one side has no comparable
            // proof. Never compare a file observation with a whole tree.
            _ => return false,
        };
        self.observed_trees.insert(before);
        let changed = before != after && self.observed_trees.insert(after);
        if changed {
            self.verified_checks.clear();
        }
        changed
    }

    /// A passing check earns progress once per changed workspace, independent
    /// of its timings or other variable stdout. Other substantive results earn
    /// progress once by their bytes. Plans and no-op write receipts do not.
    fn record_observation(
        &mut self,
        name: &str,
        args: &serde_json::Value,
        result: &str,
        ok: bool,
        execution: Option<crate::ExecOutcome>,
        routed_to: Option<&(&'static str, serde_json::Value)>,
    ) -> bool {
        if ok && is_progress_verification(name, args, execution, routed_to) {
            let mut call = routed_to
                .map(|(name, args)| (*name, args.clone()))
                .unwrap_or_else(|| (name, args.clone()));
            // Timeout and output presentation do not change what was verified.
            // Retain the routed command, argv, cwd, and other check arguments.
            if let ("build_exec", serde_json::Value::Object(args)) = &mut call {
                args.remove("timeout_secs");
                args.remove("trim");
                args.remove("echo_dropped");
            }
            return content_addressable::canonical::to_canonical_dagcbor(&call)
                .ok()
                .is_some_and(|bytes| {
                    self.verified_checks
                        .insert(content_addressable::ContentId::from_canonical_bytes(&bytes))
                });
        }
        // Passing non-gate build phases do not prove new work. The tool's
        // recorded route, never a text/keyword guess, identifies these.
        if execution == Some(crate::ExecOutcome::Passed)
            && (name == "lifecycle" || routed_to.is_some_and(|(name, _)| *name == "build_exec"))
        {
            return false;
        }
        if result.trim().is_empty()
            || is_workspace_write_call(name)
            || matches!(
                name,
                "update_plan" | "state_set" | "state_clear" | "render_report"
            )
            || tools::is_context_remaining_call(name)
            || (!ok && workflow_error_fingerprint(result).is_none())
        {
            return false;
        }
        let error = (!ok).then(|| workflow_error_fingerprint(result)).flatten();
        self.observed_results
            .insert(content_addressable::RawContentId::from_content(
                error.as_deref().unwrap_or(result).as_bytes(),
            ))
    }

    /// Operator steering was delivered this round. A human steer is new
    /// information the model has not yet acted on, so it restarts the count (and
    /// re-arms the steer-once latch) exactly like progress; otherwise a stop on
    /// the very next statement would throw the operator's words away unread.
    fn note_operator_steering(&mut self) {
        self.round_progressed = true;
    }

    /// U4b: called at the start of every round after the first. First it counts
    /// the round that just completed (idle unless it progressed), then decides.
    /// Applies to read-only loops too; `0` disables that half of the brake.
    /// The STOP is a cost bound and always applies; the STEER is advice, so the
    /// caller passes `steer_allowed = action_nudges`.
    fn no_progress_verdict(&mut self, steer_allowed: bool) -> NoProgress {
        if std::mem::take(&mut self.round_progressed) {
            self.rounds_without_change = 0;
            self.no_progress_steered = false;
        } else {
            self.rounds_without_change = self.rounds_without_change.saturating_add(1);
        }
        let (n, cfg) = (self.rounds_without_change, self.no_progress);
        if cfg.stop_after > 0 && n >= cfg.stop_after {
            return NoProgress::Stop;
        }
        if steer_allowed && cfg.steer_after > 0 && n >= cfg.steer_after && !self.no_progress_steered
        {
            self.no_progress_steered = true;
            return NoProgress::Steer(format!(
                "No progress: {n} rounds produced no new evidence, workspace change, or newly \
                 verified check. Stop repeating the same observations. Stop varying \
                 the command. Say what is done and what is not done, then stop."
            ));
        }
        NoProgress::Continue
    }

    /// The harness-written reply when the brake ends the turn.
    fn no_progress_notice(&self) -> String {
        format!(
            "Stopped: {} consecutive rounds produced no new evidence, workspace change, or \
             newly verified check. Work done so far is left in the workspace.",
            self.rounds_without_change
        )
    }

    fn record_round_outcome(&mut self, round_wrote: bool, round_progress: bool) {
        // Only concrete progress renews the round allowance. The gate also
        // counts rounds which continue before reaching this hook.
        if round_wrote || round_progress {
            self.round_progressed = true;
            self.progress_revision = self.progress_revision.saturating_add(1);
        }
        // Initiative counter: consecutive rounds that changed nothing
        // in the workspace, independent of whether a tool failed.
        if round_wrote {
            self.consecutive_read_only_rounds = 0;
        } else {
            self.consecutive_read_only_rounds = self.consecutive_read_only_rounds.saturating_add(1);
        }
        if round_wrote || round_progress {
            self.rounds_since_progress = Some(0);
        } else if let Some(rounds) = self.rounds_since_progress.as_mut() {
            *rounds = rounds.saturating_add(1);
        }
    }

    /// Initiative action-forcing nudge: once the model has spent the initiative
    /// level's budget of consecutive read-only rounds without touching the
    /// workspace, inject the standard "stop exploring, make the change" nudge
    /// and reset the counter so it re-accumulates before firing again. This is
    /// the answer to the measured ceiling where a capable model reads/plans for
    /// its whole budget and never edits. `Measured` (budget 3 by default)
    /// reproduces the historical Ollama-loop threshold; higher levels force sooner.
    fn action_forcing_nudge(
        &mut self,
        hard_rounds_remaining: Option<usize>,
        step_ledger: Option<&dyn scheduled::StepLedger>,
        delegate_hint: Option<&str>,
    ) -> Option<String> {
        if self.consecutive_read_only_rounds < self.initiative.read_only_nudge_after() {
            return None;
        }
        let nudge = read_only_action_nudge(
            self.consecutive_read_only_rounds,
            hard_rounds_remaining,
            step_ledger,
            delegate_hint,
        );
        self.consecutive_read_only_rounds = 0;
        Some(nudge)
    }

    /// Renew silently only for evidence acquired since the previous renewal.
    /// This is independent of model nudges and shared by every provider loop.
    /// Call/cost budgets remain enforced by the existing attempt admission.
    fn admit_round(&mut self, round: usize, limit: &mut usize, grace: usize) -> bool {
        if round < *limit {
            return true;
        }
        if !self.can_renew(grace) {
            return false;
        }
        self.last_cap_progress_revision = self.progress_revision;
        *limit = limit.saturating_add(grace);
        round < *limit
    }

    fn can_renew(&self, grace: usize) -> bool {
        grace > 0
            && self.progress_revision > self.last_cap_progress_revision
            && self
                .rounds_since_progress
                .is_some_and(|rounds| rounds <= self.progress_horizon())
    }

    /// Completion gates must not report an exhausted allowance when the next
    /// boundary can renew it from concrete progress already observed.
    fn has_next_round(&self, round: usize, limit: usize, grace: usize) -> bool {
        round.saturating_add(1) < limit || self.can_renew(grace)
    }
}

fn workflow_error_fingerprint(result: &str) -> Option<String> {
    // #2561: missing, unwritable, or undeletable paths are real tool failures,
    // but a new wrong-path probe is not progress toward resolving a build.
    if result.lines().next().is_some_and(|first| {
        first.starts_with("error: reading ")
            || first.starts_with("error: writing ")
            || first.starts_with("error: deleting ")
    }) {
        return None;
    }
    build_error_fingerprint(result).or_else(|| edit_miss_fingerprint(result))
}

fn build_error_fingerprint(result: &str) -> Option<String> {
    let mut pending_error: Option<String> = None;
    let mut fingerprints = Vec::new();
    for line in result.lines() {
        let trimmed = line.trim();
        if trimmed.starts_with("error[") || trimmed.starts_with("error:") {
            pending_error = Some(normalize_error_line(trimmed));
            continue;
        }
        if let Some(rest) = trimmed.strip_prefix("-->") {
            if let Some(error) = pending_error.take() {
                let location = rest
                    .split_whitespace()
                    .next()
                    .unwrap_or("")
                    .trim()
                    .trim_start_matches("./");
                if location.is_empty() {
                    fingerprints.push(error);
                } else {
                    fingerprints.push(format!("{location} {error}"));
                }
                if fingerprints.len() >= 3 {
                    break;
                }
            }
        }
    }
    if fingerprints.is_empty() {
        pending_error.map(|e| e.chars().take(240).collect())
    } else {
        Some(fingerprints.join(" | ").chars().take(500).collect())
    }
}

fn edit_miss_fingerprint(result: &str) -> Option<String> {
    let lc = result.to_ascii_lowercase();
    if !(lc.contains("old_string")
        && (lc.contains("not found")
            || lc.contains("old string not found")
            || lc.contains("matches 0")
            || lc.contains("no match")))
    {
        return None;
    }
    let line = result
        .lines()
        .find(|line| {
            let l = line.to_ascii_lowercase();
            l.contains("old_string")
                && (l.contains("not found") || l.contains("matches 0") || l.contains("no match"))
        })
        .unwrap_or("edit_file old_string not found");
    Some(format!("edit_file {}", normalize_error_line(line)))
}

fn normalize_error_line(line: &str) -> String {
    let mut out = String::new();
    let mut in_ws = false;
    for c in line.chars() {
        if c.is_whitespace() {
            if !in_ws {
                out.push(' ');
                in_ws = true;
            }
        } else if c != '`' {
            out.push(c);
            in_ws = false;
        }
    }
    out.chars().take(240).collect()
}

fn active_step_description(step_ledger: Option<&dyn scheduled::StepLedger>) -> Option<String> {
    let snapshot = step_ledger?.snapshot();
    snapshot
        .steps
        .iter()
        .find(|step| step.status == StepStatus::Active)
        .or_else(|| {
            snapshot
                .steps
                .iter()
                .find(|step| step.status != StepStatus::Done)
        })
        .map(|step| step.description.clone())
}

fn workflow_guidance(direction: impl std::fmt::Display) -> String {
    format!(
        "{direction} {REFACTOR_PUBLISH_GUIDANCE} Guidance is advisory: follow the latest operator instruction, including \
         newer steering. Honor stop or report-only requests. Reconcile changed plans with \
         update_plan; preserve completed work."
    )
}

const PERMISSION_RECOVERY_GUIDANCE: &str =
    "Use an already-authorized alternative if permitted. For an exact requestable grant with \
     an available operator, call request_permissions once. Never re-ask for or retry a permission \
     the operator declined, or ask again with no operator available. Do not bypass a refusal.";

/// Render saved plan, scratchpad and task worktree at a cap exit, so partial
/// work is salvaged into the final summary / fallback instead of being lost
/// (Step 27.5, #2766). `None` when all are empty.
fn cap_exit_progress(
    worktree_session: Option<&crate::worktree_adoption::WorktreeSession>,
    step_ledger: Option<&dyn scheduled::StepLedger>,
    scratchpad_store: Option<&dyn scratchpad::ScratchpadStore>,
) -> Option<String> {
    let plan = step_ledger.and_then(scheduled::plan_block);
    let state = scratchpad_store.and_then(scratchpad::scratchpad_state_block);
    let task = worktree_session.and_then(crate::worktree_adoption::WorktreeSession::task_hint);
    let parts: Vec<String> = [plan, state, task].into_iter().flatten().collect();
    (!parts.is_empty()).then(|| parts.join("\n\n"))
}

fn is_read_only_tool(name: &str) -> bool {
    crate::navigator::NAV_TOOL_NAMES.contains(&name)
        || matches!(
            name,
            "list_dir"
                | "read_file"
                | "find"
                | "search"
                | "web_fetch"
                | "use_skill"
                | "save_note"
                | "recall"
                | "prompt_read"
                | "artifact_read"
        )
}

fn is_read_only_call(name: &str, args: &serde_json::Value) -> bool {
    is_read_only_tool(name)
        || (name == "git"
            && args
                .get("op")
                .and_then(|op| op.as_str())
                .is_some_and(git_tool::is_scoped_read_op))
        || (name == "run_command"
            && args
                .get("command")
                .and_then(|v| v.as_str())
                .is_some_and(is_read_only_shell_probe))
}

/// The tools that actually modify the workspace tree — `write_file` and
/// `edit_file`. Aliases the model sometimes invents (`create_file`,
/// `str_replace`, `apply_patch`) get a coaching reply and change nothing, so
/// they are deliberately NOT in the set.
///
/// Public because the `solve_result` trace line reports on writes too, and a
/// second copy of this literal set in the CLI is exactly the drift the reuse
/// discipline forbids: adding a write tool here would silently stop being
/// counted there.
pub fn is_workspace_write_call(name: &str) -> bool {
    matches!(name, "write_file" | "edit_file")
}

/// U4b: did this completed call PASS a progress-evidencing check — a `lifecycle`
/// run of a gate phase (`test`/`check`, [`crate::tooling::Phase::is_gate`]), or a
/// `run_command` ROUTED to the confined build lane (#2533/#2543's
/// `routing::RouteTable`) whose subcommand IS a gate — `cargo test`/`cargo
/// check`, or a `just` recipe literally named `test`/`check`? Mirrors
/// `Phase::is_gate` exactly (`Phase::from_key` happens to share its "test"/
/// "check" keys with cargo's own subcommand strings and with a recipe name,
/// so this is the SAME rule, not a parallel one): `cargo build` (an
/// incremental no-op when already built), `cargo clippy`, and a `just fmt`/
/// `just clean` all route to `build_exec` too but do NOT count — #2548
/// round 2's should-fix, because the lifecycle side never counted `lint`/
/// `format`/`clean`/`setup` either, and a model alternating `edit_file` with
/// a trivially-passing `just fmt` must not reset the brake.
///
/// A bare `run_command` is still deliberately excluded: a shell exit code is
/// not evidence of a passing build (`| tail` masks it — see
/// `WorkflowRuntimeState::record_observation`), and recognising build commands by keyword
/// would be an invented classifier. #2551 round 2 (should-fix): this used to
/// RE-DERIVE the route via a second `classify_call`, which reads the
/// filesystem — and the call in between can change it. Measured: `cd
/// target; cargo test | tail -5` on a clean checkout refuses to route at
/// DISPATCH (`target/` does not exist yet) and runs unrouted at the root,
/// where `cargo test` CREATES `target/` and `| tail` masks the exit code;
/// re-classifying AFTER the call then routes successfully and would have
/// counted exactly the masked pass #2548 exists to exclude. `routed_to` is
/// dispatch's OWN recorded decision (`tools.rs`'s routing site, the same
/// place that decided what actually ran) — read here, never recomputed —
/// so verification cannot see a filesystem state dispatch never acted on.
fn is_progress_verification(
    name: &str,
    args: &serde_json::Value,
    execution: Option<crate::ExecOutcome>,
    routed_to: Option<&(&'static str, serde_json::Value)>,
) -> bool {
    if execution != Some(crate::ExecOutcome::Passed) {
        return false;
    }
    if name == "lifecycle" {
        return args
            .get("phase")
            .and_then(|v| v.as_str())
            .and_then(crate::tooling::Phase::from_key)
            .is_some_and(crate::tooling::Phase::is_gate);
    }
    if name != "run_command" {
        return false;
    }
    let Some(("build_exec", routed)) = routed_to.map(|(tool, args)| (*tool, args)) else {
        return false;
    };
    // `argv[0]` is the program (`cargo`/`just`); `argv[1]` is cargo's
    // subcommand or the just recipe name — the SAME slot `Phase::from_key`
    // reads for `lifecycle`, so one function decides "is this a gate" for
    // both call shapes. #2524 follow-up: `cargo_build_route` keeps a
    // leading `+toolchain` selector (`cargo +stable test`) in `argv`, so
    // that slot may be `argv[1]` (`+stable`) instead of the subcommand —
    // skip it with the SAME `is_toolchain_selector` `cargo_build_route`
    // itself checks, shared rather than re-derived, so the two can never
    // disagree about what counts as a selector.
    let Some(argv) = routed.get("argv").and_then(|v| v.as_array()) else {
        return false;
    };
    let sub = match argv.get(1).and_then(|v| v.as_str()) {
        Some(token) if routing::is_toolchain_selector(token) => {
            argv.get(2).and_then(|v| v.as_str())
        }
        other => other,
    };
    sub.and_then(crate::tooling::Phase::from_key)
        .is_some_and(crate::tooling::Phase::is_gate)
}

/// #2374: built-in tools that never touch workspace files: harness state,
/// plans, retrieval, operator prompts, mode switches.
fn is_workspace_inert_tool(name: &str) -> bool {
    matches!(
        name,
        "code_search"
            | "where_is"
            | "tool_search"
            | "memory_fetch"
            | "re_read"
            | "resume_context"
            | "experience_recall"
            | "experience_record"
            | "state_get"
            | "state_set"
            | "state_clear"
            | "plan_get"
            | "update_plan"
            | "render_report"
            | "request_permissions"
            | "request_user_input"
            | "select_operating_mode"
            | "enter_plan_mode"
            | "exit_plan_mode"
    ) || tools::is_context_remaining_call(name)
}

/// #2374: simple shell commands that only read. Used only by result-aware
/// verification, so the default path's probe steering is unchanged. It differs
/// from [`is_read_only_shell_probe`]'s list on purpose: `sed` is left out,
/// because `-ri`, `-Ei`, `--in-place` and its `w` command all write.
const VERIFICATION_READ_PROGRAMS: &[&str] = &[
    "grep",
    "rg",
    "head",
    "tail",
    "wc",
    "pwd",
    "cat",
    "ls",
    "find",
    "stat",
    "file",
    "tree",
    "git status",
    "git diff",
    "git log",
    "git show",
];

/// #2374: the tool a call reaches: a rewrite alias's canonical name, the name
/// itself otherwise, and `None` for a corrective alias, which only returns
/// coaching text.
pub(crate) fn dispatched_tool_name(name: &str) -> Option<&str> {
    match tools::resolve_tool_alias(name) {
        Some(tools::AliasOutcome::Correct(_)) => None,
        Some(tools::AliasOutcome::Rewrite(canonical)) => Some(canonical),
        None => Some(name),
    }
}

/// #2374: whether a call may have changed the workspace: anything that is
/// neither read-only nor a workspace-inert built-in, judged as the tool it
/// reaches. Unknown and MCP tools fail closed (they may).
pub(crate) fn may_change_workspace(name: &str, args: &serde_json::Value) -> bool {
    let Some(name) = dispatched_tool_name(name) else {
        return false;
    };
    if name == "run_command" {
        return args["command"]
            .as_str()
            .is_none_or(|command| !is_verification_read_command(command));
    }
    !is_read_only_call(name, args) && !is_workspace_inert_tool(name)
}

/// A single simple command that only reads: one of
/// [`VERIFICATION_READ_PROGRAMS`], with no shell metacharacters and no action
/// that writes or runs (`find -delete` / `-exec` / `-fprint`, `--output=`,
/// `tree -o`), however quotes or backslashes spell the token.
pub(crate) fn is_verification_read_command(command: &str) -> bool {
    let command = command.trim();
    const SHELL_META: &[char] = &['&', '|', ';', '`', '$', '\n', '>', '<', '(', ')'];
    if command.is_empty() || command.contains(SHELL_META) {
        return false;
    }
    let tokens: Vec<String> = command
        .split_whitespace()
        .map(|t| t.replace(['"', '\'', '\\'], ""))
        .collect();
    let acts = tokens.iter().any(|t| {
        t.starts_with("--output")
            || matches!(
                t.as_str(),
                "-delete"
                    | "-exec"
                    | "-execdir"
                    | "-ok"
                    | "-okdir"
                    | "-fprint"
                    | "-fprint0"
                    | "-fprintf"
                    | "-fls"
            )
    }) || (tokens[0] == "tree" && tokens.iter().any(|t| t == "-o"));
    if acts {
        return false;
    }
    VERIFICATION_READ_PROGRAMS
        .iter()
        .any(|p| command == *p || command.starts_with(&format!("{p} ")))
}

/// Redact a model-/user-facing string through the session disclosure filter,
/// if one is registered. Used for the final-summary path — the model's own
/// answer may echo a secret it read earlier, so it is value-filtered before it
/// leaves the loop, the same by-value gate the tool-result chokepoint applies.
/// `None` (no session filter) is bit-for-bit identity.
fn redact_model_facing(disclosure: Option<&crate::ocap::DisclosureFilter>, text: String) -> String {
    let text = match disclosure {
        Some(filter) => filter.redact(&text),
        None => text,
    };
    // TLS backstop (step-6.6): the same session filter, so the summary path is
    // covered even where the explicit `disclosure` param is not threaded.
    crate::ocap::redact_session_ingress(&text)
}

fn maybe_offload_tool_result(
    name: &str,
    result: String,
    tool_offload: bool,
    spill_store: Option<&dyn content_spill::SpillStore>,
    disclosure: Option<&crate::ocap::DisclosureFilter>,
) -> String {
    let out = if matches!(
        name,
        "run_command" | "lifecycle" | "prompt_read" | "artifact_read" | "memory_fetch"
    ) {
        result
    } else {
        // Thread the tool name into provenance so a tool output and an identical-looking
        // compaction span never share an address (content_spill binds provenance).
        content_spill::maybe_offload(result, tool_offload, Some(name.to_string()), spill_store)
    };
    // step-6.1a (`disclosure-gate-live-path`): the SINGLE live-path disclosure
    // chokepoint. Every tool result — including the early-return tools above,
    // which the offload/spill redaction never touched — passes the by-VALUE
    // filter before it becomes a `{"role":"tool"}` message, so a registered
    // session secret / canary cannot reach the model verbatim in-turn, in ANY
    // encoding (raw / base64 / hex / chunk-split). The explicit `disclosure`
    // param redacts when threaded; the TLS session filter (installed per turn)
    // is the uniform backstop, so even a caller that forgot the param can't
    // place tool-derived text into model context unfiltered (step-6.6).
    let out = match disclosure {
        Some(filter) => filter.redact(&out),
        None => out,
    };
    crate::ocap::redact_session_ingress(&out)
}

#[allow(clippy::too_many_arguments)]
fn record_compaction_artifact(
    // #2555: this is the ONE checkpoint every compaction that actually fired
    // reaches, across all three legacy chat loops (the Responses loop's
    // equivalent single entry point is `compact_responses_input`) — so it is
    // also where the repeat-read steer memo is released. A post-compaction
    // re-read is legitimate (the working-set card no longer holds the page),
    // so the memo must not outlive the compaction that invalidated it.
    repeat_calls: &mut RepeatCallGuard,
    artifact_sink: Option<&dyn artifact_read::PromptArtifactSink>,
    artifact_context: Option<artifact_read::ArtifactReadContext<'_>>,
    action: CompressAction,
    tokens_before: usize,
    tokens_after: usize,
    budget: usize,
    round: usize,
    reason: &str,
    trigger: Option<&CompressTrigger>,
    send_budget_authoritative: bool,
    // #1993: the SAME `CompressState` the caller already threads through
    // `compress()` — floor_trend is cross-round session state, not derived
    // from this one call's trigger/outcome, so it is passed independently
    // of `trigger` and is present on every checkpoint (recovery paths
    // included), not only the automatic-trigger ones.
    floor_trend: FloorTrend,
    color: bool,
) {
    repeat_calls.release_read_memos();
    let (Some(sink), Some(context)) = (artifact_sink, artifact_context) else {
        return;
    };
    if let Err(error) = artifact_hooks::record_compaction_checkpoint(
        sink,
        context,
        action,
        tokens_before,
        tokens_after,
        budget,
        round,
        reason,
        trigger,
        send_budget_authoritative,
        floor_trend,
    ) {
        print_harness_notice(
            &format!("warning: failed to record compaction artifact: {error}"),
            color,
        );
    }
}

fn is_read_only_shell_probe(command: &str) -> bool {
    let command = command.trim();
    if command.is_empty() {
        return false;
    }
    const SHELL_META: &[char] = &['&', '|', ';', '`', '$', '\n', '>', '<', '(', ')'];
    if command.contains(SHELL_META) {
        return false;
    }
    let mut tokens = command.split_ascii_whitespace();
    let Some(program) = tokens.next() else {
        return false;
    };
    match program {
        "grep" | "rg" | "head" | "tail" | "wc" | "pwd" => true,
        "sed" => !tokens.any(|t| t == "-i" || t.starts_with("-i")),
        _ => false,
    }
}

// The narrate-then-stop rescue budget is `ChatCtx.narration_nudge_cap`
// (`[tui] narration_nudge_cap`, default 1, per-model `[[model_tuning]]`
// override) — promoted from a hardcoded const here (lever L3). After the cap
// its narration is accepted as the final answer.
/// Max "you ended while a plan still has open steps" nudges per turn. This is
/// state-driven from the plan ledger, not prose-matched.
const PENDING_PLAN_NUDGE_CAP: usize = 1;
/// Max "generated hidden thinking but no visible content/tool call" retries per
/// turn. The first retry is generic; the second is explicit that hidden
/// thinking is not an action. Bounded so a broken backend still exits with the
/// diagnostic.
const SUSPICIOUS_EMPTY_RETRY_CAP: u32 = 2;
/// Max "you claimed file context changed under you without verifying" nudges
/// per turn. Kept separate from narration nudges: this is a blocker-specific
/// ground-truth check, not generic intent-to-act recovery.
const STALE_FILE_NUDGE_CAP: usize = 1;
const UNVERIFIED_EXEC_BLOCKER_NUDGE_CAP: usize = 1;

/// A model must not turn an assumption about `run_command` into a reported
/// capability wall. This detector is deliberately narrow: it requires the
/// concrete tool name plus denial/blocker language seen in live transcripts.
fn looks_like_unverified_run_command_blocker(content: &str) -> bool {
    let lower = content.to_ascii_lowercase();
    lower.contains("run_command")
        && [
            "permission-denied",
            "permission denied",
            "exec not granted",
            "capability wall",
            "run_command is unavailable",
            "run_command unavailable",
            "can't run",
            "cannot run",
        ]
        .iter()
        .any(|needle| lower.contains(needle))
}

fn run_command_is_advertised(tools: &serde_json::Value) -> bool {
    tools.as_array().is_some_and(|defs| {
        defs.iter().any(|def| {
            def.pointer("/function/name")
                .and_then(serde_json::Value::as_str)
                == Some("run_command")
                || (def.get("name").and_then(serde_json::Value::as_str) == Some("run_command"))
        })
    })
}

/// Result text that marks a REFUSED CAPABILITY in newt's OWN vocabulary — what
/// `tools::denied_fs_result` and the exec leash's `denied_run_command_result`
/// emit. Used by the exec-denial ground-truth check. An exit 126 with no
/// structured denial emits none of these (#2629 round 2): its note is
/// deliberately outside this vocabulary, so only the child's own
/// `Permission denied` (below) can ground a claim about it.
const CONFINEMENT_DENIAL_NEEDLES: [&str; 3] = [
    "not within the granted authority",
    "does not permit",
    "capability denied",
];

/// The OS's own words when the kernel refuses a fenced child. These ground
/// an exec-denial claim; they do not prescribe how the agent should recover.
const OS_PERMISSION_DENIAL_NEEDLES: [&str; 2] = ["permission denied", "permission-denied"];

fn run_command_result_is_denial(tool_name: &str, ok: bool, result: &str) -> bool {
    if tool_name != "run_command" || ok {
        return false;
    }
    let lower = result.to_ascii_lowercase();
    // The confined lane's refusal of a binary the host HAS coaches an exec
    // grant, so it is a grant gap; one not installed at all is not (#2304).
    (lower.contains(tools::ABSENT_BINARY_MARKER) && !lower.contains(tools::NOT_ON_HOST_MARKER))
        || CONFINEMENT_DENIAL_NEEDLES
            .iter()
            .chain(OS_PERMISSION_DENIAL_NEEDLES.iter())
            .any(|needle| lower.contains(needle))
}

fn run_command_ground_truth_nudge() -> &'static str {
    "Your capability-wall claim is unsupported: no returned run_command result \
     this turn contains an exec denial. If you have not probed the relevant \
     command, call run_command now and inspect its returned result. If a probe \
     succeeded, ground the answer in that success. Report a denial only when an \
     actual returned result contains one; otherwise continue the task."
}

fn should_ground_unverified_run_command_blocker(
    content: &str,
    tools: &serde_json::Value,
    denial_observed: bool,
    action_nudges: bool,
    nudges_used: usize,
    has_next_round: bool,
) -> bool {
    action_nudges
        && nudges_used < UNVERIFIED_EXEC_BLOCKER_NUDGE_CAP
        && has_next_round
        && run_command_is_advertised(tools)
        && !denial_observed
        && looks_like_unverified_run_command_blocker(content)
}

#[cfg(test)]
#[path = "mod_tests/exec_grounding_tests.rs"]
mod exec_grounding_tests;
/// Recent-progress horizon used to decide whether a configured workflow grace
/// window should activate at the normal round cap.
const WORKFLOW_RECENT_PROGRESS_ROUNDS: usize = 3;

fn tail_on_char_boundary(s: &str, max_bytes: usize) -> &str {
    let cut = s.len().saturating_sub(max_bytes);
    let start = (cut..=s.len())
        .find(|&i| s.is_char_boundary(i))
        .unwrap_or(0);
    &s[start..]
}

/// Compatibility wrapper for the narrate-then-stop classifier. Production turns
/// use [`crate::NudgeClassifier::load_default`] so `~/.newt/classifiers/nudge.toml`
/// can tune the examples; pure tests use the built-in prototypes here.
#[cfg(test)]
fn looks_like_intent_to_act(content: &str) -> bool {
    crate::NudgeClassifier::builtin().is_pending_action(content)
}

/// Completing an evidence question is independent of permission to mutate.
/// Reuse the classifier's bare-evidence-promise refinement. Findings, blockers,
/// and future plans can themselves be the requested read-only deliverable.
/// This is a conservative quality guard, not a general completion oracle.
fn readonly_completion_pending(
    disposition: PromptDisposition,
    classifier: &crate::NudgeClassifier,
    content: &str,
) -> bool {
    matches!(
        disposition,
        PromptDisposition::Explain | PromptDisposition::Research
    ) && classifier.classify(content).class == crate::NudgeClass::DeferredAnswer
}

/// One quality retry, never action pressure or a permission change. Keep its
/// state separate from action nudges so compaction cannot replenish the retry.
fn retry_readonly_completion(
    messages: &mut Vec<serde_json::Value>,
    content: &str,
    replay: Option<&[serde_json::Value]>,
    retried: &mut bool,
    more_rounds: bool,
) -> bool {
    if *retried || !more_rounds {
        return false;
    }
    *retried = true;
    strip_trailing_nudge_exchange(messages);
    // Responses reasoning items must precede their answer, unchanged.
    if let Some(items) = replay {
        messages.extend_from_slice(items);
    }
    messages.push(serde_json::json!({"role": "assistant", "content": content}));
    messages.push(serde_json::json!({
        "role": "user",
        "content": format!(
            "{} Your reply promised another step but did not answer the request. \
             Continue using only the read-only tools already available, or give the answer \
             supported by the evidence. If something is missing, ask a concrete clarification \
             or state the unresolved blocker. Do not end with another promise to check.",
            compress::LOOP_GUIDANCE_PREFIX
        ),
    }));
    true
}

#[allow(clippy::too_many_arguments)]
fn readonly_completion_handoff(
    content: &str,
    end_reason: &mut Option<&mut Option<crate::TurnEndReason>>,
    more_rounds: bool,
    workspace: &str,
    read_scope: &crate::Scope<String>,
    capability_evidence: &capability_check::Evidence,
    disclosure: Option<&crate::ocap::DisclosureFilter>,
    turn_claims: &claim_check::TurnClaims<'_>,
    verification: &self_verify::VerificationLedger,
) -> String {
    if let Some(slot) = end_reason {
        **slot = Some(if more_rounds {
            crate::TurnEndReason::NarrationCapExhausted
        } else {
            crate::TurnEndReason::NarrationFinalRound
        });
    }
    finalize_final_text(
        FinalReply::from(content.to_owned()).with_notice(
            "This response appears unfinished. If the request is still unresolved, \
             reply `continue` to resume the read-only check, or clarify what evidence you need."
                .into(),
        ),
        workspace,
        read_scope,
        capability_evidence,
        disclosure,
        turn_claims,
        verification,
    )
}

/// An explicit exit request is a handoff, not another planning round. Observe
/// it only after the whole batch has been recorded; later calls in that batch
/// still see the Plan clamp. The caller alone consumes and approves the request.
/// What the approval handoff knows about the round that just ended: the
/// Plan-disposition half of plan-before-act reads these to decide that the
/// operator's answer is the next useful event.
struct PlanRoundFacts<'a> {
    disposition: PromptDisposition,
    step_ledger: Option<&'a dyn StepLedger>,
    /// The ledger as the turn began, so only a plan recorded THIS turn can
    /// end it — a plan carried over from an earlier turn asks nothing.
    plan_at_turn_start: &'a scheduled::PlanSnapshot,
    /// The round added evidence or changed the workspace.
    progressed: bool,
}

fn pending_plan_approval_handoff(
    control: Option<&dyn PlanModeControl>,
    round: PlanRoundFacts<'_>,
    harness: Option<&smart_harness::SmartHarness>,
    cancel: Option<&std::sync::atomic::AtomicBool>,
    end_reason: &mut Option<&mut Option<crate::TurnEndReason>>,
) -> anyhow::Result<Option<String>> {
    // Plan-before-act, the Plan-disposition half. A turn that may not act,
    // whose multi-step plan was recorded this turn, and whose latest round
    // added nothing, has reached the operator's decision: request exit on
    // the model's behalf — the same request `exit_plan_mode` records — so
    // the question comes after one idle round. Measured without this on
    // 2026-10-07: a 35B model re-loaded the same two skills for twelve idle
    // rounds until the no-progress brake stopped it, then was asked anyway.
    if let Some(control) = control {
        let plan_recorded = round.step_ledger.is_some_and(|ledger| {
            scheduled::fresh_multi_step_plan(round.plan_at_turn_start, &ledger.snapshot())
        });
        if !control.exit_requested()
            && round.disposition == PromptDisposition::Plan
            && !round.progressed
            && plan_recorded
        {
            let _ = control.request_exit();
        }
    }
    if !control.is_some_and(PlanModeControl::exit_requested) {
        return Ok(None);
    }
    if is_cancelled(cancel) {
        return smart_harness::cancelled(harness, end_reason).map(Some);
    }
    let text = "Awaiting approval to leave plan mode.";
    if let Some(harness) = harness {
        harness.outcome(crate::TurnEndReason::AwaitingOperator, text)?;
    }
    if let Some(slot) = end_reason {
        **slot = Some(crate::TurnEndReason::AwaitingOperator);
    }
    Ok(Some(text.to_owned()))
}

/// Heuristic: did the model stop because it *believes* a file changed under it,
/// without first proving that via git/filesystem ground truth? This catches the
/// "stale line numbers ⇒ operator should restore the file" stall: a context
/// summary or partial read gets mistaken for a concurrent edit, and the model
/// stops instead of running read-only checks.
fn looks_like_unverified_stale_file_blocker(content: &str) -> bool {
    const FILE_CUES: &[&str] = &[
        "file",
        "line reference",
        "line references",
        "old_string",
        "edit_file",
        ".rs",
        ".toml",
        ".md",
    ];
    const STALE_CUES: &[&str] = &[
        "modified out from under",
        "changed out from under",
        "edited out from under",
        "modified concurrently",
        "changed concurrently",
        "stale context",
        "contexts are stale",
        "context is stale",
        "old line references",
        "line references are invalid",
        "file grew from",
        "grew from",
    ];
    const BLOCKER_CUES: &[&str] = &[
        "blocked",
        "cannot safely",
        "can't safely",
        "could land in the wrong place",
        "corrupt the code",
        "restore",
        "git checkout",
        "revert",
        "operator should",
        "human should",
        "recommendation",
    ];

    let lc = content.to_lowercase();
    let tail = tail_on_char_boundary(&lc, 1_200);
    FILE_CUES.iter().any(|c| tail.contains(c))
        && STALE_CUES.iter().any(|c| tail.contains(c))
        && BLOCKER_CUES.iter().any(|c| tail.contains(c))
}

/// The corrective injected when the model narrated its next action but emitted
/// no tool call (the narrate-then-stop stall). Sibling of [`read_only_action_nudge`].
fn narration_action_nudge() -> String {
    workflow_guidance(
        "You described what you were about to do but did not call any tool, so \
     nothing actually happened. If you intended to act, emit the tool call now \
     (for example edit_file or write_file with the real arguments) — do not just \
     describe it. If you are genuinely finished, say so explicitly in one \
     sentence.",
    )
}

/// The act-now directive appended after a mid-turn compaction replaced the
/// middle with a summary. The summary wrapper deliberately de-actions itself
/// ("REFERENCE ONLY" — weak models otherwise treat it as fresh instructions);
/// the inverse hazard is losing momentum entirely: post-compaction is exactly
/// where a weak model narrates instead of acting, and the corrective text of
/// an already-spent narration nudge may have just been summarized away. This
/// re-arms intent: mid-task, active step named, next output a tool call.
/// Carries [`compress::CONTINUATION_PREFIX`] so later compressions neither
/// anchor the tail on it nor keep more than one alive.
/// The operator's actual instruction for this turn comes from the caller's
/// authoritative task, not from rediscovering a user message in compacted
/// history. Compaction may retain an older conversation prompt while replacing
/// the current one with a lossy summary, so role-scanning cannot identify the
/// active task reliably (#1163, 2026-07-16 multi-turn repro).
fn post_compaction_continuation(
    worktree_session: Option<&crate::worktree_adoption::WorktreeSession>,
    step_ledger: Option<&dyn scheduled::StepLedger>,
    prompt_context: prompt_read::PromptReadContext<'_>,
) -> String {
    // Retain every step and status after compaction without making the saved
    // plan override a newer operator correction.
    let plan_clause = step_ledger
        .and_then(scheduled::plan_block)
        .map(|plan| {
            format!(
                " Your saved plan is below. Continue from the `→` step when it still \
                 matches the operator's request; otherwise reconcile it with update_plan:\n{plan}\n"
            )
        })
        .unwrap_or_default();
    // The exact prompt is already protected in the active-prompt metadata/user pair;
    // point at its immutable identity instead of injecting a lossy 400-char
    // quote as a fresh user message.
    let instruction_clause = prompt_context.active_receipt().map_or_else(
        || {
            " Re-read the protected [NEWT ACTIVE PROMPT v1] prompt pair (or call \
             prompt_read with address `current`) before continuing."
                .to_string()
        },
        |receipt| {
            format!(
                " The authoritative operator prompt is protected in the [NEWT ACTIVE \
                 PROMPT v1] metadata/user pair at address {} with model digest {}; call prompt_read \
                 with address `current` to recover it verbatim before continuing.",
                receipt.id(),
                receipt.model_digest()
            )
        },
    );
    let task_clause = worktree_session
        .and_then(crate::worktree_adoption::WorktreeSession::task_hint)
        .map(|hint| format!("\n{hint}\n"))
        .unwrap_or_default();
    workflow_guidance(format!(
        "{} You are mid-task: the context above was just compacted, not \
         completed.{instruction_clause}{plan_clause}{task_clause} For prompt-rooted work, \
         use artifact_read {{\"address\":\"root\"}} before deciding what remains. \
         When continuing, your next output should be the next concrete tool call; re-read \
         files before editing. To re-anchor on ground truth, check the current git branch and the last few \
         commits: earlier work may already be COMMITTED, so a clean working tree does NOT mean \
         no work happened. Preserve completed work; \
         do not repeat work the log shows is done or silently narrow the task.",
        compress::CONTINUATION_PREFIX
    ))
}

/// After a compaction pass replaced the middle with a summary (or the static
/// fallback), refund the narrate-then-stop rescue budget and (re-)append the
/// act-now continuation directive. The refund closes the counter/corrective
/// asymmetry: the spent-nudge counters are turn-locals that survive
/// compaction, while the corrective text they refer to lives in `messages`
/// and may have just been summarized away — leaving the harness refusing to
/// re-nudge a model that no longer remembers the correction. Prune-only and
/// fit passes keep the corrective text, so they neither refund nor anchor.
///
/// `enabled_mid_turn` combines action-nudge enablement and `round > 0`: the
/// pre-dispatch compaction also fires on round 0 of a FRESH turn (a long
/// session's between-turn growth is first measured there), where "You are
/// mid-task … do not summarize" would be false and would countermand an
/// informational ask ("summarize what we changed today") sitting right above
/// it. At round 0 nothing has been spent or lost, so the whole repair is
/// skipped. The optional directive is installed only if `admit` accepts the
/// candidate under the provider's existing request-budget contract. A rejected
/// hint leaves the compacted transcript intact; final dispatch preflight still
/// checks that transcript and refuses an irreducible oversized request.
#[allow(clippy::too_many_arguments)]
fn apply_post_compaction_continuation(
    worktree_session: Option<&crate::worktree_adoption::WorktreeSession>,
    messages: &mut Vec<serde_json::Value>,
    narration_nudges: &mut usize,
    action: CompressAction,
    step_ledger: Option<&dyn scheduled::StepLedger>,
    prompt_context: prompt_read::PromptReadContext<'_>,
    enabled_mid_turn: bool,
    admit: impl FnOnce(&[serde_json::Value]) -> bool,
) {
    if !enabled_mid_turn
        || !matches!(
            action,
            CompressAction::Summarized | CompressAction::StaticFallback
        )
    {
        return;
    }
    *narration_nudges = 0;
    // Prepare without mutating the transcript. Preserve the existing
    // continuation classification; all other messages stay byte-identical.
    let mut candidate = messages.clone();
    candidate.retain(|m| !compress::is_continuation_message(m));
    candidate.push(serde_json::json!({
        "role": "user",
        "content": post_compaction_continuation(worktree_session, step_ledger, prompt_context),
    }));
    if admit(&candidate) {
        *messages = candidate;
    }
}

/// The stronger corrective for the second and later narration nudges
/// (`[tui] narration_nudge_cap` > 1). The generic first nudge already failed
/// to convert intent into action, so this one is state-driven like
/// [`read_only_action_nudge`]: it names the active plan step and demands the
/// next output be a bare tool call.
fn escalated_narration_action_nudge(
    attempt: usize,
    cap: usize,
    step_ledger: Option<&dyn scheduled::StepLedger>,
) -> String {
    let step_clause = active_step_description(step_ledger)
        .map(|step| format!(" Active step: '{step}'."))
        .unwrap_or_default();
    workflow_guidance(format!(
        "Reminder {attempt}/{cap}: you again described an action without calling \
         a tool, so nothing has happened.{step_clause} Your NEXT output must be \
         exactly one tool call that starts that action (for example read_file, \
         edit_file, or run_command with real arguments) — no prose before it. \
         If you are blocked, state the one concrete blocker in a single \
         sentence instead of announcing more intentions."
    ))
}

fn stale_file_ground_truth_nudge() -> String {
    workflow_guidance(
        "You claimed the file changed under you or that your edit context is stale, \
     but you did not prove that with ground truth. Before stopping or asking the \
     operator to restore/revert anything, run read-only verification: git status \
     --short, git diff -- <file>, wc -l <file>, and re-read the exact target \
     range. If those checks do not prove an actual concurrent change, continue \
     from the verified file contents. Never recommend git checkout/revert unless \
     git diff proves unwanted changes and the operator approves.",
    )
}

fn workflow_classifier_text(messages: &[serde_json::Value], current_content: &str) -> String {
    let mut parts = Vec::new();
    let start = messages.len().saturating_sub(12);
    for message in &messages[start..] {
        if let Some(text) = message_text(message) {
            if !text.trim().is_empty() {
                parts.push(text);
            }
        }
    }
    if !current_content.trim().is_empty() {
        parts.push(current_content.to_string());
    }
    parts.join("\n")
}

fn combine_nudge_hints(first: Option<&str>, second: Option<&str>) -> Option<String> {
    let text = [first, second]
        .into_iter()
        .flatten()
        .map(str::trim)
        .filter(|hint| !hint.is_empty())
        .collect::<Vec<_>>()
        .join("\n\n");
    (!text.is_empty()).then_some(text)
}

fn message_text(message: &serde_json::Value) -> Option<String> {
    match message.get("content")? {
        serde_json::Value::String(s) => Some(s.clone()),
        serde_json::Value::Array(parts) => {
            let text = parts
                .iter()
                .filter_map(|part| part.get("text").and_then(|text| text.as_str()))
                .collect::<Vec<_>>()
                .join("\n");
            (!text.is_empty()).then_some(text)
        }
        _ => None,
    }
}

fn pending_plan_completion_nudge(
    step_ledger: Option<&dyn scheduled::StepLedger>,
    needs_plan_update: bool,
    workflow_hint: Option<&str>,
) -> Option<String> {
    let snapshot = step_ledger?.snapshot();
    let total = snapshot.steps.len();
    if total == 0 {
        return None;
    }
    let unfinished = snapshot
        .steps
        .iter()
        .filter(|s| s.status != StepStatus::Done)
        .count();
    if unfinished == 0 {
        return None;
    }
    let active = snapshot
        .steps
        .iter()
        .position(|s| s.status == StepStatus::Active)
        .or_else(|| {
            snapshot
                .steps
                .iter()
                .position(|s| s.status != StepStatus::Done)
        });
    let active_clause = active
        .map(|index| format!(" Active step {}.", index + 1))
        .unwrap_or_default();
    let step_word = if unfinished == 1 { "step" } else { "steps" };
    let workflow_clause = workflow_hint
        .map(str::trim)
        .filter(|hint| !hint.is_empty())
        .map(|hint| format!("\n\n{hint}"))
        .unwrap_or_default();
    if needs_plan_update {
        Some(workflow_guidance(format!(
            "You ended with a findings/next-steps summary while the agent-maintained, advisory plan still has \
             {unfinished}/{total} unfinished {step_word}.{active_clause} Your summary says \
             immediate prerequisite repair work now blocks the active step. Call update_plan now \
             with the full ordered plan: mark completed steps completed, make the immediate \
             blocker repair the active step, and keep later feature work pending. Then call the \
             next concrete tool for that active repair. Do not repeat the findings summary or \
             claim a tool-round limit while this nudge is giving you another round.{workflow_clause}"
        )))
    } else {
        Some(workflow_guidance(format!(
            "You ended the turn while the agent-maintained, advisory plan still has {unfinished}/{total} unfinished \
             {step_word}.{active_clause} Either call update_plan with completed steps marked \
             completed, call the next tool for the active step, or state the concrete blocker. \
             Do not hand off by only describing remaining work."
        )))
    }
}

fn read_only_action_nudge(
    read_only_rounds: usize,
    hard_rounds_remaining: Option<usize>,
    step_ledger: Option<&dyn scheduled::StepLedger>,
    delegate_hint: Option<&str>,
) -> String {
    let plan_clause = if step_ledger.and_then(plan_reseat_pointer).is_some() {
        " You have an active multi-step plan; continue the ACTIVE step when it still \
         matches the operator's request."
    } else {
        ""
    };
    let delegate_clause = delegate_hint
        .map(|hint| format!(" {hint}"))
        .unwrap_or_default();
    // A renewable allowance is not a final deadline. For a hard bound, name
    // only later rounds: this reminder precedes the current admitted round.
    let round_clause = hard_rounds_remaining
        .map(|remaining| {
            format!(
                " After this round, at most {remaining} further tool rounds remain under the configured hard limit."
            )
        })
        .unwrap_or_default();
    workflow_guidance(format!(
        "[{read_only_rounds} read-only rounds so far. Stop AIMLESS exploring and start \
         making the change. This is a nudge, not a limit — you may still read, but if \
         you have enough context, call edit_file or write_file now. {PERMISSION_RECOVERY_GUIDANCE} \
         If you truly cannot proceed yet, state the \
         exact blocker. Before edit_file, read the ONE file you are about to change so \
         old_string matches exact text; never guess old_string or repeat a failed edit.\
         {plan_clause}{delegate_clause}{round_clause}]"
    ))
}

/// Append the memory-nudge line to the current user message — the last
/// message in the list per the memory-manager contract. Defensive fallback:
/// if the last message somehow isn't a user turn, push a standalone user
/// message instead (mirrors the read-only-rounds nudge injection).
/// Make narration nudges EPHEMERAL (#1158): remove the previously-injected
/// nudge exchange — a trailing `[assistant: narration][user: LOOP_GUIDANCE …]`
/// pair — before the loop injects the next one. Without this, a narrate →
/// nudge → narrate → nudge sequence PILES its own dithering into the
/// transcript, and the accumulated "I said I'd act, I was told to act, I said
/// I'd act…" residue is exactly what drove the model (Opus 4.8, 2026-07-14)
/// to defend its idleness ("I'm genuinely finished") and then refuse fresh
/// prompts. Keeping only the CURRENT correction means the model sees the
/// steer once, not a wall of its own hesitation. The escalation counter still
/// climbs, so the escalated wording still fires — only the stale pairs are
/// dropped. A no-op unless the tail actually is a nudge exchange.
fn strip_trailing_nudge_exchange(messages: &mut Vec<serde_json::Value>) {
    let tail_is_nudge = messages.last().is_some_and(|m| {
        m["role"] == "user"
            && m["content"]
                .as_str()
                .is_some_and(|c| c.starts_with(compress::LOOP_GUIDANCE_PREFIX))
    });
    if tail_is_nudge {
        messages.pop(); // the LOOP_GUIDANCE nudge
        if messages.last().is_some_and(|m| m["role"] == "assistant") {
            messages.pop(); // the narration it corrected
        }
    }
}

fn append_nudge_line(messages: &mut Vec<serde_json::Value>, line: &str) {
    match messages.last_mut() {
        Some(last) if last["role"] == "user" => {
            let cur = last["content"].as_str().unwrap_or_default();
            last["content"] = serde_json::Value::String(format!("{cur}\n\n{line}"));
        }
        _ => messages.push(serde_json::json!({"role": "user", "content": line})),
    }
}

fn ollama_non_content_fields(json: &serde_json::Value) -> Vec<&'static str> {
    let message = &json["message"];
    ["reasoning", "reasoning_content", "thinking"]
        .into_iter()
        .filter(|field| {
            message[*field]
                .as_str()
                .map(|value| !value.trim().is_empty())
                .unwrap_or(false)
        })
        .collect()
}

fn ollama_response_shape(json: &serde_json::Value) -> String {
    let message = &json["message"];
    let message_keys = message
        .as_object()
        .map(|obj| obj.keys().cloned().collect::<Vec<_>>().join(","))
        .unwrap_or_else(|| "<missing>".to_string());
    let content_chars = message["content"]
        .as_str()
        .map(|content| content.chars().count())
        .unwrap_or(0);
    let tool_calls = message["tool_calls"]
        .as_array()
        .map(|calls| calls.len())
        .unwrap_or(0);
    let non_content = ollama_non_content_fields(json);
    let non_content = if non_content.is_empty() {
        "none".to_string()
    } else {
        non_content.join(",")
    };
    format!(
        "ollama response shape: message_keys=[{message_keys}] content_chars={content_chars} tool_calls={tool_calls} non_content_fields=[{non_content}] prompt_eval_count={} eval_count={}",
        json["prompt_eval_count"]
            .as_u64()
            .map_or("missing".to_string(), |n| n.to_string()),
        json["eval_count"]
            .as_u64()
            .map_or("missing".to_string(), |n| n.to_string())
    )
}

fn suspicious_empty_retry_nudge(retry_index: u32, json: &serde_json::Value) -> String {
    if retry_index == 0 {
        return "Your previous response produced generated tokens but no assistant-visible content \
                and no tool call. Reply with either a tool call or final assistant content."
            .to_string();
    }
    let fields = ollama_non_content_fields(json);
    let field_note = if fields.is_empty() {
        "hidden/non-content fields".to_string()
    } else {
        format!("hidden/non-content field(s): {}", fields.join(", "))
    };
    format!(
        "Your previous response again produced generated tokens only in {field_note}, \
         with no assistant-visible content and no tool call. Hidden thinking is not an \
         action. If you intend to act, emit the exact tool call now; otherwise reply \
         with final assistant-visible content. Do not continue with hidden-only reasoning."
    )
}

fn suspicious_empty_ollama_diagnostic(json: &serde_json::Value) -> String {
    let fields = ollama_non_content_fields(json);
    let field_note = if fields.is_empty() {
        "no known non-content fields were present".to_string()
    } else {
        format!("non-content field(s) present: {}", fields.join(", "))
    };
    format!(
        "(model generated output tokens but returned no assistant-visible content or tool calls; {field_note}; rerun with `newt --trace` to capture the response shape)"
    )
}

/// Build the nudge appended to the message list when the tool-round cap is hit.
/// `progress` (the `<plan>`/`<state>` working memory, Step 27.5) is folded in so
/// the model summarizes against what it actually accomplished; `observed`
/// (#867 Part A) is the verified-paths manifest collected across the rounds.
fn cap_exit_nudge(max_tool_rounds: usize, progress: Option<&str>, observed: &[String]) -> String {
    // #867: the message list was just trimmed (`trim_for_summary`), so most
    // of the evidence this summary should cite is GONE — the forensic session
    // showed a model reconstructing plausible-but-nonexistent file paths from
    // its priors at exactly this point. Constrain the summary to what is
    // still verbatim in context; absence must be stated, not papered over.
    let mut nudge = format!(
        "You have reached the tool-round limit ({max_tool_rounds} rounds). \
         Do NOT call any more tools. Give the operator a concise progress update \
         that separates completed and verified work, the current state or blocker, \
         and remaining work. The tool loop has stopped at the cap. Report whether \
         the operator's objective is complete or what remains; do not infer completion \
         merely because tools are disabled. Cite only file paths \
         that appear verbatim in the messages above — if the evidence you need \
         was in the omitted messages, say so plainly instead of reconstructing \
         file names or line numbers from memory. Do not narrate an intention to \
         keep working now (for example, \"let me read/edit/verify\"); list those \
         actions as remaining work and state that they have not run because the \
         round cap stopped further tool calls. Do not reproduce literal `<plan>` \
         or `<state>` tags from the working memory below. \
         Report an ACTION (an edit made, a test run or passing, a branch created, a \
         commit, a push, a PR opened) ONLY if a successful tool result above confirms \
         it — if you did not see the tool result, the action did not happen; list it \
         as remaining work instead. The workspace's real git state is checked against \
         this summary."
    );
    // #867 Part A: the ledger survived the trim — hand the model the REAL
    // manifest so grounded citation is possible, not just demanded.
    if !observed.is_empty() {
        nudge.push_str(
            "\n\nFile paths actually observed in tool results this run \
             (these exist — cite from this list):",
        );
        for p in observed {
            nudge.push_str("\n- ");
            nudge.push_str(p);
        }
    }
    if let Some(p) = progress {
        nudge.push_str(&format!("\n\nYour progress so far:\n{p}"));
    }
    nudge
}

/// Fallback message returned when even the final tools-disabled completion
/// fails. Includes accumulated token counts, salvages the `<plan>`/`<state>`
/// progress so partial work survives (Step 27.5), and gives HONEST advice: a run
/// dominated by failed tool calls is a tooling/permissions problem, not too few
/// rounds, so we don't blindly tell the user to raise the cap.
fn cap_exit_tokens_hint(max_tool_rounds: usize, accumulated: Option<crate::TokenUsage>) -> String {
    match accumulated {
        Some(u) => format!(
            " ({} in / {} out tokens consumed across {max_tool_rounds} rounds)",
            u.input_tokens, u.output_tokens,
        ),
        None => String::new(),
    }
}

fn cap_exit_advice(max_tool_rounds: usize, wasted_calls: usize) -> &'static str {
    // If at least one failed tool call per round, the cap was thrash, not a
    // genuine need for more rounds.
    if wasted_calls >= max_tool_rounds.max(1) {
        "most of those rounds were spent on tool calls that failed — the model \
         could not find a working edit/shell path, which is usually a tooling or \
         permissions issue rather than too few rounds; check `newt doctor`"
    } else {
        "increase the tool-round limit for the next attempt, or ask a more focused question"
    }
}

fn cap_exit_progress_block(label: &str, progress: Option<&str>) -> String {
    match progress {
        Some(p) => {
            // The ledger is one step per line, but a bare newline inside a
            // Markdown paragraph is a soft break that the styled surface folds
            // into a space (`markdown/emitter.rs`, `Event::SoftBreak`). Two
            // trailing spaces are a CommonMark hard break: one step per
            // rendered line, and invisible on the plain surface, which prints
            // the bytes verbatim (`display::print_newt`).
            let body = format!("{label}:\n{}", humanize_cap_exit_progress(p));
            format!("\n\n{}", body.replace('\n', "  \n"))
        }
        None => String::new(),
    }
}

/// The plan and scratchpad are deliberately represented with lightweight XML
/// inside model context. Those tags are protocol framing, not user-facing UI;
/// deterministic cap fallbacks render the same saved content as ordinary text.
fn humanize_cap_exit_progress(progress: &str) -> String {
    progress
        .replace("<plan>", "Plan:\n")
        .replace("</plan>", "")
        .replace("<state>", "Current state:\n")
        .replace("</state>", "")
        .trim()
        .to_string()
}

fn cap_exit_fallback(
    max_tool_rounds: usize,
    accumulated: Option<crate::TokenUsage>,
    wasted_calls: usize,
    progress: Option<&str>,
) -> FinalReply {
    let tokens_hint = cap_exit_tokens_hint(max_tool_rounds, accumulated);
    let advice = cap_exit_advice(max_tool_rounds, wasted_calls);
    let salvaged = cap_exit_progress_block("Progress captured before the summary failed", progress);
    FinalReply::harness(format!(
        "Paused at the tool-round limit ({max_tool_rounds} rounds){tokens_hint}. \
         The final summarization request also failed while preparing a progress \
         update; {advice}.{salvaged}"
    ))
}

/// Preserve the model-authored progress update while making the objective state
/// unambiguous. A pending-action classification is useful at a cap (it often
/// carries the best remaining-work handoff); the footer prevents those future
/// actions from being mistaken for completed work.
fn cap_exit_progress_handoff(
    max_tool_rounds: usize,
    accumulated: Option<crate::TokenUsage>,
    content: &str,
    has_pending_actions: bool,
    progress: Option<&str>,
) -> FinalReply {
    let tokens_hint = cap_exit_tokens_hint(max_tool_rounds, accumulated);
    let pending = if has_pending_actions {
        " The proposed next actions in this update have not run yet."
    } else {
        ""
    };
    let captured = cap_exit_progress_block("Captured working state", progress);
    FinalReply::from(content.to_owned()).with_notice(format!(
        "The tool loop reached the tool-round limit ({max_tool_rounds} rounds){tokens_hint}. \
         This progress handoff preserves the model's update.{pending}{captured}"
    ))
}

fn cap_exit_summary_is_action_handoff(content: &str) -> bool {
    crate::NudgeClassifier::load_default()
        .classify(content)
        .is_pending_action()
        || looks_like_unverified_stale_file_blocker(content)
}

/// Leave a clean, completed model summary untouched. Only add the deterministic
/// handoff wrapper when the model still proposes work or core has structured
/// plan/state to preserve. Interactive callers use `TurnEndReason::RoundCap` to
/// add their own resume affordance independently of this textual shape.
fn cap_exit_model_reply(
    max_tool_rounds: usize,
    accumulated: Option<crate::TokenUsage>,
    content: &str,
    progress: Option<&str>,
) -> FinalReply {
    let pending = cap_exit_summary_is_action_handoff(content);
    if pending || progress.is_some() {
        cap_exit_progress_handoff(max_tool_rounds, accumulated, content, pending, progress)
    } else {
        FinalReply::from(content.to_string())
    }
}

/// Apply the same evidence and disclosure gates to every provider's FINAL
/// answer for a turn — cap-exit handoff AND normal (no-tool) finish alike
/// (#1964: this used to run only on the cap-exit path, so a normal finish —
/// including a fabricated "verified working" report — returned unannotated).
/// The Responses wire used to bypass all three checks on cap-exit even
/// though the shared summary prompt promised the workspace would be
/// verified; the same promise holds for any final answer, not just one
/// forced out by the round cap.
fn finalize_final_text(
    text: impl Into<FinalReply>,
    workspace: &str,
    read_scope: &crate::Scope<String>,
    capability_evidence: &capability_check::Evidence,
    disclosure: Option<&crate::ocap::DisclosureFilter>,
    // #2683: HEAD captured before this turn's tool calls ran, so a
    // "committed" claim can be checked against whether HEAD actually moved.
    turn_claims: &claim_check::TurnClaims<'_>,
    verification: &self_verify::VerificationLedger,
) -> String {
    let mut reply = text.into();
    let source_draft = redact_model_facing(disclosure, reply.model.clone());
    reply.model = observed_report::assistant_prose(&source_draft);
    // Evaluate each gate against model prose only. Its appended diagnostics are
    // harness evidence, not words to attribute to the assistant.
    reply.annotation(capability_check::annotate_unobserved_probe(
        reply.model.clone(),
        capability_evidence,
    ));
    reply.annotation(turn_claims.annotate(
        reply.model.clone(),
        workspace,
        verification.claim_directories(),
        read_scope,
    ));
    reply.annotation(verification.annotate_cargo_claim(reply.model.clone()));
    reply.annotation(verification.annotate_pr_claim(reply.model.clone()));
    reply.annotation(verification.annotate_push_claim(reply.model.clone()));
    turn_claims.set_notices(workspace, read_scope, &reply.notices);
    redact_model_facing(
        disclosure,
        turn_claims.final_report(
            workspace,
            read_scope,
            &reply.model,
            &source_draft,
            disclosure,
        ),
    )
}

/// The cap-exit context threaded into a final tools-disabled summary (Step
/// 27.5): the round limit, accumulated usage, the count of failed tool calls
/// (drives honest advice), the salvaged `<plan>`/`<state>` progress, and the
/// #867 observed-paths manifest (verified paths from tool results, collected
/// before the trim could delete them).
struct CapExit {
    max_tool_rounds: usize,
    accumulated: Option<crate::TokenUsage>,
    wasted_calls: usize,
    progress: Option<String>,
    observed: Vec<String>,
    /// Complete-request ceiling for the final tools-disabled dispatch.
    request_budget: Option<usize>,
    calibration: f32,
    estimation: crate::tokens::TokenEstimation,
    /// Ollama's request `options` (see [`ollama_options`]), repeated on every
    /// request including the tools-disabled cap exit. Ignored by OpenAI chat.
    ollama_options: Option<serde_json::Value>,
    /// Learning evidence from fresh counts of this immutable summary request.
    /// Admission still probes anew on every attempt; this is never a count cache.
    prompt_measurement: std::sync::Mutex<Option<context_recovery::PromptMeasurement>>,
    /// Set when the harness wrote the cap-exit text itself (#2372).
    fell_back: std::sync::atomic::AtomicBool,
}

impl CapExit {
    fn push_nudge(&self, messages: &mut Vec<serde_json::Value>) {
        messages.push(serde_json::json!({
            "role": "user",
            "content": cap_exit_nudge(self.max_tool_rounds, self.progress.as_deref(), &self.observed),
        }));
    }

    fn fits(&self, messages: &[serde_json::Value], model: &str) -> bool {
        preflight_full_message_request(
            messages,
            None,
            self.request_budget,
            self.calibration,
            self.estimation,
            model,
        )
        .is_ok()
    }

    fn fallback(&self) -> (FinalReply, bool, Option<crate::TokenUsage>) {
        self.fell_back
            .store(true, std::sync::atomic::Ordering::Relaxed);
        (
            cap_exit_fallback(
                self.max_tool_rounds,
                self.accumulated,
                self.wasted_calls,
                self.progress.as_deref(),
            ),
            false,
            self.accumulated,
        )
    }

    fn record_measurement(
        &self,
        measurement: context_recovery::PromptMeasurement,
    ) -> anyhow::Result<()> {
        let mut observed = self
            .prompt_measurement
            .lock()
            .map_err(|_| anyhow::anyhow!("optional prompt measurement lock poisoned"))?;
        // The final request body is immutable across transport retries. Retain
        // its strongest count for learning, independent of each fresh admission.
        if observed
            .as_ref()
            .is_none_or(|previous| measurement.tokens > previous.tokens)
        {
            *observed = Some(measurement);
        }
        Ok(())
    }

    fn learn_measurement(&self, state: &mut CompressState) -> anyhow::Result<()> {
        if let Some(measurement) = *self
            .prompt_measurement
            .lock()
            .map_err(|_| anyhow::anyhow!("optional prompt measurement lock poisoned"))?
        {
            measurement.learn(state);
        }
        Ok(())
    }

    fn recover_rejection(
        &self,
        result: anyhow::Result<(FinalReply, bool, Option<crate::TokenUsage>)>,
        observations: &mut Option<&mut observability::SolveObservation>,
        state: &mut CompressState,
        round: usize,
        attempt: u32,
    ) -> anyhow::Result<(FinalReply, bool, Option<crate::TokenUsage>)> {
        self.learn_measurement(state)?;
        if let Err(error) = &result {
            if let Some(rejection) = error.downcast_ref::<context_recovery::OptionalRejection>() {
                context_recovery::terminal_optional(
                    observations,
                    state,
                    self.calibration,
                    round,
                    attempt,
                    rejection.estimated_tokens,
                )?;
                observability::observe_harness_reply(observations);
                return Ok(self.fallback());
            }
        }
        if self.fell_back.load(std::sync::atomic::Ordering::Relaxed) {
            observability::observe_harness_reply(observations);
        }
        result
    }

    async fn finish<Fut>(
        &self,
        endpoint: &str,
        attempts: Option<attempt_capture::AttemptScope<'_>>,
        request: impl Fn() -> Fut,
        http_error_prefix: &str,
        estimated_tokens: usize,
        extract: impl FnOnce(serde_json::Value) -> (String, Option<crate::TokenUsage>),
    ) -> anyhow::Result<(FinalReply, bool, Option<crate::TokenUsage>)>
    where
        Fut: std::future::Future<Output = anyhow::Result<reqwest::RequestBuilder>>,
    {
        self.finish_with_decoder(
            endpoint,
            attempts,
            request,
            http_error_prefix,
            estimated_tokens,
            |bytes| Ok(serde_json::from_slice(bytes)?),
            extract,
        )
        .await
    }

    #[allow(clippy::too_many_arguments)]
    async fn finish_with_decoder<Fut>(
        &self,
        endpoint: &str,
        attempts: Option<attempt_capture::AttemptScope<'_>>,
        request: impl Fn() -> Fut,
        http_error_prefix: &str,
        estimated_tokens: usize,
        decode: fn(&[u8]) -> anyhow::Result<serde_json::Value>,
        extract: impl FnOnce(serde_json::Value) -> (String, Option<crate::TokenUsage>),
    ) -> anyhow::Result<(FinalReply, bool, Option<crate::TokenUsage>)>
    where
        Fut: std::future::Future<Output = anyhow::Result<reqwest::RequestBuilder>>,
    {
        let retry = tui_retry_policy(endpoint);
        let result = dispatch_with_decoder(
            &retry,
            attempts,
            request,
            http_error_prefix,
            |_, _, _| {},
            None,
            decode,
        )
        .await;
        let result = match result {
            Err(error)
                if crate::retry::classify(&error)
                    == crate::retry::Retryability::ContextExceeded =>
            {
                return Err(error.context(context_recovery::OptionalRejection { estimated_tokens }));
            }
            other => other,
        };
        if let Err(error) = &result {
            if error.downcast_ref::<generation_bounds::Stopped>().is_some() {
                let (mut text, streamed, usage) = self.fallback();
                generation_bounds::append_notice(&mut text, error);
                return Ok((
                    text,
                    streamed,
                    merge_round_usage(usage, observability::reported_usage(error)),
                ));
            }
        }
        if let Ok((json, attempt)) = result {
            let limited = generation_bounds::output_limited(&json);
            let (content, usage) = extract(json);
            attempt_capture::complete(attempt.as_ref(), usage);
            let total = merge_round_usage(self.accumulated, usage);
            if limited {
                return Ok((
                    generation_bounds::output_limit_notice(content, usage),
                    false,
                    total,
                ));
            }
            if !content.is_empty() {
                return Ok((
                    cap_exit_model_reply(
                        self.max_tool_rounds,
                        self.accumulated,
                        &content,
                        self.progress.as_deref(),
                    ),
                    false,
                    total,
                ));
            }
        }
        // Failed or empty summaries retain only usage from preceding rounds.
        Ok(self.fallback())
    }
}

/// Final tools-disabled completion for the Ollama (`/api/chat`) path.
///
/// `messages` is the already-trimmed list (caller uses `trim_for_summary`).
/// `cap.accumulated` carries usage from the preceding tool-call rounds so it
/// survives even when this summary request fails.
/// Ollama's request `options` (#2312): the declared window as `num_ctx` and an
/// explicit output allowance as `num_predict`, its supported cap field. `None`
/// when neither applies, so such a body gains no `options` key at all.
fn ollama_options(num_ctx: Option<u32>, num_predict: Option<u32>) -> Option<serde_json::Value> {
    let mut options = serde_json::Map::new();
    if let Some(num_ctx) = num_ctx {
        options.insert("num_ctx".into(), num_ctx.into());
    }
    if let Some(num_predict) = num_predict {
        options.insert("num_predict".into(), num_predict.into());
    }
    (!options.is_empty()).then_some(serde_json::Value::Object(options))
}

async fn final_summary_ollama(
    client: &reqwest::Client,
    chat_url: &str,
    model: &str,
    mut messages: Vec<serde_json::Value>,
    cap: &CapExit,
    attempts: Option<attempt_capture::AttemptScope<'_>>,
) -> anyhow::Result<(FinalReply, bool, Option<crate::TokenUsage>)> {
    cap.push_nudge(&mut messages);
    if !cap.fits(&messages, model) {
        return Ok(cap.fallback());
    }
    // No `tools` key => the model cannot emit tool calls.
    let mut body = serde_json::json!({
        "model": model,
        "messages": &messages,
        "stream": false,
    });
    if let Some(options) = &cap.ollama_options {
        body["options"] = options.clone();
    }
    cap.finish(
        chat_url,
        attempts,
        || async { Ok(client.post(chat_url).json(&body)) },
        "Ollama",
        estimate_tokens(&messages, cap.estimation),
        |json| {
            // #385: strip inline reasoning; all-reasoning content takes the fallback.
            let (content, _reasoning) = crate::reasoning::split_reasoning(
                json["message"]["content"].as_str().unwrap_or(""),
            );
            (content, ollama_usage(&json))
        },
    )
    .await
}

/// Project the internal protected-head representation onto chat templates that
/// accept exactly one system message at index zero.
///
/// Prompt provenance deliberately keeps the base prompt and active-prompt card
/// as separate leading system messages internally. Coalesce only that leading
/// run for the OpenAI Chat Completions wire; a genuinely late system message is
/// malformed and must not be silently promoted across conversation history.
fn openai_chat_wire_messages(
    messages: &[serde_json::Value],
) -> anyhow::Result<Vec<serde_json::Value>> {
    agent_harness::render::openai_chat_wire_messages(messages).map_err(|error| match error {
        // Preserve the public wire diagnostic when adapting the shared renderer.
        agent_harness::Error::Proposal(message) => anyhow::anyhow!(message),
        error => error.into(),
    })
}

fn prepare_openai_assistant_replay(
    message: &serde_json::Value,
    clean_content: &str,
    replay_scope: crate::model_card::ReasoningReplayScope,
    current_user_turn: bool,
) -> serde_json::Value {
    let mut assistant = message.clone();
    if assistant["role"].as_str().is_none() {
        assistant["role"] = serde_json::Value::String("assistant".into());
    }

    let keep_reasoning = replay_scope == crate::model_card::ReasoningReplayScope::FullHistory
        || (replay_scope == crate::model_card::ReasoningReplayScope::CurrentUserTurn
            && current_user_turn);
    if !keep_reasoning {
        assistant["content"] = serde_json::Value::String(clean_content.to_string());
        if let Some(object) = assistant.as_object_mut() {
            object.remove("reasoning_content");
        }
    }
    sanitize_replayed_tool_call_arguments(&mut assistant);
    assistant
}

/// #2558/F39: every replayed assistant turn routes through
/// [`prepare_openai_assistant_replay`] before entering `messages` — the one
/// place to make an unparseable `arguments` string harmless everywhere
/// (chat and the token-count preflight, which resend `messages` verbatim). A call whose `arguments` string
/// fails to parse as JSON is replayed as `"{}"`: the model already sees a
/// rejection naming the parse error (`validate_tool_call_batch` /
/// `ContentInvalid`), and never sees this call dispatched, so a small valid
/// stand-in cannot be mistaken for real input reaching a tool.
fn sanitize_replayed_tool_call_arguments(assistant: &mut serde_json::Value) {
    let Some(calls) = assistant["tool_calls"].as_array_mut() else {
        return;
    };
    for call in calls {
        let Some(args) = call["function"]["arguments"].as_str() else {
            continue;
        };
        let trimmed = args.trim();
        if trimmed.is_empty() || serde_json::from_str::<serde_json::Value>(trimmed).is_ok() {
            continue;
        }
        call["function"]["arguments"] = serde_json::Value::String("{}".to_string());
    }
}

/// Count the assembled Chat Completions body only when admission has a bound.
/// Every caller invokes this anew immediately before its generation attempt.
async fn count_openai_request(
    client: &reqwest::Client,
    chat_url: &str,
    api_key: Option<&str>,
    body: &serde_json::Value,
    budget: Option<usize>,
) -> anyhow::Result<Option<crate::backend_probe::TokenCount>> {
    if budget.is_none() {
        return Ok(None);
    }
    let endpoint = chat_url
        .strip_suffix("/v1/chat/completions")
        .ok_or_else(|| anyhow::anyhow!("invalid Chat Completions endpoint for token admission"))?;
    let model = body["model"]
        .as_str()
        .ok_or_else(|| anyhow::anyhow!("token admission requires the assembled request model"))?;
    crate::backend_probe::count_chat_tokens(client, endpoint, model, api_key, body).await
}

fn enforce_counted_budget(
    count: Option<&crate::backend_probe::TokenCount>,
    budget: Option<usize>,
    estimated_tokens: usize,
) -> anyhow::Result<()> {
    if let (Some(count), Some(budget)) = (count, budget) {
        if count.tokens > budget {
            let error = observability::DispatchError::context_exceeded(format!(
                "pre-dispatch: Context size has been exceeded: measured {} input tokens \
                 exceed the {budget}-token input budget",
                count.tokens,
            ));
            return Err(
                anyhow::Error::new(error).context(context_recovery::PromptMeasurement {
                    tokens: count.tokens,
                    estimated_tokens,
                }),
            );
        }
    }
    Ok(())
}

/// Final tools-disabled completion for the OpenAI (`/v1/chat/completions`) path.
///
/// `messages` is the already-trimmed list (caller uses `trim_for_summary`).
/// `accumulated` carries usage from the preceding tool-call rounds.
#[allow(clippy::too_many_arguments)]
async fn final_summary_openai(
    clients: (&reqwest::Client, &reqwest::Client),
    chat_url: &str,
    model: &str,
    api_key: Option<&str>,
    mut messages: Vec<serde_json::Value>,
    generation_policy: generation_policy::GenerationPolicy,
    context_window: Option<u32>,
    cap: &CapExit,
    attempts: Option<attempt_capture::AttemptScope<'_>>,
) -> anyhow::Result<(FinalReply, bool, Option<crate::TokenUsage>)> {
    let (count_client, stream_client) = clients;
    cap.push_nudge(&mut messages);
    let messages = openai_chat_wire_messages(&messages)?;
    if !cap.fits(&messages, model) {
        return Ok(cap.fallback());
    }
    // Omit `tools` / `tool_choice` => the model cannot emit tool calls.
    let mut body = serde_json::json!({
        "model": model,
        "messages": &messages,
        "stream": true,
        "stream_options": {"include_usage": true},
    });
    generation_policy.apply_to_chat_completions_body(&mut body);
    generation_bounds::apply_chat(
        &mut body,
        chat_url,
        generation_policy.output_allowance,
        context_window,
        cap.request_budget.unwrap_or_else(|| {
            calibrate_up(estimate_tokens(&messages, cap.estimation), cap.calibration)
        }),
    )?;
    cap.finish_with_decoder(
        chat_url,
        attempts,
        || async {
            let count =
                count_openai_request(count_client, chat_url, api_key, &body, cap.request_budget)
                    .await?;
            let estimated_tokens = estimate_tokens(&messages, cap.estimation);
            if let Some(count) = &count {
                cap.record_measurement(context_recovery::PromptMeasurement {
                    tokens: count.tokens,
                    estimated_tokens,
                })?;
            }
            enforce_counted_budget(count.as_ref(), cap.request_budget, estimated_tokens)?;
            let mut req = stream_client.post(chat_url).json(&body);
            if let Some(key) = api_key {
                req = req.bearer_auth(key);
            }
            Ok(req)
        },
        "inference endpoint",
        estimate_tokens(&messages, cap.estimation),
        smart_harness::decode_openai_response,
        |json| {
            // #385: strip inline <think>…</think> reasoning from the content.
            let (content, _reasoning) = crate::reasoning::split_reasoning(
                json["choices"][0]["message"]["content"]
                    .as_str()
                    .unwrap_or(""),
            );
            (content, openai_usage(&json["usage"]))
        },
    )
    .await
}

/// OpenAI-compatible variant of [`chat_complete`]: the same agentic tool-call
/// loop, but over `POST {endpoint}/v1/chat/completions` with bearer auth and
/// the OpenAI `tool_calls` / `tool_call_id` / `usage` shapes.
///
/// Primary requests stream on the transport and are validated before tools
/// execute. An accepted final answer is returned as generated; the host
/// renders it (#2372).
pub async fn openai_chat_complete(
    ctx: ChatCtx<'_>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    openai_chat_complete_with_prompt(ctx, None, None, mcp).await
}

/// Provenance-aware OpenAI Chat Completions loop. See
/// [`chat_complete_with_prompt`] for the compatibility contract.
pub async fn openai_chat_complete_with_prompt(
    ctx: ChatCtx<'_>,
    turn_prompt_context: Option<&crate::TurnPromptContext>,
    prompt_source: Option<&dyn PromptSource>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    openai_chat_complete_with_prompt_and_artifacts(
        ctx,
        turn_prompt_context,
        prompt_source,
        None,
        None,
        mcp,
    )
    .await
}

async fn openai_chat_complete_with_prompt_and_artifacts(
    ctx: ChatCtx<'_>,
    turn_prompt_context: Option<&crate::TurnPromptContext>,
    prompt_source: Option<&dyn PromptSource>,
    artifact_source: Option<&dyn artifact_read::ArtifactSource>,
    artifact_sink: Option<&dyn artifact_read::PromptArtifactSink>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    let ChatCtx {
        shell_dialect,
        command_budget,
        verify_outcomes,
        smart_harness,
        url,
        model,
        kind: _,
        api_key,
        messages: mem_messages,
        task,
        workspace,
        default_command_cwd,
        worktree_session,
        color,
        // #2372: the host renders the accepted reply, markdown included.
        markdown: _,
        tool_offload,
        spill_store,
        disclosure,
        compaction_store,
        scratchpad,
        scratchpad_store,
        code_search,
        where_is,
        nav,
        exposure,
        experience_store,
        step_ledger,
        caveats,
        persona_tools,
        // Chat Completions does not use the Responses-only `reasoning_effort`
        // field. Explicit endpoint capability data may instead project cognition
        // into a local generation policy.
        cognition,
        output_allowance,
        overflow_retry: _,
        attempt_ledger,
        chat_completions_capability,
        responses_capability: _,
        openai_api: _,
        reasoning_replay_scope,
        max_tool_rounds,
        workflow_grace_rounds,
        narration_nudge_cap,
        action_nudges,
        prompt_disposition,
        prompt_intake,
        tool_output_lines,
        debug,
        trace,
        num_ctx,
        connect_timeout_secs,
        inference_timeout_secs,
        mid_loop_trim_threshold,
        compaction_trigger_policy,
        mid_loop_trim_tokens,
        max_ok_input,
        build_check_cmd,
        safe_context,
        recover_cw_400,
        mut note_sink,
        mut note_nudge,
        recall_source,
        memory_source,
        summarizer,
        compress_state,
        mut tool_events,
        mut phantom_reaches,
        mut end_reason,
        mut round_cap_hit,
        mut solve_obs,
        mut permission_gate,
        mut on_round_usage,
        estimate_ratio,
        estimation,
        summary_input_cap_floor_chars,
        rewrites_history,
        input_ceiling_pct,
        low_budget_pct,
        exec_floor,
        write_ledger,
        attribution,
        cancel,
        run_allowance,
        live_tool_output,
        git_tool,
        crew_runner,
        operating_mode_control,
        plan_mode_control,
        plan_draft_sink,
        steering,
        completed_spill_renderer,
        // #2372: the primary content is filtered with the stream filter's
        // policy — a lone `</think>` is answer text unless the backend
        // declares the #528 leading shape.
        emits_leading_reasoning,
    } = ctx;
    // Any completed viewport this turn paints must not outlive the turn's
    // bookkeeping: on EVERY exit (return, `?`, cancel, panic) the guard
    // discards it — without terminal writes — so a stale rewind can never
    // replay over a later turn's prompt.
    let _completed_spill_guard = CompletedSpillDismissGuard(&completed_spill_renderer);
    // See the Ollama path: a non-Act turn is allowed bounded reads but never
    // execution-pressure nudges.
    let action_nudges = action_nudges && prompt_disposition == PromptDisposition::Act;
    if let Some(harness) = smart_harness {
        harness.start_turn()?;
    }
    // Smart mode retains full tool output before the existing shell cap runs.
    let spill_store = smart_harness.map(|h| h.spill_store()).or(spill_store);
    let tool_offload = tool_offload || smart_harness.is_some();
    let smart_verify = action_nudges && prompt_disposition == PromptDisposition::Act;
    let action_nudges = action_nudges && smart_harness.is_none();
    let max_tool_rounds = prompt_disposition.tool_round_limit(max_tool_rounds);
    let mut generation_window = num_ctx;
    let generation_policy = generation_policy::GenerationPolicy::resolve(
        cognition,
        output_allowance,
        chat_completions_capability,
        reasoning_replay_scope,
    );
    // Initial policy observation; each assembled request below records the
    // independent generation guard's actual server-enforced cap.
    observability::observe_output_allowance(
        &mut solve_obs,
        generation_policy.output_allowance,
        generation_policy.max_output_tokens.is_some(),
    );
    let reasoning_replay_scope = generation_policy.reasoning_replay_scope;
    // Headless callers may pass no session state (mirrors the Ollama path).
    let mut local_compress_state = CompressState::new();
    let compress_state = match compress_state {
        Some(s) => s,
        None => &mut local_compress_state,
    };
    let client = reqwest::Client::builder()
        .connect_timeout(std::time::Duration::from_secs(connect_timeout_secs))
        .timeout(std::time::Duration::from_secs(inference_timeout_secs))
        .build()?;
    // #643: streamed generations get their OWN client, because a
    // whole-request `.timeout()` bounds connect + headers + the ENTIRE body —
    // it aborts a slow-but-progressing token stream the instant total time
    // crosses the deadline (the DGX retry-storm wedge the Ollama path already
    // learned). An IDLE `read_timeout` caps the gap BETWEEN chunks and resets
    // on every token, so a stream runs as long as it keeps producing while a
    // genuinely stalled connection still bails. Counting probes keep `client`;
    // every streamed generation uses `stream_client`.
    let stream_client = reqwest::Client::builder()
        .connect_timeout(std::time::Duration::from_secs(connect_timeout_secs))
        .read_timeout(std::time::Duration::from_secs(inference_timeout_secs))
        .build()?;
    let chat_url = format!("{}/v1/chat/completions", url.trim_end_matches('/'));
    let retry = tui_retry_policy(url);
    // The save_note tool is advertised only when a sink exists (Step 19.3);
    // recall only when a source exists (Step 17.5); memory_fetch only when a
    // memory source exists (#319) — mirrors the Ollama path.
    let advertise_save_note = note_sink.is_some();
    let advertise_recall = recall_source.is_some();
    let advertise_memory_fetch = memory_source.is_some();
    // Step 26.4 (#583): state tools only when the feature is on AND a store exists.
    let advertise_scratchpad = scratchpad_store.is_some() && scratchpad;
    // Step 26.5.5 (#582): the code_search tool when a searcher is present.
    let advertise_code_search = code_search.is_some();
    // Step 26.6a (#585): the experiential tools when a store is present.
    let advertise_experiential = experience_store.is_some();
    // Step 26.6b (#586): the scheduled plan tools when a ledger is present.
    let advertise_scheduled = step_ledger.is_some();
    // Native Git is the default interface; the injected adapter remains internal.
    let advertise_git = false;
    let advertise_team = crew_runner.is_some();
    let advertise_operating_mode = operating_mode_control.is_some();
    let advertise_plan_mode = plan_mode_control.is_some();
    let advertise_plan_mode_active =
        plan_mode_control.is_some_and(|control| control.is_plan_mode());

    let mem_messages = observed_report::replay_messages(mem_messages);
    let mut messages: Vec<serde_json::Value> = mem_messages
        .iter()
        .map(|m| {
            let content = if m.role == crate::Role::Assistant
                && reasoning_replay_scope != crate::model_card::ReasoningReplayScope::FullHistory
            {
                crate::reasoning::split_reasoning(&m.content).0
            } else {
                m.content.clone()
            };
            serde_json::json!({"role": m.role.as_str(), "content": content})
        })
        .collect();
    if let Some(harness) = smart_harness {
        messages = harness.initial_messages(messages)?;
    }
    if let (Some(session), Some(context)) = (worktree_session, turn_prompt_context) {
        session
            .report
            .lock()
            .expect("report state")
            .begin(context.active().root_prompt_id());
    }
    let ephemeral_prompt = prompt_read::headless_prompt_fallback(turn_prompt_context, task);
    let turn_prompt_context = turn_prompt_context.or(ephemeral_prompt.as_ref());
    let prompt_context =
        prompt_read::PromptReadContext::new(turn_prompt_context, task, prompt_source);
    let artifact_context = turn_prompt_context
        .map(|turn| artifact_read::ArtifactReadContext::from_turn(turn, artifact_source));
    let active_task = prompt_context.active_text();
    prompt_read::ensure_active_prompt_card(&mut messages, prompt_context, prompt_intake);
    // #2313: one ledger attempt per primary request, keyed at the send.
    let attempt_turn = turn_prompt_context
        .map(|turn| turn.active_operator_prompt().id().to_string())
        .unwrap_or_default();
    // An explicit inference budget applies even without an audit sink.
    let fallback_ledger = std::sync::Mutex::new(crate::attempts::AttemptLedger::default());
    let attempt_ledger = attempt_ledger.or_else(|| run_allowance.map(|_| &fallback_ledger));
    let attempts = attempt_ledger.map(|ledger| attempt_capture::AttemptScope {
        ledger,
        turn: &attempt_turn,
        model,
        backend: url,
        cancel,
        run_allowance,
    });

    // In-band memory nudge (Step 19.3) — mirrors the Ollama path.
    if note_sink.is_some() {
        if let Some(line) = note_nudge.as_deref_mut().and_then(NoteNudge::begin_turn) {
            if let Some(harness) = smart_harness {
                harness.host_message(&line)?;
                messages.push(serde_json::json!({"role":"user", "content":line}));
            } else {
                append_nudge_line(&mut messages, &line);
            }
        }
    }

    let mut accumulated_usage: Option<crate::TokenUsage> = None;
    let mut hallucination_count: u32 = 0;
    // Step 27.3/#771: guard against exact-repeat tool loops this run.
    // #2315: result-aware verification for this turn, decided once.
    let result_aware = self_verify::enabled() && verify_outcomes;
    let mut repeat_calls = RepeatCallGuard::default();
    // Plan-before-act: the ledger as this turn began (see `PlanRoundFacts`).
    let plan_at_turn_start = step_ledger
        .map(|ledger| ledger.snapshot())
        .unwrap_or_default();
    let mut read_history = tools::ReadHistory::default();
    // #2315: what each check actually did, fed at the per-tool-result funnel.
    let mut verification = self_verify::VerificationLedger::for_turn(task, result_aware);
    // #2683: HEAD before this turn's own tool calls run, so a "committed"
    // claim in the final report can be checked against whether HEAD actually
    // moved. `None` (off-repo, or the read scope refuses the probe) must
    // never manufacture a false refutation — see `claim_check::TurnGitEvidence`.
    let turn_claims =
        claim_check::TurnClaims::capture(workspace, &caveats.fs_read, worktree_session)
            .with_evidence(observed_report::review::Evidence {
                sink: artifact_sink,
                context: artifact_context,
                spill: spill_store,
            });
    // #1948: DETECTION beside the guard — it notices a clean-then-build
    // loop and says so once; it never blocks or rewrites the call.
    let mut clean_build = crate::loop_watch::CleanBuildWatch::default();
    // Consecutive context-window recoveries (parse limit → trim → retry).
    let mut cw_retries: u32 = 0;
    let mut output_recovery = output_limit_recovery::Recovery::default();
    // No-tools recovery (mirrors the Ollama path): a model that rejects the
    // `tools` field 400s even on "hello"; drop tools and retry, notice once.
    let mut tools_supported = true;
    let mut tools_unsupported_notified = false;
    // Pre-send token budget gate; tightened mid-turn by a recovered 400
    // (#223). `num_ctx` is not sent on this wire, but an operator-declared
    // local endpoint window still provides an authoritative input ceiling.
    // Cloud endpoints leave it unset and continue to fail open on proven-good
    // evidence alone.
    let mut effective_input_ceiling = num_ctx_input_ceiling(
        num_ctx,
        input_ceiling_pct,
        generation_policy.output_allowance,
    );
    let mut send_budget: Option<usize> =
        initial_send_budget(max_ok_input, safe_context, effective_input_ceiling);
    let mut send_budget_authoritative = safe_context.is_some() || effective_input_ceiling.is_some();
    // Tool schemas ride along in every request body; count them once (18.1).
    let tools = merged_tool_definitions(
        mcp,
        advertise_save_note,
        advertise_recall,
        advertise_memory_fetch,
        advertise_git.then_some(&caveats.fs_read),
        advertise_team,
        advertise_scratchpad,
        advertise_code_search,
        advertise_experiential,
        advertise_scheduled,
        advertise_operating_mode,
        advertise_plan_mode,
        advertise_plan_mode_active,
        command_budget,
        shell_dialect,
    );
    // Put the persona's preferred tools first without removing other tools.
    // Dispatch separately checks explicit permissions and delegation authority.
    let tools = filter_advertised_tools(tools, persona_tools);
    let tools = filter_tools_for_disposition(
        smart_harness::advertise(tools, smart_harness),
        prompt_disposition,
    );
    // #TEC Pass 1: exposure stage — clip the authorized catalog to the live
    // usable budget (identity under `ExposureProfile::Full`). See the Ollama
    // path for the full rationale.
    let (tools, hidden_tools) = crate::agentic::tools::select_exposed(
        tools,
        &exposure,
        exposure_budget_tokens(send_budget, safe_context),
        &std::collections::BTreeSet::new(),
        estimation,
    );
    // The endpoint speaks the OpenAI function-tool wire even when the serving
    // model is hosted behind vLLM/LiteLLM/NIM. Enforce that wire's 128-function
    // envelope after authorization + exposure, keeping Kernel tools ahead of
    // optional MCP schemas. Retain omitted schemas in the same controller for
    // exact-name activation without changing dispatch authority.
    let mut tools = crate::agentic::tools::select_openai_compatible_tools(tools, &hidden_tools);
    let mut tool_tokens = estimate_value_tokens(&tools, estimation);
    // Phase 20 §2.3: per-turn calibration ratio + real-token schema overhead
    // (mirrors the Ollama path).
    let mut cal = compress_state.calibration.ratio(estimate_ratio);
    let mut tool_tokens_real = calibrate_up(tool_tokens, cal);
    preflight_irreducible_request(
        &messages,
        Some(&tools),
        authoritative_request_budget(send_budget, send_budget_authoritative, mid_loop_trim_tokens),
        cal,
        estimation,
        model,
    )?;
    // Truthful context-size tracker (prompt-tokens-preferred, Step 18.1).
    let mut prompt_tracker = PromptTracker::new();
    let today = chrono::Local::now().format("%Y-%m-%d").to_string();

    // #867 Part A: observed-paths ledger (matches the Ollama path).
    let mut observed_paths = claim_check::ObservedPaths::default();
    let mut observed_resolver = claim_check::workspace_resolver(workspace);

    // Narrate-then-stop rescue counter (mirror of the Ollama path).
    let mut narration_nudges: usize = 0;
    let mut readonly_completion_retried = false;
    // Self-verify gate (#23): times we've handed the model a round to run the
    // verification the workspace ships before letting it conclude. Capped so a
    // model that refuses to verify still ends the turn.
    let mut self_verify_nudges: usize = 0;
    let mut verification_nudges: usize = 0;
    const SELF_VERIFY_CAP: usize = 2;
    // Pending-plan final-answer gate counter (mirror of the Ollama path).
    let mut pending_plan_nudges: usize = 0;
    // Unverified stale-file blocker rescue counter (mirror of the Ollama path).
    let mut stale_file_nudges: usize = 0;
    let mut unverified_exec_blocker_nudges: usize = 0;
    let mut run_command_denial_observed = false;
    // #2628: see the primary loop declaration above for the invariant.
    let mut pending_rerun: Option<tools::PendingRerun> = None;
    let mut capability_evidence = capability_check::Evidence::default();
    let mut probe_correction_used = false;
    let nudge_classifier = crate::NudgeClassifier::load_default();
    // #1152/#1162: same intent gate as the primary loop — see the comment there.
    let action_turn = action_nudges && crate::classifiers::user_turn_invites_action(active_task);
    let exec_grounding_turn = action_nudges && prompt_disposition == PromptDisposition::Act;
    let workflow_steerer = crate::WorkflowSteerer::load_default();
    let mut workflow_runtime = WorkflowRuntimeState {
        initiative: crate::initiative::effective_initiative(),
        no_progress: crate::initiative::installed_no_progress(),
        ..Default::default()
    };
    // See the Ollama path: a matching workflow's grace-horizon override.
    workflow_runtime.set_progress_horizon(
        workflow_steerer.progress_horizon(&workflow_classifier_text(&messages, "")),
    );

    // Same progress-backed renewable allowance as the other providers.
    let mut current_tool_round_limit = max_tool_rounds;
    // #1965: the turn's only whole-turn wall-clock signal. The evidenced
    // 32-minute turn emitted none — this file has per-tool `Instant` timers
    // and nothing watching the turn as a whole.
    let turn_started = std::time::Instant::now();
    let mut turn_heartbeat = TurnHeartbeat::default();
    let mut uncorrelatable_batches: u32 = 0;
    let mut selected_source = selected_target::Projection::default();
    let mut observed_facts = semantic_pins::Projection::default();
    'round_loop: for round in 0..usize::MAX {
        let round = round.saturating_sub(output_recovery.skipped_rounds);
        selected_source.refresh(
            &mut messages,
            step_ledger,
            workspace,
            &caveats.fs_read,
            worktree_session,
            false,
        );
        observed_facts.planning = output_budget::guidance(
            Some(generation_bounds::output_cap(
                generation_policy.output_allowance,
                None,
                0,
            )?),
            step_ledger,
            &selected_target::root(workspace, worktree_session),
            &caveats.fs_read,
            estimation,
        );
        semantic_pins::refresh(
            &mut observed_facts,
            smart_harness,
            &mut messages,
            prompt_context,
            selected_source.current(),
            &turn_claims,
            workspace,
            &caveats.fs_read,
        )?;
        let round_policy = generation_policy;
        // #2331: a call to an authorized tool whose schema was off the wire
        // promoted it; its schema rides every request from here on.
        if hidden_tools.append_promoted(&mut tools) {
            tool_tokens = estimate_value_tokens(&tools, estimation);
            tool_tokens_real = calibrate_up(tool_tokens, cal);
        }
        // Bounded to ONE line per interval, and the policy is pure over the
        // elapsed it is handed — this reads the clock, `due` does not.
        let turn_elapsed = turn_started.elapsed();
        if let Some(line) = turn_heartbeat.notice(turn_elapsed, round, current_tool_round_limit) {
            print_newt(&line, color, false);
        }
        // FIRST statement of every round: the previous round's completed
        // viewport must come down before ANY canonical line this round can
        // print — the grace-window debug note, the round separator, the
        // compression notices, the cancel checkpoint's return to a caller
        // that prints. Erasing here is safe precisely because nothing has
        // written since the frame was painted.
        dismiss_completed_spill(&completed_spill_renderer);
        if !workflow_runtime.admit_round(
            round,
            &mut current_tool_round_limit,
            workflow_grace_rounds,
        ) {
            break;
        }
        // Interrupt checkpoint (Esc / Ctrl-C), same contract as the Ollama path:
        // bail at the round boundary with an empty reply; tool dispatches below
        // are also raced so an interrupt can stop a hung command mid-round.
        if is_cancelled(cancel) {
            return Ok((
                smart_harness::cancelled(smart_harness, &mut end_reason)?,
                false,
                accumulated_usage,
                hallucination_count,
            ));
        }
        // #952/#1669: operator steering, delivered BEFORE this round's model
        // call and AFTER any tool that was already running finished above.
        // Steering changes what the agent does NEXT; it never abandons the
        // turn (that is `cancel`, checked immediately above).
        if drain_steering_into(steering, &mut messages, color) > 0 {
            workflow_runtime.note_operator_steering();
        }
        if round > 0 && color {
            execute!(
                io::stdout(),
                SetForegroundColor(CtColor::DarkGrey),
                Print("…\n"),
                ResetColor
            )
            .ok();
        }

        // Conditional plan re-seat (#630 b) — mirror of the Ollama path: re-show
        // the active step each round so a multi-step plan doesn't go stale.
        // U4b: the brake's gate runs EVERY round, outside the nudge gate: nudges may
        // be off, a bound may not (only the steer honours `action_nudges`).
        if round > 0 {
            no_progress_gate!(
                workflow_runtime,
                action_nudges,
                messages,
                end_reason,
                solve_obs,
                accumulated_usage,
                hallucination_count,
                smart_harness,
                (
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification
                ),
                |harness| harness.record_messages(&messages)?
            );
        }
        if round > 0 && action_nudges {
            if let Some(ptr) = step_ledger.and_then(plan_reseat_pointer) {
                messages.push(serde_json::json!({ "role": "user", "content": ptr }));
            }
            // Initiative action-forcing: the OpenAI-chat loop had no read-only
            // action nudge (only the Ollama loop did), so a model driven here
            // could read/plan its whole budget without ever editing. Fire the
            // nudge once the initiative level's read-only budget is spent.
            let remaining = (workflow_grace_rounds == 0)
                .then_some(current_tool_round_limit.saturating_sub(round + 1));
            if let Some(nudge) = workflow_runtime.action_forcing_nudge(remaining, step_ledger, None)
            {
                if debug {
                    print_debug(
                        &format!(
                            "initiative[{}]: forcing action, read-only budget spent (round {round})",
                            workflow_runtime.initiative
                        ),
                        color,
                    );
                }
                messages.push(serde_json::json!({ "role": "user", "content": nudge }));
            }
        }

        // Context compression (Step 18.4, #247 — mirrors the Ollama path):
        // the shared prune → boundary → redacted summary → marker pipeline
        // serves the mid-loop trigger and the pre-send budget guard.
        {
            // Phase 20 §2.3: calibrated `current` (real-token space) —
            // mirrors the Ollama path.
            let advertised_tools = tools_supported.then_some(&tools);
            if let Some(harness) = smart_harness {
                harness.record_messages(&messages)?;
            }
            let wire_messages = openai_chat_wire_messages(&messages)?;
            let current = full_message_request_pressure_tokens(
                prompt_tracker.current(&messages, advertised_tools, cal, estimation),
                &wire_messages,
                advertised_tools,
                cal,
                estimation,
            );
            // Count-only budget priced in message-token space (F1) — mirrors
            // the Ollama path.
            let message_tokens = estimate_tokens(&messages, estimation);
            let has_authoritative_headroom = count_guard_has_headroom(
                current,
                authoritative_request_budget(
                    send_budget,
                    send_budget_authoritative,
                    mid_loop_trim_tokens,
                ),
                max_ok_input,
            );
            let reasoning_tail_len =
                compress::protected_reasoning_tail_len(&messages, reasoning_replay_scope);
            if let Some(trigger) = compression_trigger(
                compress::compression_message_count(&messages, reasoning_tail_len),
                current,
                message_tokens,
                CompressionTriggerLimits {
                    count_threshold: mid_loop_trim_threshold,
                    token_threshold: mid_loop_trim_tokens,
                    send_budget,
                    tool_tokens: tool_tokens_real,
                    policy: compaction_trigger_policy,
                    has_authoritative_headroom,
                },
            ) {
                // Hard budgets are real-token currency → pipeline chars/4
                // (Phase 20 §2.3); count-only budgets pass through (F1).
                let pipeline_budget = if trigger.hard_budget {
                    calibrate_down(trigger.budget, cal)
                } else {
                    trigger.budget
                };
                // Step 20.3: authoritative iff a token threshold fired or the
                // send budget rests on a believed ceiling (mirrors the Ollama
                // loop). A lone-HWM guard is non-authoritative → fails open.
                let token_fired = mid_loop_trim_tokens.is_some_and(|t| t > 0 && current > t);
                let compression = smart_harness::compress(
                    CompressRequest {
                        messages: &messages,
                        budget: pipeline_budget,
                        // A current-turn reasoning transcript is one atomic
                        // logical item for count pressure. Token pressure still
                        // applies to its real size, but a physical count cap
                        // must not split away the plan the endpoint requires.
                        max_messages: if reasoning_tail_len > 0 {
                            None
                        } else {
                            trigger.max_messages
                        },
                        replay_protected_tail_len: reasoning_tail_len,
                        task: active_task,
                        hard_budget: trigger.hard_budget,
                        authoritative: token_fired || send_budget_authoritative,
                        focus: None,
                        est: estimation,
                        summary_input_cap_floor_chars,
                        rewrites_history,
                        compaction_store,
                        compaction_stage: None,
                    },
                    summarizer,
                    compress_state,
                    smart_harness,
                );
                let Some(outcome) = cancellable(cancel, compression).await else {
                    return Ok((
                        smart_harness::cancelled(smart_harness, &mut end_reason)?,
                        false,
                        accumulated_usage,
                        hallucination_count,
                    ));
                };
                let outcome = outcome?;
                if let Some(notice) = outcome.notice {
                    print_harness_notice(&notice, color);
                }
                if outcome.action == CompressAction::Refused {
                    anyhow::bail!("{}", refusal_bail_message(outcome.refusal, current, model));
                }
                if outcome.fired {
                    // N2 (mirrors the Ollama path): flag a still-over-budget
                    // assembly before the full-request preflight refuses its
                    // dispatch — compared in the pipeline's own chars/4
                    // currency (Phase 20 §2.3).
                    let suffix = if trigger.hard_budget && outcome.tokens_after > pipeline_budget {
                        ", still over budget"
                    } else {
                        ""
                    };
                    emit_compression_notice(
                        color,
                        outcome.tokens_before,
                        outcome.tokens_after,
                        outcome.action,
                        suffix,
                    );
                    if debug {
                        print_debug(
                            &format!(
                                "compression: {} → {} messages (budget ~{} tokens, \
                                 +~{tool_tokens} tool-schema tokens ride along)",
                                messages.len(),
                                outcome.messages.len(),
                                pipeline_budget,
                            ),
                            color,
                        );
                    }
                    messages = outcome.messages;
                    prompt_tracker.invalidate();
                    apply_post_compaction_continuation(
                        worktree_session,
                        &mut messages,
                        &mut narration_nudges,
                        outcome.action,
                        step_ledger,
                        prompt_context,
                        round > 0 && action_nudges,
                        |candidate| {
                            openai_chat_wire_messages(candidate).is_ok_and(|wire| {
                                preflight_full_message_request(
                                    &wire,
                                    tools_supported.then_some(&tools),
                                    authoritative_request_budget(
                                        send_budget,
                                        send_budget_authoritative,
                                        mid_loop_trim_tokens,
                                    ),
                                    cal,
                                    estimation,
                                    model,
                                )
                                .is_ok()
                            })
                        },
                    );
                    record_compaction_artifact(
                        &mut repeat_calls,
                        artifact_sink,
                        artifact_context,
                        outcome.action,
                        outcome.tokens_before,
                        outcome.tokens_after,
                        pipeline_budget,
                        round,
                        trigger.primary_cause.artifact_reason(),
                        Some(&trigger),
                        send_budget_authoritative,
                        compress_state.floor_trend(),
                        color,
                    );
                }
            }
        }

        // #1528: inner recovery loop — a cw-400 (or a tools-unsupported error)
        // retries THIS logical round IN PLACE. Only a COMPLETED dispatch `break`s
        // out and lets `round` advance, so recovery never consumes a tool-capable
        // round (critical at current_tool_round_limit == 1 or near the cap): the recovered
        // request is re-sent WITH tools, never demoted to the tools-disabled summary.
        // How long the model actually took, read off the spinner the operator
        // was watching rather than a second clock started beside it. Assigned
        // inside the retry loop below, where the spinner is still alive.
        let mut thought_for;
        let (json, round_est_raw): (serde_json::Value, usize) = loop {
            if let Some(harness) = smart_harness {
                harness.record_messages(&messages)?;
            }
            let wire_messages = openai_chat_wire_messages(&messages)?;

            // Mirror the Ollama full-request gate. A known authoritative ceiling
            // means the harness must not dispatch an impossible request,
            // especially after a giant exact prompt_read result.
            preflight_full_message_request(
                &wire_messages,
                tools_supported.then_some(&tools),
                authoritative_request_budget(
                    send_budget,
                    send_budget_authoritative,
                    mid_loop_trim_tokens,
                ),
                cal,
                estimation,
                model,
            )?;

            // Phase 20 §2.2: chars/4 estimate of exactly the request about to be
            // dispatched — mirrors the Ollama path.
            let round_est_raw = estimate_request_tokens(
                &wire_messages,
                tools_supported.then_some(&tools),
                estimation,
            );

            // OpenAI-compatible endpoints don't use Ollama's `options.num_ctx` —
            // context limits are configured server-side (vLLM --max-model-len).
            let mut body = serde_json::json!({
                "model": model,
                "messages": wire_messages,
                "tools": tools.clone(),
                "tool_choice": "auto",
                "stream": true,
                "stream_options": {"include_usage": true},
            });
            round_policy.apply_to_chat_completions_body(&mut body);
            // Drop tools (and the now-meaningless tool_choice) for a model that
            // rejected them on a prior "does not support tools" 400.
            if !tools_supported {
                if let Some(o) = body.as_object_mut() {
                    o.remove("tools");
                    o.remove("tool_choice");
                }
            }
            // OpenAI-compatible endpoints do not accept a `num_ctx` request field,
            // but the operator-declared local window still bounds Newt's pre-send
            // budget. These endpoints reject oversize requests rather than silently
            // truncating them, so no wire field is needed to enforce the local cap.
            let request_budget = authoritative_request_budget(
                send_budget,
                send_budget_authoritative,
                mid_loop_trim_tokens,
            );
            let output_cap = generation_bounds::apply_chat(
                &mut body,
                &chat_url,
                round_policy.output_allowance,
                generation_window,
                request_budget.unwrap_or_else(|| calibrate_up(round_est_raw, cal)),
            )?;
            observability::observe_output_allowance(&mut solve_obs, Some(output_cap), true);
            let measured_prompt_tokens = std::sync::atomic::AtomicUsize::new(0);
            let admission_commit_failure = std::sync::OnceLock::new();
            let max_attempts = retry.max_retries.saturating_add(1);
            let attempts_started = std::cell::Cell::new(0u32);
            let spinner_label =
                inference_progress_label(model, 1, max_attempts, inference_timeout_secs);
            let spinner = if thinking_stream_enabled() {
                crate::tty::Spinner::start(&spinner_label, crate::tty::Sink::Stdout, color)
            } else {
                None
            };
            let dispatch = with_backoff_notify_error(
                &retry,
                || {
                    let attempt = attempts_started.get().saturating_add(1);
                    attempts_started.set(attempt);
                    if let Some(spinner) = spinner.as_ref() {
                        spinner.set_label(&inference_progress_label(
                            model,
                            attempt,
                            max_attempts,
                            inference_timeout_secs,
                        ));
                    }
                    async {
                        let mut req = smart_harness::request_with_messages(
                            stream_client.post(&chat_url),
                            &body,
                            smart_harness,
                            "openai",
                            &messages,
                        )?;
                        if let Some(key) = api_key {
                            req = req.bearer_auth(key);
                        }
                        let counted = count_openai_request(
                            &client,
                            &chat_url,
                            api_key,
                            &body,
                            request_budget,
                        )
                        .await;
                        if let (Some(harness), Some(budget)) = (smart_harness, request_budget) {
                            let committed = match counted.as_ref() {
                                Ok(Some(count)) => harness.record_token_count(Ok(count), budget),
                                Err(error) => harness.record_token_count(Err(error), budget),
                                Ok(None) => Ok(()),
                            };
                            if let Err(error) = committed {
                                admission_commit_failure.get_or_init(|| error);
                                // The preserved diagnostic may itself contain a transient
                                // or context error. Storage failure must bypass both retries.
                                anyhow::bail!("token-count evidence could not be committed");
                            }
                        }
                        let counted = counted?;
                        if let Some(count) = &counted {
                            measured_prompt_tokens
                                .fetch_max(count.tokens, std::sync::atomic::Ordering::Relaxed);
                        }
                        enforce_counted_budget(counted.as_ref(), request_budget, round_est_raw)?;
                        // W0 (#1511): classify while the error is TYPED — the
                        // DispatchError keeps the historical message text and carries
                        // the structural class to the driver boundary.
                        let (resp, attempt) =
                            attempt_capture::send(attempts, "primary", req, "request failed")
                                .await?;
                        let json = smart_harness::response_with_decoder(
                            resp,
                            smart_harness,
                            "inference endpoint",
                            smart_harness::decode_openai_response,
                        )
                        .await
                        .inspect_err(|error| {
                            attempt_capture::failed(attempt.as_ref(), error);
                        })?;
                        attempt_capture::complete(attempt.as_ref(), openai_usage(&json["usage"]));
                        Ok(json)
                    }
                },
                |attempt, delay, error| {
                    if let Some(spinner) = spinner.as_ref() {
                        spinner.set_label(&format!(
                            "retry {attempt}/{} in {:.1}s…",
                            retry.max_retries,
                            delay.as_secs_f32(),
                        ));
                    }
                    print_retry_indicator(attempt, retry.max_retries, delay, error, color);
                },
            );
            let dispatch = cancellable(cancel, dispatch).await;
            thought_for = spinner
                .as_ref()
                .map_or(std::time::Duration::ZERO, crate::tty::Spinner::elapsed);
            drop(spinner);
            if let Some(error) = admission_commit_failure.into_inner() {
                return Err(error);
            }
            let measured = measured_prompt_tokens.load(std::sync::atomic::Ordering::Relaxed);
            if measured > 0 {
                compress_state
                    .calibration
                    .observe_count(measured, round_est_raw);
                cal = compress_state.calibration.ratio(estimate_ratio);
                tool_tokens_real = calibrate_up(tool_tokens, cal);
            }
            let Some(dispatch) = dispatch else {
                return Ok((
                    smart_harness::cancelled(smart_harness, &mut end_reason)?,
                    false,
                    accumulated_usage,
                    hallucination_count,
                ));
            };
            match dispatch {
                Ok(j) => {
                    // Success renews recovery attempts, not the learned budget.
                    cw_retries = 0;
                    break (j, round_est_raw);
                }
                Err(e) => {
                    // No-tools recovery: a model that rejects the `tools` field
                    // (deepseek-r1) 400s even on "hello". Drop tools, notice once,
                    // and re-dispatch the same round — self-limiting (the rebuilt
                    // body omits tools) and session-persistent.
                    if tools_supported && is_tools_unsupported_error(&e) {
                        tools_supported = false;
                        if !tools_unsupported_notified {
                            tools_unsupported_notified = true;
                            print_newt(
                                &format!(
                                "{model} does not support tools — tools disabled for this session"
                            ),
                                color,
                                false,
                            );
                        }
                        continue;
                    }
                    // Graceful context-window overflow recovery: parse the model's
                    // real limit, tighten the budget, compress, and retry once (#223;
                    // compress-not-trim since Step 18.4). When the endpoint carries
                    // NO parseable limit — llama.cpp's numberless `500 "Context size
                    // has been exceeded"` — fall back to deriving a tightened cap
                    // from the current send budget. The shared parse-only hook reads
                    // both LiteLLM and vLLM numbered forms in interactive and
                    // headless drivers; this fallback is only for numberless errors.
                    // It remains capped by the operator-declared local window even
                    // though no `num_ctx` field rides on this wire.
                    let overflow =
                        crate::retry::classify(&e) == crate::retry::Retryability::ContextExceeded;
                    // Record the rejected size BEFORE increasing estimation slack.
                    let refused_tokens = cw_overflow::parse_context_window_error(&e.to_string())
                        .map(|(tokens, _)| usize::try_from(tokens).unwrap_or(usize::MAX))
                        .unwrap_or_else(|| calibrate_up(round_est_raw, cal));
                    if overflow {
                        cal = compress_state.calibration.overflow(cal);
                        tool_tokens_real = calibrate_up(tool_tokens, cal);
                    }
                    if cw_retries < 2 {
                        let recovered_window = recover_cw_400.and_then(|f| f(&e, model, &today));
                        if let Some(recovered_budget) = recovered_window
                            .map(|context_window| {
                                recovered_input_budget(
                                    context_window,
                                    input_ceiling_pct,
                                    round_policy.output_allowance,
                                    effective_input_ceiling,
                                )
                            })
                            // Exact admission rejected this candidate, not the
                            // configured server window. Keep its known bound.
                            .or_else(|| request_budget.filter(|budget| measured > *budget))
                            .or_else(|| {
                                cw_overflow::core_recover_overflow(
                                    &e.to_string(),
                                    send_budget,
                                    None,
                                )
                                .map(|cap| cap as usize)
                            })
                            .or_else(|| {
                                overflow.then_some(
                                    send_budget.unwrap_or_else(|| calibrate_up(round_est_raw, cal)),
                                )
                            })
                            .and_then(|budget| {
                                cw_overflow::recovery_target(
                                    budget,
                                    refused_tokens,
                                    effective_input_ceiling,
                                )
                            })
                        {
                            if let Some(context_window) = recovered_window {
                                generation_window = Some(
                                    generation_window
                                        .map_or(context_window, |old| old.min(context_window)),
                                );
                                emit_context_window_400(&mut on_round_usage, context_window);
                            }
                            // The callback returns the endpoint's full hard window,
                            // not an already-discounted input cap. Reserve this
                            // request's maximum output against the actual window,
                            // then retain any tighter declared-window ceiling.
                            let new_budget = effective_input_ceiling
                                .map_or(recovered_budget, |c| recovered_budget.min(c));
                            let new_budget = authoritative_request_budget(
                                Some(new_budget),
                                true,
                                mid_loop_trim_tokens,
                            )
                            .unwrap_or(new_budget);
                            emit_overflow_notice(
                                color,
                                &display::OverflowReason::Refused {
                                    request_estimate: Some(
                                        refused_tokens.min(u32::MAX as usize) as u32
                                    ),
                                    window: recovered_window,
                                    trim_to: new_budget.min(u32::MAX as usize) as u32,
                                },
                                model,
                                cw_retries + 1,
                            );
                            send_budget = Some(new_budget);
                            effective_input_ceiling = Some(new_budget);
                            // The endpoint's parsed hard limit is authoritative
                            // from here on (Step 20.3; mirrors the Ollama path).
                            send_budget_authoritative = true;
                            let compression = context_recovery::compress(
                                CompressRequest {
                                    // Real-token cap minus real-token schema
                                    // overhead → pipeline chars/4 currency
                                    // (Phase 20 §2.3; mirrors the Ollama path).
                                    messages: &messages,
                                    budget: context_recovery::target(
                                        &messages,
                                        calibrate_down(
                                            new_budget.saturating_sub(tool_tokens_real),
                                            cal,
                                        ),
                                        estimation,
                                    ),
                                    max_messages: None,
                                    replay_protected_tail_len:
                                        compress::protected_reasoning_tail_len(
                                            &messages,
                                            reasoning_replay_scope,
                                        )
                                        .max(context_recovery::protected_tool_tail(&messages)),
                                    task: active_task,
                                    hard_budget: true,
                                    authoritative: true,
                                    focus: None,
                                    est: estimation,
                                    summary_input_cap_floor_chars,
                                    rewrites_history,
                                    compaction_store,
                                    compaction_stage: None,
                                },
                                summarizer,
                                compress_state,
                                smart_harness,
                            );
                            let Some(outcome) = cancellable(cancel, compression).await else {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Ok((
                                    smart_harness::cancelled(smart_harness, &mut end_reason)?,
                                    false,
                                    accumulated_usage,
                                    hallucination_count,
                                ));
                            };
                            let outcome = match outcome {
                                Ok(outcome) => outcome,
                                Err(error) => {
                                    context_recovery::record(
                                        &mut solve_obs,
                                        smart_harness,
                                        round,
                                        cw_retries + 1,
                                        round_est_raw,
                                        None,
                                    )?;
                                    return Err(e.context(format!(
                                        "context re-projection failed: {error}"
                                    )));
                                }
                            };
                            if let Some(notice) = outcome.notice {
                                print_harness_notice(&notice, color);
                            }
                            if outcome.action == CompressAction::Refused
                                || !outcome.fired
                                || outcome.tokens_after >= outcome.tokens_before
                            {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Err(e);
                            }
                            if outcome.fired {
                                messages = outcome.messages;
                                prompt_tracker.invalidate();
                                apply_post_compaction_continuation(
                                    worktree_session,
                                    &mut messages,
                                    &mut narration_nudges,
                                    outcome.action,
                                    step_ledger,
                                    prompt_context,
                                    round > 0 && action_nudges,
                                    |candidate| {
                                        openai_chat_wire_messages(candidate).is_ok_and(|wire| {
                                            preflight_full_message_request(
                                                &wire,
                                                tools_supported.then_some(&tools),
                                                authoritative_request_budget(
                                                    send_budget,
                                                    send_budget_authoritative,
                                                    mid_loop_trim_tokens,
                                                ),
                                                cal,
                                                estimation,
                                                model,
                                            )
                                            .is_ok()
                                        })
                                    },
                                );
                                record_compaction_artifact(
                                    &mut repeat_calls,
                                    artifact_sink,
                                    artifact_context,
                                    outcome.action,
                                    outcome.tokens_before,
                                    outcome.tokens_after,
                                    calibrate_down(
                                        new_budget.saturating_sub(tool_tokens_real),
                                        cal,
                                    ),
                                    round,
                                    "context_window_400",
                                    None,
                                    false,
                                    compress_state.floor_trend(),
                                    color,
                                );
                            }
                            let projected = estimate_request_tokens(
                                &openai_chat_wire_messages(&messages)?,
                                tools_supported.then_some(&tools),
                                estimation,
                            );
                            if projected >= round_est_raw
                                || calibrate_up(projected, cal) > new_budget
                            {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Err(e);
                            }
                            context_recovery::record(
                                &mut solve_obs,
                                smart_harness,
                                round,
                                cw_retries + 1,
                                round_est_raw,
                                Some(calibrate_up(projected, cal)),
                            )?;
                            cw_retries += 1;
                            continue;
                        }
                    }
                    if overflow {
                        context_recovery::record(
                            &mut solve_obs,
                            smart_harness,
                            round,
                            cw_retries + 1,
                            round_est_raw,
                            None,
                        )?;
                    }
                    return Err(e);
                }
            }
        };
        // Merge per-round token usage (input = max single prompt, output =
        // sum — Step 18.1) and anchor the context-size tracker.
        let round_usage = openai_usage(&json["usage"]);
        if let Some(prompt_tokens) = json["usage"]["prompt_tokens"]
            .as_u64()
            .and_then(|n| u32::try_from(n).ok())
        {
            compress_state
                .calibration
                .observe(Some(prompt_tokens), round_est_raw);
            cal = compress_state.calibration.ratio(estimate_ratio);
            tool_tokens_real = calibrate_up(tool_tokens, cal);
            prompt_tracker.record(prompt_tokens, messages.len());
        }
        accumulated_usage = merge_round_usage(accumulated_usage, round_usage);

        // Phase 20 §2.2: no `num_ctx` on this wire, so there is no silent
        // head-truncation mode to suspect (oversize requests get a parseable
        // 400 instead). The declared local `num_ctx` still caps Newt's input
        // budget even though that field is not sent on this wire: accepting a
        // prompt with a short reply does not prove the same prompt leaves room
        // for the configured maximum output.
        let truncation_suspect = false;
        if let (Some(u), Some(budget), false) = (round_usage, send_budget, truncation_suspect) {
            let raised = capped_accepted_prompt_tokens(u.input_tokens, effective_input_ceiling);
            if raised > budget {
                send_budget = Some(raised);
                if debug {
                    print_debug(
                        &format!(
                            "send budget raised to ~{raised} tokens (backend accepted \
                             {}-token prompt)",
                            u.input_tokens
                        ),
                        color,
                    );
                }
            }
        }

        let message = &json["choices"][0]["message"];

        // #857: split the reasoning OFF the answer. A `<think>` block (reasoning
        // parser off) must never be returned or fed to the content-scrape recovery,
        // and the separate `reasoning_content` channel (reasoning parser on) is read
        // but never concatenated into the reply. Normal replies (no reasoning) are
        // unchanged: `split_reasoning` returns the content verbatim.
        let (oa_content, inline_reasoning) = crate::reasoning::ThinkFilter::filter_complete(
            message["content"].as_str().unwrap_or(""),
            emits_leading_reasoning,
        );
        let separate_reasoning = message["reasoning_content"]
            .as_str()
            .map(str::trim)
            .filter(|s| !s.is_empty());
        if debug && (separate_reasoning.is_some() || inline_reasoning.is_some()) {
            let n = separate_reasoning
                .map(str::len)
                .or_else(|| inline_reasoning.as_deref().map(str::len))
                .unwrap_or(0);
            print_debug(
                &format!("reasoning ({n} chars) surfaced to the trace, not the answer"),
                color,
            );
        }
        // Show reasoning after the primary SSE response has been validated.
        // Transport streaming keeps cancellation effective; this fold retains
        // the existing presentation after a complete tool/answer decision.
        //
        // Same fold as the streaming path and as a tool result: the first
        // `spill_lines` rows commit, the rest are retained behind
        // `/spill open <id>`, and one line says how long it took.
        commit_reasoning_fold(
            separate_reasoning
                .map(str::to_string)
                .or_else(|| inline_reasoning.clone()),
            thought_for,
            completed_spill_renderer.as_deref(),
            color,
        );
        // Discard the whole capped batch before parsing or dispatching tools.
        if generation_bounds::output_limited(&json) {
            if output_recovery.retry(
                message["tool_calls"]
                    .as_array()
                    .is_some_and(|calls| !calls.is_empty()),
                &mut messages,
                smart_harness,
            )? {
                continue;
            }
            if let Some(obs) = solve_obs.as_deref_mut() {
                obs.behavior_signals
                    .push(observability::BehaviorSignal::ChatCompletionFinish {
                        round,
                        finish_reason: Some("length".into()),
                    });
                let reasoning = separate_reasoning.or(inline_reasoning.as_deref());
                if observability::reasoning_overflow_signature(
                    Some("length"),
                    oa_content.is_empty(),
                    reasoning.is_some(),
                    message["tool_calls"]
                        .as_array()
                        .is_some_and(|calls| !calls.is_empty()),
                ) {
                    obs.behavior_signals
                        .push(observability::BehaviorSignal::ReasoningOverflow {
                            round,
                            reasoning_overflow_detected: true,
                            continuation_attempted: false,
                            continuation_succeeded: false,
                            finish_reason: "length".into(),
                            reasoning_tokens_estimate: estimation.tokens_for_chars(
                                reasoning.map(|text| text.chars().count()).unwrap_or(0),
                            ),
                        });
                }
            }
            let text = finalize_final_text(
                generation_bounds::output_limit_notice(oa_content, round_usage),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            if let Some(slot) = &mut end_reason {
                **slot = Some(crate::TurnEndReason::Failed);
            }
            if let Some(harness) = smart_harness {
                harness.outcome(crate::TurnEndReason::Failed, &text)?;
            }
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
        let native_calls = message["tool_calls"].as_array();
        // Recover tool calls emitted as content instead of the native field —
        // the #1 weak-model failure (see `tool_recovery`). Mirror of the Ollama
        // loop: a local vLLM/llama.cpp server reports OpenAI-wire, so weak models
        // there drop content-emitted calls too. Recovered calls are native-shaped
        // and flow into the executor + is_hallucination path below.
        let mut recovered = if native_calls.map(|t| t.is_empty()).unwrap_or(true) {
            tool_recovery::recover_tool_calls(&oa_content)
        } else {
            tool_recovery::Recovery::default()
        };
        // A recovered call has no provider id; the harness derives one from the
        // call and the attempt that produced it (never for a provider call).
        let recovered_identities = tool_recovery::assign_ids(
            &mut recovered,
            attempt_ledger.and_then(|l| l.lock().ok().and_then(|l| l.latest_primary())),
        );
        let tool_calls: Option<&Vec<serde_json::Value>> = match native_calls {
            Some(t) if !t.is_empty() => Some(t),
            _ if !recovered.calls.is_empty() => Some(&recovered.calls),
            _ => None,
        };
        let has_tools = tool_calls.map(|tc| !tc.is_empty()).unwrap_or(false);
        let finish_reason = json["choices"][0]["finish_reason"].as_str();
        if let Some(obs) = solve_obs.as_deref_mut() {
            obs.behavior_signals
                .push(observability::BehaviorSignal::ChatCompletionFinish {
                    round,
                    finish_reason: finish_reason.map(str::to_string),
                });
        }
        // W0 (#1511): served-model + parse-status observation for the solve
        // contract — mirror of the Ollama loop above.
        if let Some(obs) = solve_obs.as_deref_mut() {
            if let Some(m) = json["model"].as_str().filter(|m| !m.is_empty()) {
                obs.served_model = Some(m.to_string());
            }
            let native = native_calls.is_some_and(|t| !t.is_empty());
            if let Some(sig) = observability::round_parse_signal(
                round,
                !oa_content.is_empty(),
                native,
                recovered.dialect,
                recovered_identities.clone(),
            ) {
                obs.parse_signals.push(sig);
            }
        }
        if debug && !recovered.calls.is_empty() {
            print_debug(
                &format!(
                    "recovered {} tool call(s) from content (non-native emission)",
                    recovered.calls.len()
                ),
                color,
            );
        }

        if debug {
            let excerpt: String = oa_content.chars().take(80).collect();
            let tc_count = tool_calls.map(|tc| tc.len()).unwrap_or(0);
            let usage_str = match round_usage {
                Some(u) => format!("{} in / {} out", u.input_tokens, u.output_tokens),
                None => "no usage".into(),
            };
            print_debug(
                &format!(
                    "round {round}: tool_calls={tc_count} usage=[{usage_str}] content={excerpt:?}"
                ),
                color,
            );
        }

        if !has_tools {
            if let Some(mut nudge) = capability_evidence.correction(
                &oa_content,
                &tools,
                &mut probe_correction_used,
                tools_supported
                    && workflow_runtime.has_next_round(
                        round,
                        current_tool_round_limit,
                        workflow_grace_rounds,
                    )
                    && !is_cancelled(cancel),
            ) {
                if let Some(harness) = smart_harness {
                    nudge = harness.correct_answer(&oa_content, &nudge)?;
                }
                messages.push(serde_json::json!({"role":"assistant", "content":oa_content}));
                messages.push(serde_json::json!({"role":"user", "content":nudge}));
                continue 'round_loop;
            }
            if let Some(harness) = smart_harness {
                let more = workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                );
                let control = harness
                    .classify(&oa_content, narration_nudge_cap, more, cancel)
                    .await?;
                let control = harness
                    .verify_answer(
                        control,
                        self_verify::Concluding {
                            messages: &messages,
                            workspace,
                            task,
                            rounds_left: more,
                            round,
                            ledger: &verification,
                            solve_obs: solve_obs.as_deref_mut(),
                        },
                        smart_verify,
                        &oa_content,
                    )
                    .await?;
                let (text, reason) = match control {
                    smart_harness::Control::Continue(nudge) => {
                        messages
                            .push(serde_json::json!({"role":"assistant", "content":oa_content}));
                        messages.push(serde_json::json!({"role":"user", "content":nudge}));
                        continue 'round_loop;
                    }
                    smart_harness::Control::Answer => (
                        FinalReply::from(oa_content.clone()),
                        crate::TurnEndReason::Completed,
                    ),
                    smart_harness::Control::Finish { text, reason } => (text, reason),
                };
                if let Some(slot) = &mut end_reason {
                    **slot = Some(reason);
                }
                let text = finalize_final_text(
                    text,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                harness.outcome(reason, &text)?;
                return Ok((text, false, accumulated_usage, hallucination_count));
            }

            // Format-hallucination tracker (mirror of the Ollama loop): content
            // that looked like a tool call but couldn't be recovered is counted.
            if recovered.tool_shaped {
                hallucination_count += 1;
                if debug {
                    print_debug(
                        "format-hallucination: tool call emitted as unrecoverable text",
                        color,
                    );
                }
            }
            let content = oa_content.clone();
            if !is_cancelled(cancel)
                && readonly_completion_pending(prompt_disposition, &nudge_classifier, &content)
            {
                let more_rounds = workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                );
                if retry_readonly_completion(
                    &mut messages,
                    &content,
                    None,
                    &mut readonly_completion_retried,
                    more_rounds,
                ) {
                    continue 'round_loop;
                }
                let out = readonly_completion_handoff(
                    &content,
                    &mut end_reason,
                    more_rounds,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                return Ok((out, false, accumulated_usage, hallucination_count));
            }
            if content.is_empty() && debug {
                print_debug(
                    "empty content with no tool calls — model produced nothing",
                    color,
                );
            }
            // Narrate-then-stop rescue (mirror of the Ollama loop): non-empty
            // prose with no tool call. Nudge once and continue instead of ending
            // the turn — bounded by the configured narration_nudge_cap + the round budget.
            let nudge_classification =
                (!content.is_empty()).then(|| nudge_classifier.classify(&content));
            let workflow_classifier_text = workflow_classifier_text(&messages, &content);
            let workflow_hint = nudge_classification
                .as_ref()
                .filter(|classification| classification.is_plan_update())
                .and_then(|_| workflow_steerer.plan_update_hint(&workflow_classifier_text));
            let classifier_plan_direction = nudge_classification
                .as_ref()
                .filter(|classification| classification.is_plan_update())
                .and_then(|_| nudge_classifier.direction_for(crate::NudgeClass::PlanUpdate));
            let plan_nudge_hint =
                combine_nudge_hints(classifier_plan_direction, workflow_hint.as_deref());
            if should_ground_unverified_run_command_blocker(
                &content,
                &tools,
                run_command_denial_observed,
                exec_grounding_turn,
                unverified_exec_blocker_nudges,
                workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                ),
            ) {
                if debug {
                    print_debug(
                        "unsupported run_command blocker — requiring a ground-truth probe",
                        color,
                    );
                }
                messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                messages.push(serde_json::json!({
                    "role": "user",
                    "content": format!(
                        "{} {}",
                        compress::LOOP_GUIDANCE_PREFIX,
                        run_command_ground_truth_nudge()
                    )
                }));
                unverified_exec_blocker_nudges += 1;
                continue 'round_loop;
            }
            if !content.is_empty()
                && pending_plan_nudges < PENDING_PLAN_NUDGE_CAP
                && workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                )
                && action_turn
            {
                let needs_plan_update = nudge_classification
                    .as_ref()
                    .is_some_and(|c| c.is_plan_update());
                if let Some(nudge) = pending_plan_completion_nudge(
                    step_ledger,
                    needs_plan_update,
                    plan_nudge_hint.as_deref(),
                ) {
                    if debug {
                        print_debug(
                            "active plan has unfinished steps — nudging before final answer",
                            color,
                        );
                    }
                    messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                    messages.push(serde_json::json!({
                        "role": "user",
                        "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, nudge)
                    }));
                    pending_plan_nudges += 1;
                    continue 'round_loop;
                }
            }
            if !content.is_empty()
                && stale_file_nudges < STALE_FILE_NUDGE_CAP
                && workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                )
                && action_nudges
                && looks_like_unverified_stale_file_blocker(&content)
            {
                if debug {
                    print_debug(
                        "unverified stale-file blocker — nudging to check ground truth",
                        color,
                    );
                }
                messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                messages.push(serde_json::json!({
                    "role": "user",
                    "content": format!(
                        "{} {}",
                        compress::LOOP_GUIDANCE_PREFIX,
                        stale_file_ground_truth_nudge()
                    ),
                }));
                stale_file_nudges += 1;
                continue 'round_loop;
            }
            if !content.is_empty()
                && narration_nudges < narration_nudge_cap
                && workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                )
                && action_turn
                && nudge_classification
                    .as_ref()
                    .is_some_and(|c| c.is_pending_action())
            {
                if debug {
                    print_debug(
                        "narrated intent with no tool call — nudging to act and continuing",
                        color,
                    );
                }
                // #1158: ephemeral — replace the prior nudge, don't stack.
                strip_trailing_nudge_exchange(&mut messages);
                messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                // First nudge: the (tunable) classifier direction. Later
                // nudges (cap > 1) escalate — name the active step, demand a
                // bare tool call (mirrors the Ollama loop).
                let direction = if narration_nudges == 0 {
                    nudge_classification
                        .as_ref()
                        .and_then(|classification| {
                            nudge_classifier.direction_for(classification.class)
                        })
                        .map(workflow_guidance)
                        .unwrap_or_else(narration_action_nudge)
                } else {
                    escalated_narration_action_nudge(
                        narration_nudges + 1,
                        narration_nudge_cap,
                        step_ledger,
                    )
                };
                messages.push(serde_json::json!({
                    "role": "user",
                    "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, direction),
                }));
                narration_nudges += 1;
                continue 'round_loop;
            }
            // Self-verify gate (#23): the model is concluding with usable content.
            // If the workspace ships a verification (tests / a make·just·npm·cargo
            // target / a command the instruction names) it NEVER ran this turn,
            // hand it one more round to run it before we accept the finish — the
            // measured #1 capability lever (models declare done on broken
            // solutions). Gated by the action-nudge switch (`/nudge off`) and
            // capped so a model that won't verify still ends the turn. The
            // `workflow_runtime.has_next_round(round, current_tool_round_limit, workflow_grace_rounds)` guard (cursor[bot], #1483)
            // mirrors the narration/stale-file nudges: on the FINAL round a
            // verify nudge would burn the pending answer into a cap-exit with
            // zero rounds left to actually run anything — step aside and accept.
            // #2315: in the opt-in result-aware mode the same position decides
            // from observed outcomes instead (A12: one decision, three callers).
            let mut verification_stop = None;
            if verification.result_aware() && action_nudges && !content.is_empty() {
                match self_verify::conclude_turn(
                    self_verify::Concluding {
                        messages: &messages,
                        workspace,
                        task: active_task,
                        rounds_left: workflow_runtime.has_next_round(
                            round,
                            current_tool_round_limit,
                            workflow_grace_rounds,
                        ),
                        round,
                        ledger: &verification,
                        solve_obs: solve_obs.as_deref_mut(),
                    },
                    verification_nudges,
                )
                .await
                {
                    self_verify::Decision::Nudge(nudge) => {
                        strip_trailing_nudge_exchange(&mut messages);
                        messages
                            .push(serde_json::json!({ "role": "assistant", "content": content }));
                        messages.push(serde_json::json!({
                            "role": "user",
                            "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, nudge),
                        }));
                        verification_nudges += 1;
                        continue 'round_loop;
                    }
                    self_verify::Decision::Stop(reason) => verification_stop = Some(reason),
                    self_verify::Decision::Accept => {}
                }
            } else if self_verify::enabled()
                && action_nudges
                && self_verify_nudges < SELF_VERIFY_CAP
                && workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                )
                && !content.is_empty()
            {
                let cmds = self_verify::commands_from_messages(&messages);
                let checks = verification
                    .applicable_checks(workspace, active_task, &cmds)
                    .await
                    .unwrap_or_default();
                if let Some(nudge) = self_verify::verify_gate_nudge(&checks, &cmds) {
                    if debug {
                        print_debug(
                            "concluding with unrun verification — self-verify nudge",
                            color,
                        );
                    }
                    strip_trailing_nudge_exchange(&mut messages);
                    messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                    messages.push(serde_json::json!({
                        "role": "user",
                        "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, nudge),
                    }));
                    self_verify_nudges += 1;
                    continue 'round_loop;
                }
            }
            // Phase 20 §2.2: non-empty final content is usable output —
            // report the accepted prompt before returning.
            if !content.is_empty() {
                emit_accepted(
                    &mut on_round_usage,
                    round_usage,
                    truncation_suspect,
                    round_est_raw,
                );
            }
            // Acceptance forensics (mirrors the Ollama macro): record WHY
            // this no-tool reply ends the turn. #1261: includes the gate's
            // `action_turn` guard — where the rescue can never arm (non-Act
            // turn / non-action-inviting prompt), prose is the legitimate
            // ending, never a "budget spent" anomaly.
            let accepted_reason = if content.is_empty() {
                crate::TurnEndReason::Empty
            } else if nudge_classification
                .as_ref()
                .is_some_and(|c| c.is_pending_action())
                && action_turn
            {
                if !workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                ) {
                    crate::TurnEndReason::NarrationFinalRound
                } else {
                    crate::TurnEndReason::NarrationCapExhausted
                }
            } else {
                crate::TurnEndReason::Completed
            };
            let accepted_reason = verification_stop.unwrap_or(accepted_reason);
            if debug && accepted_reason != crate::TurnEndReason::Completed {
                print_debug(
                    &format!("no-tool reply accepted as final answer ({accepted_reason:?})"),
                    color,
                );
            }
            if let Some(slot) = &mut end_reason {
                **slot = Some(accepted_reason);
            }
            if content.is_empty() {
                let out = FinalReply::harness("(model returned an empty response — try rephrasing, or check the model with `newt doctor`)".to_string());
                let out = finalize_final_text(
                    out,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                observability::observe_harness_reply(&mut solve_obs);
                return Ok((out, false, accumulated_usage, hallucination_count));
            }
            // Esc after the answer arrived: the operator asked to stop, so the
            // turn ends empty (the round-boundary contract) while the paid
            // round's usage stands.
            if is_cancelled(cancel) {
                return Ok((
                    smart_harness::cancelled(smart_harness, &mut end_reason)?,
                    false,
                    accumulated_usage,
                    hallucination_count,
                ));
            }
            // #2372: the accepted, gated `content` IS the reply. It is never
            // generated a second time for display: the host renders it (the TUI
            // prints a non-streamed reply), so what the operator sees, what the
            // caller returns and what the ledger counts are one generation.
            // #1964: the same claim check + disclosure gate as a cap-exit summary.
            let out = finalize_final_text(
                content,
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            return Ok((out, false, accumulated_usage, hallucination_count));
        }

        // Record the assistant turn (it carries the tool_calls), then VALIDATE the
        // whole batch before emitting acceptance or running any call (#1528 B4).
        // The accepted observation is emitted AFTER whole-batch validation and
        // BEFORE the first tool side effect, below.
        // #857: unknown endpoints keep the historical clean replay (no inline
        // <think> or reasoning_content). A capability-profiled reasoning backend
        // may instead retain the assistant's current-turn plan across tool rounds.
        // Some proxies omit the otherwise-required role; preparation also
        // canonicalizes that field before compression can inspect tool pairs.
        let mut assistant_turn =
            prepare_openai_assistant_replay(message, &oa_content, reasoning_replay_scope, true);
        // A recovered call was never in the provider's message, so the replayed
        // turn has no `tool_calls` for its tool result to answer. Add them, in
        // wire shape, with the derived ids; the original text stays in
        // `content` as the evidence they were derived from.
        if !recovered_identities.is_empty() {
            assistant_turn["tool_calls"] =
                serde_json::Value::Array(tool_recovery::wire_tool_calls(&recovered.calls));
        }
        messages.push(assistant_turn);
        let mut round_modified_workspace = false;
        let mut round_progress = false;
        let mut round_succeeded = false;
        let tcs = tool_calls.unwrap();
        // Phase 1 (invariant #3, BATCH level): validate the ENTIRE batch before
        // any side effect. Every OpenAI `tool_call` must have a non-empty, UNIQUE
        // `id` and a valid name/object-args; a bad sibling rejects the WHOLE batch
        // — echo the reason for each call (keyed by its id) and execute nothing,
        // so no valid call mutates the workspace ahead of an unvalidated batch.
        //
        // Some API proxies (NVIDIA inference → Anthropic backend) wrap
        // Anthropic-native tool-use blocks in the OpenAI `tool_calls` array
        // without converting the inner schema, so fall back to `name`/`input`
        // when the `function` key is absent.
        let extracted: Vec<(Option<&str>, Option<&str>, &serde_json::Value)> = tcs
            .iter()
            .map(|tc| {
                if tc["function"].is_null() {
                    (tc["id"].as_str(), tc["name"].as_str(), &tc["input"])
                } else {
                    (
                        tc["id"].as_str(),
                        tc["function"]["name"].as_str(),
                        &tc["function"]["arguments"],
                    )
                }
            })
            .collect();
        let validated = match tools::validate_tool_call_batch(&extracted, true) {
            Ok(v) => {
                uncorrelatable_batches = 0;
                Some(v)
            }
            Err(tools::BatchRejection::CorrelationImpossible(reason)) => {
                // A missing/blank/duplicate `tool_call_id`: a tool result cannot
                // be correlated. Never fabricate an id — re-ask, or abort once
                // the budget is spent.
                let reask = tools::reask_uncorrelatable(
                    &mut uncorrelatable_batches,
                    &reason,
                    smart_harness,
                    tool_events.as_deref_mut(),
                )?;
                if let Some(turn) = messages.last_mut() {
                    tools::withdraw_tool_calls(turn);
                }
                messages.push(serde_json::json!({"role": "user", "content": reask}));
                continue 'round_loop;
            }
            Err(tools::BatchRejection::ContentInvalid(reason)) => {
                uncorrelatable_batches = 0;
                if let Some(harness) = smart_harness {
                    harness.reject_tools(&reason, true)?;
                }
                // ids are valid + unique → echo a correctly keyed rejection per
                // call and re-dispatch so the model can retry.
                for tc in tcs {
                    let id = tc["id"].as_str().unwrap_or("");
                    print_synthetic_tool_result(
                        "(rejected tool-call batch)",
                        &serde_json::Value::Null,
                        workspace,
                        &reason,
                        color,
                        &completed_spill_renderer,
                    );
                    if let Some(rec) = tool_events.as_deref_mut() {
                        rec.push(crate::ToolEvent::from_call(
                            "(rejected tool-call batch)",
                            &serde_json::Value::Null,
                            false,
                            Some(0),
                        ));
                    }
                    smart_harness::push_tool_message(
                        &mut messages,
                        serde_json::json!({
                            "role": "tool",
                            "tool_call_id": id,
                            "content": format!("tool-call batch rejected before execution: {reason}"),
                        }),
                        smart_harness,
                        true,
                        "(rejected tool-call batch)",
                    )?;
                }
                None
            }
        };
        // #1528 B4: a FULLY-VALIDATED tool-call batch is usable output — emit the
        // accepted-prompt observation now, AFTER whole-batch validation and BEFORE
        // the first tool side effect below. A correlation-impossible batch aborted
        // above (early `Err`, RR2) and a content-invalid batch leaves
        // `validated == None` (RR1); neither is provider-accept evidence, so
        // neither ratchets the learned budget.
        let batch = smart_harness
            .zip(validated.as_ref())
            .map(|(harness, calls)| harness.tool_batch(calls, &messages))
            .transpose()?;
        let mut tool_warnings = Vec::new();
        if validated.is_some() {
            emit_accepted(
                &mut on_round_usage,
                round_usage,
                truncation_suspect,
                round_est_raw,
            );
            commit_tool_round_narration(
                &oa_content,
                false,
                completed_spill_renderer.as_deref(),
                color,
            );
        }
        // Phase 2: every call is valid — execute in order (empty when rejected).
        for (call_index, (tc, vc)) in tcs.iter().zip(validated.iter().flatten()).enumerate() {
            let id = vc.call_id.as_str();
            let name = vc.name.as_str();
            let args = vc.args.clone();
            announce_tool_activity(name);
            // Per-tool head: any frame from the PREVIOUS tool in this batch
            // comes down before this iteration's first writer (the debug /
            // trace echoes below print BEFORE the wired `call()` erase).
            dismiss_completed_spill(&completed_spill_renderer);
            if debug && tc["function"].is_null() {
                print_debug(
                    &format!(
                        "tool call in Anthropic-native format inside tool_calls array \
                         (no `function` key) — name={name:?}"
                    ),
                    color,
                );
            }
            if trace {
                print_trace(
                    &format!(
                        "raw tool_call element: {}",
                        serde_json::to_string(tc).unwrap_or_else(|_| "?".into())
                    ),
                    color,
                );
            }
            let mcp_handles = mcp.handles(name);
            if debug {
                print_debug(
                    &format!("dispatching tool name={name:?} mcp_handles={mcp_handles}"),
                    color,
                );
            }
            if is_hallucination(name, &args) {
                hallucination_count += 1;
            }
            // #2637: never refuse an exact bare re-read — serve it silently
            // from the memo when the file's actual current content still
            // matches; otherwise fall through to a real read below.
            if let Some(content) =
                repeat_calls.cached_read(name, &args, ReadScope { workspace, caveats })
            {
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &content,
                    color,
                    &completed_spill_renderer,
                );
                if let Some(rec) = tool_events.as_deref_mut() {
                    rec.push(crate::ToolEvent::from_cache(name, &args));
                }
                let offloaded =
                    maybe_offload_tool_result(name, content, tool_offload, spill_store, disclosure);
                smart_harness::push_tool_resolution(
                    &mut messages,
                    serde_json::json!({
                        "role": "tool",
                        "tool_call_id": id,
                        "content": offloaded,
                    }),
                    batch.as_ref(),
                    call_index,
                )?;
                continue;
            }
            // Step 27.3/#771: short-circuit selected exact repeats (mirrors the
            // Ollama path; Responses uses function_call_output). Counted as a
            // hallucination above first when applicable.
            if let Some(steer) = repeat_calls.repeat_steer(name, &args) {
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &steer,
                    color,
                    &completed_spill_renderer,
                );
                if let Some(rec) = tool_events.as_deref_mut() {
                    rec.push(crate::ToolEvent::from_call(name, &args, false, Some(0)));
                }
                smart_harness::push_tool_resolution(
                    &mut messages,
                    serde_json::json!({
                        "role": "tool",
                        "tool_call_id": id,
                        "content": steer,
                    }),
                    batch.as_ref(),
                    call_index,
                )?;
                continue;
            }
            let invocation = batch
                .as_ref()
                .map(|batch| batch.start(call_index, disclosure))
                .transpose()?;
            record_organic_note_use(name, &note_sink, &mut note_nudge);
            // retry technique: snapshot the file's pre-write bytes before the
            // write tool runs, so the post-turn gate can revert exactly newt's writes.
            let before_change =
                progress_workspace_state(name, &args, workspace, &caveats.fs_read).await;
            ledger_note_write(write_ledger, name, &args, workspace);
            let tool_t0 = std::time::Instant::now();
            let execution = std::sync::OnceLock::new();
            let retry_authorized = std::sync::OnceLock::new();
            let routed_to = std::sync::OnceLock::new();
            let governed_pr = std::sync::OnceLock::new();
            let report_capture = std::sync::Mutex::new(observed_report::Capture::default());
            let command_directory = std::sync::OnceLock::new();
            let attribution_epoch = AttributionEpoch::new(attribution, git_tool, model, name);
            // #727: intercept the read-only budget self-read (see the Ollama path).
            // OpenAI-compatible endpoints do not receive `num_ctx`, but a local
            // endpoint's operator-declared window still provides the displayed
            // input ceiling. Cloud endpoints normally leave it unset.
            let result = if tools::is_context_remaining_call(name) {
                let report = budget::render_context_budget(
                    prompt_tracker.current(&messages, Some(&tools), cal, estimation),
                    effective_input_ceiling,
                    num_ctx,
                    input_ceiling_pct,
                    low_budget_pct,
                );
                if let Some(invocation) = &invocation {
                    invocation.host();
                    invocation.observe(&report, None, spill_store)?;
                }
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &report,
                    color,
                    &completed_spill_renderer,
                );
                report
            } else {
                // #1947: distil the ledger BEFORE the call. What a
                // `render_report` in THIS call can be checked against is what
                // the turn has already done — the events for this very call
                // are pushed after it returns.
                let tool_evidence = tool_events
                    .as_deref()
                    .map(|e| capability_check::Evidence::from_events(e));
                let Some(result) = tools::execute_tool_with_collaborators(
                    name,
                    &args,
                    workspace,
                    color,
                    tool_output_lines,
                    caveats,
                    mcp,
                    tools::ToolCollaborators {
                        command_budget,
                        shell_dialect,
                        read_history: Some(&mut read_history),
                        default_command_cwd,
                        worktree_session,
                        invocation: invocation.as_ref(),
                        build_check_cmd: build_check_cmd.as_deref(),
                        tool_evidence: tool_evidence.as_ref(),
                        // Reborrow + re-coerce: shortens the trait-object
                        // lifetime to this call (Option<&mut dyn _> is
                        // invariant, so the longer ChatCtx lifetime can't
                        // unify directly).
                        note_sink: note_sink
                            .as_deref_mut()
                            .map(|s| &mut *s as &mut dyn NoteSink),
                        recall_source,
                        memory_source,
                        prompt_context: Some(prompt_context),
                        artifact_context,
                        artifact_sink,
                        // #263 prompted grants — same reborrow pattern.
                        permission_gate: permission_gate
                            .as_deref_mut()
                            .map(|g| &mut *g as &mut dyn PermissionGate),
                        exec_floor,
                        git_tool,
                        crew_runner,
                        scratchpad_store,
                        code_search,
                        where_is,
                        nav,
                        experience_store,
                        step_ledger,
                        operating_mode_control,
                        plan_mode_control,
                        plan_draft_sink,
                        spill_store,
                        persona_tools,
                        hidden_tools: Some(&hidden_tools),
                        live_tool_output: live_tool_output.clone(),
                        completed_spill_renderer: completed_spill_renderer.clone(),
                        execution: Some(&execution),
                        retry_authorized: Some(&retry_authorized),
                        governed_pr: Some(&governed_pr),
                        report_capture: Some(&report_capture),
                        command_directory: Some(&command_directory),
                        routed_to: Some(&routed_to),
                        pending_rerun: Some(&mut pending_rerun),
                    },
                    tool_offload,
                    prompt_disposition,
                    cancel,
                )
                .await?
                else {
                    return Ok((
                        smart_harness::cancelled(smart_harness, &mut end_reason)?,
                        false,
                        accumulated_usage,
                        hallucination_count,
                    ));
                };
                result
            };
            if debug {
                // This line lands directly below the viewport `result` just
                // painted — take the frame down first or its later rewind
                // erases this line and strands frame rows.
                dismiss_completed_spill(&completed_spill_renderer);
                let excerpt: String = result.chars().take(120).collect();
                print_debug(&format!("tool result: {excerpt:?}"), color);
            }
            // 17.6: record the call for the turn's events column (mirrors
            // the Ollama path) — digested args, duration as a display claim.
            // Step 27.3/#771: classify once; remember repeat-steered outcomes
            // (mirrors Ollama path).
            let ok = tools::tool_ok(&result, execution.get().copied());
            round_succeeded |= ok;
            attribution_epoch.finish(&args, ok);
            run_command_denial_observed |= run_command_result_is_denial(name, ok, &result);
            capability_evidence.record(name, ok, execution.get().copied());
            let after_change = if before_change.is_some() {
                progress_workspace_state(name, &args, workspace, &caveats.fs_read).await
            } else {
                None
            };
            round_modified_workspace |=
                workflow_runtime.record_workspace_change(before_change, after_change);
            round_progress |= workflow_runtime.record_observation(
                name,
                &args,
                &result,
                ok,
                execution.get().copied(),
                routed_to.get(),
            );
            repeat_calls.record(
                name,
                &args,
                ok,
                &result,
                execution.get().copied(),
                ReadScope { workspace, caveats },
            );
            repeat_calls.permit_authorized_retry(name, &args, &retry_authorized);
            append_clean_build_warning(
                if batch.is_some() {
                    &mut tool_warnings
                } else {
                    &mut messages
                },
                &mut clean_build,
                &args,
                None,
            )?;
            record_completed_tool_event(
                &mut tool_events,
                name,
                &args,
                ok,
                execution.get().copied(),
                tool_t0,
            );
            turn_claims.observe_report(
                workspace,
                &caveats.fs_read,
                &report_capture.lock().expect("report capture"),
                execution.get().copied(),
                governed_pr.get(),
            );
            if let Some(outcome) = governed_pr.get() {
                verification.record_publication_outcome(outcome);
            }
            if ok {
                if let Some(directory) = command_directory.get() {
                    verification.record_command_directory(directory);
                }
            }
            verification
                .observe_routed(
                    name,
                    &args,
                    ok,
                    execution.get().copied(),
                    workspace,
                    routed_to.get(),
                )
                .await;
            record_phantom_reach(
                &mut phantom_reaches,
                name,
                &args,
                &result,
                ok,
                advertise_team,
            );
            // #867 Part A: ledger verified paths (see the Ollama path).
            observed_paths.record(&result, &mut observed_resolver);
            smart_harness::push_tool_return(
                &mut messages,
                serde_json::json!({
                    "role": "tool",
                    "tool_call_id": id,
                    // Step 26.3 (#584): see the Ollama path.
                    "content": smart_harness::tool_result(name, result, tool_offload, spill_store, disclosure, invocation.as_ref())?,
                }),
                invocation.as_ref(),
            )?;
        }
        for message in tool_warnings {
            smart_harness::push_tool_message(
                &mut messages,
                message,
                smart_harness,
                true,
                "build guidance",
            )?;
        }
        if let Some(harness) = smart_harness {
            harness.record_messages(&messages)?;
        }
        if round_succeeded {
            output_recovery.completed_tool_round();
        }
        workflow_runtime.record_round_outcome(round_modified_workspace, round_progress);
        if let Some(text) = pending_plan_approval_handoff(
            plan_mode_control,
            PlanRoundFacts {
                disposition: prompt_disposition,
                step_ledger,
                plan_at_turn_start: &plan_at_turn_start,
                progressed: round_modified_workspace || round_progress,
            },
            smart_harness,
            cancel,
            &mut end_reason,
        )? {
            dismiss_completed_spill(&completed_spill_renderer);
            let text = finalize_final_text(
                FinalReply::harness(text),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
    }

    // Reached the round cap; the last tool's completed viewport is still up
    // and nothing has written since — dismiss before any summary output.
    dismiss_completed_spill(&completed_spill_renderer);
    // Trim the message list and make ONE final
    // tools-disabled completion (matches the Ollama path).
    let protected_head = protected_prompt_head_len(&messages, prompt_read::ACTIVE_PROMPT_PREFIX);
    let replay_protected_tail_len =
        compress::protected_reasoning_tail_len(&messages, reasoning_replay_scope);
    let trimmed = trim_for_summary(&messages, protected_head, 6.max(replay_protected_tail_len));
    // Step 27.5: salvage progress + failed-call count (matches the Ollama path).
    let progress = cap_exit_progress(worktree_session, step_ledger, scratchpad_store);
    // #2374: a failed check at the round limit is a scored repair exhaustion.
    let cap_reason = verification
        .cap_exit_reason(
            workspace,
            if smart_harness.is_some() {
                smart_verify
            } else {
                action_nudges
            },
            current_tool_round_limit,
            solve_obs.as_deref_mut(),
        )
        .await;
    if let Some(hit) = &mut round_cap_hit {
        **hit = true;
    }
    if let Some(harness) = smart_harness {
        harness.record_messages(&messages)?;
        let text = cap_exit_fallback(
            current_tool_round_limit,
            accumulated_usage,
            repeat_calls.total_failures(),
            progress.as_deref(),
        );
        let text = finalize_final_text(
            text,
            workspace,
            &caveats.fs_read,
            &capability_evidence,
            disclosure,
            &turn_claims,
            &verification,
        );
        harness.outcome(cap_reason, &text)?;
        if let Some(slot) = &mut end_reason {
            **slot = Some(cap_reason);
        }
        return Ok((text, false, accumulated_usage, hallucination_count));
    }

    let cap = CapExit {
        max_tool_rounds: current_tool_round_limit,
        accumulated: accumulated_usage,
        wasted_calls: repeat_calls.total_failures(),
        progress,
        observed: observed_paths.into_vec(),
        request_budget: authoritative_request_budget(
            send_budget,
            send_budget_authoritative,
            mid_loop_trim_tokens,
        ),
        calibration: cal,
        estimation,
        ollama_options: None,
        prompt_measurement: Default::default(),
        fell_back: Default::default(),
    };
    let summary = final_summary_openai(
        (&client, &stream_client),
        &chat_url,
        model,
        api_key,
        trimmed,
        generation_policy,
        generation_window,
        &cap,
        attempts,
    );
    let Some(result) = cancellable(cancel, summary).await else {
        cap.learn_measurement(compress_state)?;
        return Ok((
            smart_harness::cancelled(smart_harness, &mut end_reason)?,
            false,
            accumulated_usage,
            hallucination_count,
        ));
    };
    let (text, streamed, usage) = cap.recover_rejection(
        result,
        &mut solve_obs,
        compress_state,
        current_tool_round_limit,
        cw_retries + 1,
    )?;
    let text = finalize_final_text(
        text,
        workspace,
        &caveats.fs_read,
        &capability_evidence,
        disclosure,
        &turn_claims,
        &verification,
    );
    if let Some(slot) = &mut end_reason {
        **slot = Some(cap_reason);
    }
    Ok((text, streamed, usage, hallucination_count))
}

// ── Anthropic Messages API (`POST /v1/messages`) ───────────────────────────
//
// The fourth parallel loop: a focused clone of
// `openai_chat_complete_with_prompt_and_artifacts` over Anthropic's native
// wire. The running transcript stays in the internal OpenAI-ish shape (see
// `anthropic_wire`) and is converted at dispatch only, so every shared
// subsystem — compression, nudges, claim check, budgets, repeat-call guard,
// self-verify — is the same loop-policy code as the OpenAI path. Only the
// dispatch/decode seams differ: URL, headers (`x-api-key`, never bearer),
// request body, the `AnthropicRound` decode, and native SSE streaming.

/// Anthropic auth headers: `x-api-key` when a non-empty key is configured
/// (NEVER bearer auth on this wire) plus the pinned `anthropic-version`.
fn anthropic_headers(
    req: reqwest::RequestBuilder,
    api_key: Option<&str>,
) -> reqwest::RequestBuilder {
    let req = match api_key.filter(|k| !k.is_empty()) {
        Some(key) => req.header("x-api-key", key),
        None => req,
    };
    req.header("anthropic-version", crate::backend_probe::ANTHROPIC_VERSION)
}

/// Per-turn dispatch context for the Anthropic loop, bundled so
/// [`anthropic_dispatch_round`] keeps a reviewable signature.
struct AnthropicDispatch<'a> {
    smart_harness: Option<&'a smart_harness::SmartHarness>,
    /// Whole-request-timeout client for `stream:false` bodies (a total bound
    /// is correct for a single-shot response — mirrors the OpenAI path).
    client: &'a reqwest::Client,
    /// Idle-read-timeout client for `stream:true` bodies (mirrors the Ollama
    /// path's #643 rationale: a progressing token stream must never be
    /// aborted by a whole-request deadline; only silence times out).
    stream_client: &'a reqwest::Client,
    messages_url: &'a str,
    api_key: Option<&'a str>,
    retry: &'a RetryPolicy,
    color: bool,
    markdown: bool,
    /// Buffer answer deltas until the harness can prepend its observed report.
    defer_answer: bool,
    /// Where a folded reasoning body is retained, so the closing line's
    /// `/spill open <id>` names something real rather than gesturing at it.
    retain: Option<&'a std::sync::Arc<dyn CompletedSpillRenderer>>,
}

/// One `/v1/messages` dispatch → one decoded [`anthropic_wire::AnthropicRound`].
///
/// `stream:false`: the whole exchange (send + status + JSON body) sits in the
/// retry envelope exactly like the OpenAI path's dispatch, then
/// [`anthropic_wire::parse_messages_reply`] decodes it.
///
/// `stream:true`: only send()+status-check sit in the retry envelope; the SSE
/// body is consumed OUTSIDE it (a re-sent body after visible output would
/// re-print). Unless `defer_answer` is set, text deltas print live (spinner teardown before the first
/// visible char, the `▸  ` prefix, the markdown block writer when markdown is
/// on); thinking deltas go to the spinner detail. A mid-stream failure follows the #640 policy: with no
/// visible output the round is re-issued under the retry budget; with partial
/// visible output the partial answer is kept with a notice.
///
/// Returns `Ok(None)` when the user interrupted before the round produced a
/// result (Esc / Ctrl-C) — the caller ends the turn with an empty reply. The
/// returned bool is true iff visible answer text was printed live via SSE.
async fn anthropic_dispatch_round(
    d: &AnthropicDispatch<'_>,
    body: &serde_json::Value,
    messages: &[serde_json::Value],
    stream: bool,
    cancel: Option<&std::sync::atomic::AtomicBool>,
    attempts: Option<attempt_capture::AttemptScope<'_>>,
) -> anyhow::Result<Option<(anthropic_wire::AnthropicRound, bool)>> {
    if !stream {
        let result = cancellable(
            cancel,
            with_backoff_notify_error(
                d.retry,
                || async {
                    let req = anthropic_headers(d.client.post(d.messages_url), d.api_key);
                    let req = match d.smart_harness {
                        Some(harness) => req
                            .header(reqwest::header::CONTENT_TYPE, "application/json")
                            .body(harness.prepare_with_messages(body, "anthropic", messages)?),
                        None => req.json(body),
                    };
                    // W0 (#1511): classify while the error is TYPED — mirrors
                    // the OpenAI path's dispatch site.
                    let (resp, attempt) =
                        attempt_capture::send(attempts, "primary", req, "request failed").await?;
                    let json = smart_harness::response(resp, d.smart_harness, "inference endpoint")
                        .await?;
                    Ok((json, attempt))
                },
                |attempt, delay, error| {
                    print_retry_indicator(attempt, d.retry.max_retries, delay, error, d.color);
                },
            ),
        )
        .await;
        return match result {
            None => Ok(None),
            Some(Ok((json, attempt))) => {
                let round = anthropic_wire::parse_messages_reply(&json);
                attempt_capture::complete(attempt.as_ref(), round.usage);
                Ok(Some((round, false)))
            }
            Some(Err(e)) => Err(e),
        };
    }

    // Mid-body failures happen OUTSIDE the send/status retry envelope (which
    // cannot see them), so the no-visible-output re-issues below are bounded
    // by the same policy's retry budget with its own delays.
    let mut stream_retries: u32 = 0;
    loop {
        let resp = match cancellable(
            cancel,
            with_backoff_notify_error(
                d.retry,
                || async {
                    let req = anthropic_headers(d.stream_client.post(d.messages_url), d.api_key)
                        .json(body);
                    let (resp, attempt) =
                        attempt_capture::send(attempts, "primary", req, "stream request failed")
                            .await?;
                    if !resp.status().is_success() {
                        let status = resp.status();
                        let (bytes, read_error) = crate::retry::read_response_bytes(resp).await;
                        let text = String::from_utf8_lossy(&bytes);
                        let read_diagnostic = read_error
                            .map(|error| format!("; response body read failed: {error}"))
                            .unwrap_or_default();
                        return Err(observability::DispatchError::http_status(format!(
                            "inference endpoint {status}: {text}{read_diagnostic}"
                        ))
                        .into());
                    }
                    Ok((resp, attempt))
                },
                |attempt, delay, error| {
                    print_retry_indicator(attempt, d.retry.max_retries, delay, error, d.color);
                },
            ),
        )
        .await
        {
            None => return Ok(None),
            Some(r) => r?,
        };
        let (resp, attempt) = resp;

        // The ONE spinner (`newt_core::tty`), gated on a colour terminal with
        // thinking shown; the accumulated round text stays RAW (it is
        // persisted and re-sent), display styling never enters it.
        let mut spinner = crate::tty::Spinner::start_with_caps(
            legacy_caps(d.color && thinking_stream_enabled()),
            "thinking…",
            crate::tty::Sink::Stdout,
            d.color,
        );
        let cols = display::term_cols();
        let mut md = (d.markdown && !d.defer_answer).then(|| {
            MarkdownStreamWriter::new(
                io::stdout(),
                RenderOpts {
                    color: true,
                    cols: display::reply_cols(cols),
                },
            )
        });
        let mut acc = anthropic_wire::SseAccumulator::new();
        // The same bounded reasoning block the other two wires commit. Anthropic
        // streams thinking as its own SSE action rather than inline `<think>`,
        // but the operator-facing question — "how much of this do I want in my
        // scrollback" — is identical, so it gets the identical answer.
        let anth_budget =
            if display::with_migration_notices(thinking_mode) == crate::ThinkingMode::Fold {
                display::spill_lines()
            } else {
                0
            };
        let mut anth_reason = ReasoningTrickle::default();
        let mut started = false;
        let mut transport_break: Option<String> = None;
        let mut interrupted = false;
        // The bytes of a character that has only half arrived. See `decode_chunk`.
        let mut carry: Vec<u8> = Vec::new();
        let mut resp = resp;
        while !acc.is_done() {
            match cancellable(cancel, resp.chunk()).await {
                // Interrupted: stop reading and keep what already streamed.
                None => {
                    interrupted = true;
                    break;
                }
                Some(Ok(Some(chunk))) => {
                    // Two rolling buffers: `decode_chunk` carries half a
                    // CHARACTER to the next chunk, and the accumulator carries
                    // half a `data:` LINE, since both straddle chunk boundaries.
                    for action in acc.feed(&decode_chunk(&mut carry, &chunk)) {
                        match action {
                            anthropic_wire::StreamAction::TextDelta(t) => {
                                if d.defer_answer {
                                    if let Some(sp) = spinner.take() {
                                        anth_reason.close(
                                            sp.elapsed(),
                                            d.retain.map(std::sync::Arc::as_ref),
                                            d.color,
                                        );
                                    }
                                    continue;
                                }
                                if !started {
                                    // The answer is starting — close the
                                    // reasoning block while the spinner's clock
                                    // is still readable, then tear it down.
                                    if let Some(sp) = spinner.as_ref() {
                                        anth_reason.close(
                                            sp.elapsed(),
                                            d.retain.map(std::sync::Arc::as_ref),
                                            d.color,
                                        );
                                    }
                                    drop(spinner.take());
                                    if d.color {
                                        execute!(
                                            io::stdout(),
                                            SetForegroundColor(NEWT_ORANGE_CT),
                                            Print(display::REPLY_MARKER),
                                            ResetColor,
                                        )
                                        .ok();
                                    } else {
                                        print!("{}", display::REPLY_MARKER);
                                    }
                                    started = true;
                                }
                                if let Some(w) = md.as_mut() {
                                    w.push(&t).ok();
                                } else {
                                    print!("{t}");
                                    io::stdout().flush().ok();
                                }
                            }
                            anthropic_wire::StreamAction::ThinkingDelta(t) => {
                                if let Some(sp) = spinner.as_ref() {
                                    anth_reason.feed(sp, &t, anth_budget);
                                }
                            }
                        }
                    }
                }
                Some(Ok(None)) => break,
                Some(Err(e)) => {
                    transport_break = Some(format!("stream request failed: {e}"));
                    break;
                }
            }
        }
        drop(spinner.take());
        if let Some(w) = md.as_mut() {
            w.finish().ok();
        }
        if started && md.is_none() {
            println!();
        }
        let done = acc.is_done();
        let round = acc.finish();

        // #640 mid-stream-break policy (mirrors the Ollama path): a stream
        // `error` event or a transport break after visible output keeps the
        // partial text with a notice; before any visible output it converts
        // to the retryable error shape and this round is re-issued.
        let break_error = round.error.clone().or(transport_break);
        // #2313: an interrupt is cancelled; otherwise ok only for a stream that
        // reached `message_stop` with no error, and a cut stream or an error
        // event is failed. Reported usage attaches either way.
        attempt_capture::finish(
            attempt.as_ref(),
            if interrupted {
                crate::attempts::AttemptState::Cancelled
            } else if done && break_error.is_none() {
                crate::attempts::AttemptState::Ok
            } else {
                crate::attempts::AttemptState::Failed
            },
            round.usage,
        );
        if let Some(err) = break_error {
            let shaped: anyhow::Error = observability::DispatchError::http_status(format!(
                "inference endpoint 529: mid-stream error: {err}"
            ))
            .into();
            // A server capacity rejection belongs to the outer projection
            // owner, even if text preceded it. Never replay this body unchanged.
            if crate::retry::classify(&shaped) != crate::retry::Retryability::Retry {
                return Err(shaped);
            }
            if round.text.is_empty() {
                if stream_retries >= d.retry.max_retries {
                    return Err(shaped);
                }
                stream_retries += 1;
                let delay = d.retry.delay_for(stream_retries);
                print_retry_indicator(stream_retries, d.retry.max_retries, delay, &shaped, d.color);
                tokio::time::sleep(delay).await;
                continue;
            }
            print_harness_notice(
                &format!("stream broke mid-response ({err}) — keeping the partial answer"),
                d.color,
            );
            return Ok(Some((round, started)));
        }
        return Ok(Some((round, started)));
    }
}

/// Final tools-disabled completion for the Anthropic (`/v1/messages`) path.
///
/// `messages` is the already-trimmed list (caller uses `trim_for_summary`).
/// `accumulated` carries usage from the preceding tool-call rounds. Mirrors
/// [`final_summary_openai`]: cap-exit nudge appended, same preflight, and
/// `stream:false` with NO tools advertised so the model cannot emit tool_use.
#[allow(clippy::too_many_arguments)]
async fn final_summary_anthropic(
    client: &reqwest::Client,
    messages_url: &str,
    model: &str,
    api_key: Option<&str>,
    mut messages: Vec<serde_json::Value>,
    generation_policy: generation_policy::GenerationPolicy,
    cap: &CapExit,
    attempts: Option<attempt_capture::AttemptScope<'_>>,
) -> anyhow::Result<(FinalReply, bool, Option<crate::TokenUsage>)> {
    cap.push_nudge(&mut messages);
    let (system, wire_messages) = anthropic_wire::anthropic_wire_messages(&messages)?;
    if !cap.fits(&wire_messages, model) {
        return Ok(cap.fallback());
    }
    // Omit `tools` => the model cannot emit tool_use blocks (mirrors the
    // OpenAI path's tools-disabled summary).
    let body = anthropic_wire::build_messages_body(
        model,
        generation_policy
            .output_allowance
            .unwrap_or_else(anthropic_wire::default_max_tokens),
        system.as_deref(),
        &wire_messages,
        None,
        false,
    );
    cap.finish(
        messages_url,
        attempts,
        || async { Ok(anthropic_headers(client.post(messages_url), api_key).json(&body)) },
        "inference endpoint",
        estimate_value_tokens(&body, cap.estimation),
        |json| {
            // This wire separates thinking natively; text needs no split_reasoning.
            let reply = anthropic_wire::parse_messages_reply(&json);
            (reply.text, reply.usage)
        },
    )
    .await
}

async fn anthropic_chat_complete_with_prompt_and_artifacts(
    ctx: ChatCtx<'_>,
    turn_prompt_context: Option<&crate::TurnPromptContext>,
    prompt_source: Option<&dyn PromptSource>,
    artifact_source: Option<&dyn artifact_read::ArtifactSource>,
    artifact_sink: Option<&dyn artifact_read::PromptArtifactSink>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    let ChatCtx {
        shell_dialect,
        command_budget,
        verify_outcomes,
        smart_harness,
        url,
        model,
        kind: _,
        api_key,
        messages: mem_messages,
        task,
        workspace,
        default_command_cwd,
        worktree_session,
        color,
        // Like the OpenAI-compatible path, this loop streams natively —
        // the caller-resolved markdown decision drives the live writer.
        markdown,
        tool_offload,
        spill_store,
        disclosure,
        compaction_store,
        scratchpad,
        scratchpad_store,
        code_search,
        where_is,
        nav,
        exposure,
        experience_store,
        step_ledger,
        caveats,
        persona_tools,
        // Resolved into a local generation policy like the OpenAI path; only
        // the output cap projects onto this wire today (see below).
        cognition,
        output_allowance,
        overflow_retry: _,
        attempt_ledger,
        chat_completions_capability,
        responses_capability: _,
        openai_api: _,
        reasoning_replay_scope,
        max_tool_rounds,
        workflow_grace_rounds,
        narration_nudge_cap,
        action_nudges,
        prompt_disposition,
        prompt_intake,
        tool_output_lines,
        debug,
        trace,
        num_ctx,
        connect_timeout_secs,
        inference_timeout_secs,
        mid_loop_trim_threshold,
        compaction_trigger_policy,
        mid_loop_trim_tokens,
        max_ok_input,
        build_check_cmd,
        safe_context,
        recover_cw_400,
        mut note_sink,
        mut note_nudge,
        recall_source,
        memory_source,
        summarizer,
        compress_state,
        mut tool_events,
        mut phantom_reaches,
        mut end_reason,
        mut round_cap_hit,
        mut solve_obs,
        mut permission_gate,
        mut on_round_usage,
        estimate_ratio,
        estimation,
        summary_input_cap_floor_chars,
        rewrites_history,
        input_ceiling_pct,
        low_budget_pct,
        exec_floor,
        write_ledger,
        attribution,
        cancel,
        run_allowance,
        live_tool_output,
        git_tool,
        crew_runner,
        operating_mode_control,
        plan_mode_control,
        plan_draft_sink,
        steering,
        completed_spill_renderer,
        // Anthropic streams reasoning in its own wire fields, not as a lone
        // leading `</think>` closer, so this loop never starts the filter
        // inside a reasoning block. Bound and ignored rather than dropped
        // from the pattern, so adding a field to ChatCtx keeps failing here
        // until someone decides what it means for this wire.
        emits_leading_reasoning: _,
    } = ctx;
    // Any completed viewport this turn paints must not outlive the turn's
    // bookkeeping: on EVERY exit (return, `?`, cancel, panic) the guard
    // discards it — without terminal writes — so a stale rewind can never
    // replay over a later turn's prompt.
    let _completed_spill_guard = CompletedSpillDismissGuard(&completed_spill_renderer);
    // See the Ollama path: a non-Act turn is allowed bounded reads but never
    // execution-pressure nudges. (Mirrors the OpenAI path.)
    let action_nudges = action_nudges && prompt_disposition == PromptDisposition::Act;
    if let Some(harness) = smart_harness {
        harness.start_turn()?;
    }
    // Smart mode retains full tool output before the existing shell cap runs.
    let spill_store = smart_harness.map(|h| h.spill_store()).or(spill_store);
    let tool_offload = tool_offload || smart_harness.is_some();
    let smart_verify = action_nudges && prompt_disposition == PromptDisposition::Act;
    let action_nudges = action_nudges && smart_harness.is_none();
    let max_tool_rounds = prompt_disposition.tool_round_limit(max_tool_rounds);
    let generation_policy = generation_policy::GenerationPolicy::resolve(
        cognition,
        output_allowance,
        chat_completions_capability,
        reasoning_replay_scope,
    );
    let reasoning_replay_scope = generation_policy.reasoning_replay_scope;
    // Wire projection: the OpenAI path injects the resolved policy via
    // `apply_to_chat_completions_body`; this wire takes only the REQUIRED
    // `max_tokens` today. The request-shaping fields below are deliberately
    // unused — the thinking/effort (and sampling) mapping onto /v1/messages
    // is a declared follow-up — bound to `_` so the gap stays visible. (The
    // output cap, replay scope, and continuation opt-in are read off
    // `generation_policy` where the OpenAI path reads them.)
    let generation_policy::GenerationPolicy {
        thinking: _,
        reasoning_effort: _,
        temperature: _,
        top_p: _,
        parallel_tool_calls: _,
        chat_template_kwargs: _,
        max_output_tokens: _,
        output_allowance: _,
        reasoning_replay_scope: _,
        one_bounded_reasoning_continuation: _,
    } = generation_policy;
    // #2312 tiers: explicit allowance > cognition table > wire default
    // (`NEWT_ANTHROPIC_MAX_TOKENS`, else 8192). `max_tokens` is REQUIRED on this
    // wire, so the resolved allowance is always a declared field here.
    // Known discrepancy (pre-existing, unchanged): with no allowance the local
    // ceiling below reserves nothing while the wire default is sent.
    let max_tokens = generation_policy
        .output_allowance
        .unwrap_or_else(anthropic_wire::default_max_tokens);
    observability::observe_output_allowance(&mut solve_obs, Some(max_tokens), true);
    // Streaming valve: default ON; `NEWT_ANTHROPIC_STREAM=off` disables SSE.
    // Read once per loop invocation so a mid-turn flip cannot tear a round.
    let streaming_enabled = smart_harness.is_none()
        && !std::env::var("NEWT_ANTHROPIC_STREAM")
            .is_ok_and(|v| v.trim().eq_ignore_ascii_case("off"));
    // Headless callers may pass no session state (mirrors the OpenAI path).
    let mut local_compress_state = CompressState::new();
    let compress_state = match compress_state {
        Some(s) => s,
        None => &mut local_compress_state,
    };
    let client = reqwest::Client::builder()
        .connect_timeout(std::time::Duration::from_secs(connect_timeout_secs))
        .timeout(std::time::Duration::from_secs(inference_timeout_secs))
        .build()?;
    // See the Ollama path's #643 rationale: the streaming client uses an IDLE
    // `read_timeout` (caps the gap between chunks, resets on every token) so
    // a slow-but-progressing stream is never aborted mid-flight.
    let stream_client = reqwest::Client::builder()
        .connect_timeout(std::time::Duration::from_secs(connect_timeout_secs))
        .read_timeout(std::time::Duration::from_secs(inference_timeout_secs))
        .build()?;
    let messages_url = anthropic_wire::messages_url(url);
    let retry = tui_retry_policy(url);
    let dispatcher = AnthropicDispatch {
        defer_answer: true,
        smart_harness,
        client: &client,
        stream_client: &stream_client,
        messages_url: &messages_url,
        api_key,
        retry: &retry,
        color,
        markdown,
        retain: completed_spill_renderer.as_ref(),
    };
    // Tool advertisement gating — mirrors the OpenAI path.
    let advertise_save_note = note_sink.is_some();
    let advertise_recall = recall_source.is_some();
    let advertise_memory_fetch = memory_source.is_some();
    let advertise_scratchpad = scratchpad_store.is_some() && scratchpad;
    let advertise_code_search = code_search.is_some();
    let advertise_experiential = experience_store.is_some();
    let advertise_scheduled = step_ledger.is_some();
    // Native Git is the default interface; the injected adapter remains internal.
    let advertise_git = false;
    let advertise_team = crew_runner.is_some();
    let advertise_operating_mode = operating_mode_control.is_some();
    let advertise_plan_mode = plan_mode_control.is_some();
    let advertise_plan_mode_active =
        plan_mode_control.is_some_and(|control| control.is_plan_mode());

    let mem_messages = observed_report::replay_messages(mem_messages);
    let mut messages: Vec<serde_json::Value> = mem_messages
        .iter()
        .map(|m| {
            let content = if m.role == crate::Role::Assistant
                && reasoning_replay_scope != crate::model_card::ReasoningReplayScope::FullHistory
            {
                crate::reasoning::split_reasoning(&m.content).0
            } else {
                m.content.clone()
            };
            serde_json::json!({"role": m.role.as_str(), "content": content})
        })
        .collect();
    if let Some(harness) = smart_harness {
        messages = harness.initial_messages(messages)?;
    }
    if let (Some(session), Some(context)) = (worktree_session, turn_prompt_context) {
        session
            .report
            .lock()
            .expect("report state")
            .begin(context.active().root_prompt_id());
    }
    let ephemeral_prompt = prompt_read::headless_prompt_fallback(turn_prompt_context, task);
    let turn_prompt_context = turn_prompt_context.or(ephemeral_prompt.as_ref());
    let prompt_context =
        prompt_read::PromptReadContext::new(turn_prompt_context, task, prompt_source);
    let artifact_context = turn_prompt_context
        .map(|turn| artifact_read::ArtifactReadContext::from_turn(turn, artifact_source));
    let active_task = prompt_context.active_text();
    prompt_read::ensure_active_prompt_card(&mut messages, prompt_context, prompt_intake);
    // #2313: one ledger attempt per primary request, keyed at the send.
    let attempt_turn = turn_prompt_context
        .map(|turn| turn.active_operator_prompt().id().to_string())
        .unwrap_or_default();
    // An explicit inference budget applies even without an audit sink.
    let fallback_ledger = std::sync::Mutex::new(crate::attempts::AttemptLedger::default());
    let attempt_ledger = attempt_ledger.or_else(|| run_allowance.map(|_| &fallback_ledger));
    let attempts = attempt_ledger.map(|ledger| attempt_capture::AttemptScope {
        ledger,
        turn: &attempt_turn,
        model,
        backend: url,
        cancel,
        run_allowance,
    });

    // In-band memory nudge (Step 19.3) — mirrors the OpenAI path.
    if note_sink.is_some() {
        if let Some(line) = note_nudge.as_deref_mut().and_then(NoteNudge::begin_turn) {
            if let Some(harness) = smart_harness {
                harness.host_message(&line)?;
                messages.push(serde_json::json!({"role":"user", "content":line}));
            } else {
                append_nudge_line(&mut messages, &line);
            }
        }
    }

    let mut accumulated_usage: Option<crate::TokenUsage> = None;
    let mut hallucination_count: u32 = 0;
    // Step 27.3/#771: guard against exact-repeat tool loops this run.
    // #2315: result-aware verification for this turn, decided once.
    let result_aware = self_verify::enabled() && verify_outcomes;
    let mut repeat_calls = RepeatCallGuard::default();
    // Plan-before-act: the ledger as this turn began (see `PlanRoundFacts`).
    let plan_at_turn_start = step_ledger
        .map(|ledger| ledger.snapshot())
        .unwrap_or_default();
    let mut read_history = tools::ReadHistory::default();
    // #2315: what each check actually did, fed at the per-tool-result funnel.
    let mut verification = self_verify::VerificationLedger::for_turn(task, result_aware);
    // #2683: HEAD before this turn's own tool calls run, so a "committed"
    // claim in the final report can be checked against whether HEAD actually
    // moved. `None` (off-repo, or the read scope refuses the probe) must
    // never manufacture a false refutation — see `claim_check::TurnGitEvidence`.
    let turn_claims =
        claim_check::TurnClaims::capture(workspace, &caveats.fs_read, worktree_session)
            .with_evidence(observed_report::review::Evidence {
                sink: artifact_sink,
                context: artifact_context,
                spill: spill_store,
            });
    // #1948: DETECTION beside the guard — it notices a clean-then-build
    // loop and says so once; it never blocks or rewrites the call.
    let mut clean_build = crate::loop_watch::CleanBuildWatch::default();
    // At most one reasoning-only length-stop continuation per user turn
    // (mirrors the OpenAI path; the length stop is `max_tokens` here).
    let mut reasoning_continuation_attempted = false;
    let mut reasoning_overflow_signal_index: Option<usize> = None;
    // `pause_turn` re-dispatches the same history at most once per turn.
    let mut pause_turn_retried = false;
    // Consecutive context-window recoveries (parse limit → trim → retry).
    let mut cw_retries: u32 = 0;
    let mut output_recovery = output_limit_recovery::Recovery::default();
    // No-tools recovery (mirrors the OpenAI path): real Anthropic never
    // rejects `tools`, but façades might; drop tools and retry, notice once.
    let mut tools_supported = true;
    let mut tools_unsupported_notified = false;
    // Pre-send token budget gate — mirrors the OpenAI path (`num_ctx` is not
    // sent on this wire, but an operator-declared local window still caps
    // Newt's input budget). #2341: reserve exactly the `max_tokens` sent.
    let mut effective_input_ceiling =
        num_ctx_input_ceiling(num_ctx, input_ceiling_pct, Some(max_tokens));
    let mut send_budget: Option<usize> =
        initial_send_budget(max_ok_input, safe_context, effective_input_ceiling);
    let mut send_budget_authoritative = safe_context.is_some() || effective_input_ceiling.is_some();
    // Tool schemas ride along in every request body; count them once (18.1).
    let tools = merged_tool_definitions(
        mcp,
        advertise_save_note,
        advertise_recall,
        advertise_memory_fetch,
        advertise_git.then_some(&caveats.fs_read),
        advertise_team,
        advertise_scratchpad,
        advertise_code_search,
        advertise_experiential,
        advertise_scheduled,
        advertise_operating_mode,
        advertise_plan_mode,
        advertise_plan_mode_active,
        command_budget,
        shell_dialect,
    );
    let tools = filter_advertised_tools(tools, persona_tools);
    let tools = filter_tools_for_disposition(
        smart_harness::advertise(tools, smart_harness),
        prompt_disposition,
    );
    // #TEC Pass 1: exposure stage — mirrors the OpenAI path.
    let (mut tools, hidden_tools) = crate::agentic::tools::select_exposed(
        tools,
        &exposure,
        exposure_budget_tokens(send_budget, safe_context),
        &std::collections::BTreeSet::new(),
        estimation,
    );
    // The Anthropic tool catalog, converted from the exposed catalog
    // (`input_schema` copied wholesale, no `function` nesting), and again only
    // when a hidden tool is promoted.
    let mut tools_anthropic = anthropic_wire::tools_to_anthropic(&tools);
    let mut tool_tokens = estimate_value_tokens(&tools, estimation);
    // Phase 20 §2.3: per-turn calibration ratio + real-token schema overhead
    // (mirrors the OpenAI path).
    let mut cal = compress_state.calibration.ratio(estimate_ratio);
    let mut tool_tokens_real = calibrate_up(tool_tokens, cal);
    preflight_irreducible_request(
        &messages,
        Some(&tools),
        authoritative_request_budget(send_budget, send_budget_authoritative, mid_loop_trim_tokens),
        cal,
        estimation,
        model,
    )?;
    // Truthful context-size tracker (prompt-tokens-preferred, Step 18.1).
    let mut prompt_tracker = PromptTracker::new();
    let today = chrono::Local::now().format("%Y-%m-%d").to_string();

    // #867 Part A: observed-paths ledger (mirrors the OpenAI path).
    let mut observed_paths = claim_check::ObservedPaths::default();
    let mut observed_resolver = claim_check::workspace_resolver(workspace);

    // Narrate-then-stop rescue counter (mirrors the OpenAI path).
    let mut narration_nudges: usize = 0;
    let mut readonly_completion_retried = false;
    // Self-verify gate (#23) — mirrors the OpenAI path.
    let mut self_verify_nudges: usize = 0;
    let mut verification_nudges: usize = 0;
    const SELF_VERIFY_CAP: usize = 2;
    // Pending-plan final-answer gate counter (mirrors the OpenAI path).
    let mut pending_plan_nudges: usize = 0;
    // Unverified stale-file blocker rescue counter (mirrors the OpenAI path).
    let mut stale_file_nudges: usize = 0;
    let mut unverified_exec_blocker_nudges: usize = 0;
    let mut run_command_denial_observed = false;
    // #2628: see the primary loop declaration above for the invariant.
    let mut pending_rerun: Option<tools::PendingRerun> = None;
    let mut capability_evidence = capability_check::Evidence::default();
    let mut probe_correction_used = false;
    let nudge_classifier = crate::NudgeClassifier::load_default();
    // #1152/#1162: same intent gate as the primary loop.
    let action_turn = action_nudges && crate::classifiers::user_turn_invites_action(active_task);
    let exec_grounding_turn = action_nudges && prompt_disposition == PromptDisposition::Act;
    let workflow_steerer = crate::WorkflowSteerer::load_default();
    let mut workflow_runtime = WorkflowRuntimeState {
        initiative: crate::initiative::effective_initiative(),
        no_progress: crate::initiative::installed_no_progress(),
        ..Default::default()
    };
    // See the OpenAI path: a matching workflow's grace-horizon override.
    workflow_runtime.set_progress_horizon(
        workflow_steerer.progress_horizon(&workflow_classifier_text(&messages, "")),
    );

    // Same progress-backed renewable allowance as the other providers.
    let mut current_tool_round_limit = max_tool_rounds;
    // #1965: the turn's only whole-turn wall-clock signal. The evidenced
    // 32-minute turn emitted none — this file has per-tool `Instant` timers
    // and nothing watching the turn as a whole.
    let turn_started = std::time::Instant::now();
    let mut turn_heartbeat = TurnHeartbeat::default();
    let mut uncorrelatable_batches: u32 = 0;
    let mut selected_source = selected_target::Projection::default();
    let mut observed_facts = semantic_pins::Projection::default();
    'round_loop: for round in 0..usize::MAX {
        let round = round.saturating_sub(output_recovery.skipped_rounds);
        selected_source.refresh(
            &mut messages,
            step_ledger,
            workspace,
            &caveats.fs_read,
            worktree_session,
            false,
        );
        observed_facts.planning = output_budget::guidance(
            Some(max_tokens),
            step_ledger,
            &selected_target::root(workspace, worktree_session),
            &caveats.fs_read,
            estimation,
        );
        semantic_pins::refresh(
            &mut observed_facts,
            smart_harness,
            &mut messages,
            prompt_context,
            selected_source.current(),
            &turn_claims,
            workspace,
            &caveats.fs_read,
        )?;
        // #2331: a call to an authorized tool whose schema was off the wire
        // promoted it; its schema rides every request from here on.
        if hidden_tools.append_promoted(&mut tools) {
            tools_anthropic = anthropic_wire::tools_to_anthropic(&tools);
            tool_tokens = estimate_value_tokens(&tools, estimation);
            tool_tokens_real = calibrate_up(tool_tokens, cal);
        }
        // Bounded to ONE line per interval, and the policy is pure over the
        // elapsed it is handed — this reads the clock, `due` does not.
        let turn_elapsed = turn_started.elapsed();
        if let Some(line) = turn_heartbeat.notice(turn_elapsed, round, current_tool_round_limit) {
            print_newt(&line, color, false);
        }
        // FIRST statement of every round: the previous round's completed
        // viewport must come down before ANY canonical line this round can
        // print — the grace-window debug note, the round separator, the
        // compression notices, the cancel checkpoint's return to a caller
        // that prints. Erasing here is safe precisely because nothing has
        // written since the frame was painted.
        dismiss_completed_spill(&completed_spill_renderer);
        if !workflow_runtime.admit_round(
            round,
            &mut current_tool_round_limit,
            workflow_grace_rounds,
        ) {
            break;
        }
        // Interrupt checkpoint (Esc / Ctrl-C) — mirrors the OpenAI path.
        if is_cancelled(cancel) {
            return Ok((
                smart_harness::cancelled(smart_harness, &mut end_reason)?,
                false,
                accumulated_usage,
                hallucination_count,
            ));
        }
        // #952/#1669: operator steering, delivered BEFORE this round's model
        // call and AFTER any tool that was already running finished above.
        // Steering changes what the agent does NEXT; it never abandons the
        // turn (that is `cancel`, checked immediately above).
        if drain_steering_into(steering, &mut messages, color) > 0 {
            workflow_runtime.note_operator_steering();
        }
        if round > 0 && color {
            execute!(
                io::stdout(),
                SetForegroundColor(CtColor::DarkGrey),
                Print("…\n"),
                ResetColor
            )
            .ok();
        }

        // Conditional plan re-seat (#630 b) — mirrors the OpenAI path.
        // U4b: the brake's gate runs EVERY round, outside the nudge gate: nudges may
        // be off, a bound may not (only the steer honours `action_nudges`).
        if round > 0 {
            no_progress_gate!(
                workflow_runtime,
                action_nudges,
                messages,
                end_reason,
                solve_obs,
                accumulated_usage,
                hallucination_count,
                smart_harness,
                (
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification
                ),
                |harness| harness.record_messages(&messages)?
            );
        }
        if round > 0 && action_nudges {
            if let Some(ptr) = step_ledger.and_then(plan_reseat_pointer) {
                messages.push(serde_json::json!({ "role": "user", "content": ptr }));
            }
            // Initiative action-forcing — mirrors the OpenAI path.
            let remaining = (workflow_grace_rounds == 0)
                .then_some(current_tool_round_limit.saturating_sub(round + 1));
            if let Some(nudge) = workflow_runtime.action_forcing_nudge(remaining, step_ledger, None)
            {
                if debug {
                    print_debug(
                        &format!(
                            "initiative[{}]: forcing action, read-only budget spent (round {round})",
                            workflow_runtime.initiative
                        ),
                        color,
                    );
                }
                messages.push(serde_json::json!({ "role": "user", "content": nudge }));
            }
        }

        // Context compression (Step 18.4, #247) — mirrors the OpenAI path:
        // the shared prune → boundary → redacted summary → marker pipeline
        // serves the mid-loop trigger and the pre-send budget guard.
        {
            let advertised_tools = tools_supported.then_some(&tools);
            let (_, wire_messages) = anthropic_wire::anthropic_wire_messages(&messages)?;
            let current = full_message_request_pressure_tokens(
                prompt_tracker.current(&messages, advertised_tools, cal, estimation),
                &wire_messages,
                advertised_tools,
                cal,
                estimation,
            );
            let message_tokens = estimate_tokens(&messages, estimation);
            let has_authoritative_headroom = count_guard_has_headroom(
                current,
                authoritative_request_budget(
                    send_budget,
                    send_budget_authoritative,
                    mid_loop_trim_tokens,
                ),
                max_ok_input,
            );
            let reasoning_tail_len =
                compress::protected_reasoning_tail_len(&messages, reasoning_replay_scope);
            if let Some(trigger) = compression_trigger(
                compress::compression_message_count(&messages, reasoning_tail_len),
                current,
                message_tokens,
                CompressionTriggerLimits {
                    count_threshold: mid_loop_trim_threshold,
                    token_threshold: mid_loop_trim_tokens,
                    send_budget,
                    tool_tokens: tool_tokens_real,
                    policy: compaction_trigger_policy,
                    has_authoritative_headroom,
                },
            ) {
                let pipeline_budget = if trigger.hard_budget {
                    calibrate_down(trigger.budget, cal)
                } else {
                    trigger.budget
                };
                let token_fired = mid_loop_trim_tokens.is_some_and(|t| t > 0 && current > t);
                let compression = smart_harness::compress(
                    CompressRequest {
                        messages: &messages,
                        budget: pipeline_budget,
                        max_messages: if reasoning_tail_len > 0 {
                            None
                        } else {
                            trigger.max_messages
                        },
                        replay_protected_tail_len: reasoning_tail_len,
                        task: active_task,
                        hard_budget: trigger.hard_budget,
                        authoritative: token_fired || send_budget_authoritative,
                        focus: None,
                        est: estimation,
                        summary_input_cap_floor_chars,
                        rewrites_history,
                        compaction_store,
                        compaction_stage: None,
                    },
                    summarizer,
                    compress_state,
                    smart_harness,
                );
                let Some(outcome) = cancellable(cancel, compression).await else {
                    return Ok((
                        smart_harness::cancelled(smart_harness, &mut end_reason)?,
                        false,
                        accumulated_usage,
                        hallucination_count,
                    ));
                };
                let outcome = outcome?;
                if let Some(notice) = outcome.notice {
                    print_harness_notice(&notice, color);
                }
                if outcome.action == CompressAction::Refused {
                    anyhow::bail!("{}", refusal_bail_message(outcome.refusal, current, model));
                }
                if outcome.fired {
                    let suffix = if trigger.hard_budget && outcome.tokens_after > pipeline_budget {
                        ", still over budget"
                    } else {
                        ""
                    };
                    emit_compression_notice(
                        color,
                        outcome.tokens_before,
                        outcome.tokens_after,
                        outcome.action,
                        suffix,
                    );
                    if debug {
                        print_debug(
                            &format!(
                                "compression: {} → {} messages (budget ~{} tokens, \
                                 +~{tool_tokens} tool-schema tokens ride along)",
                                messages.len(),
                                outcome.messages.len(),
                                pipeline_budget,
                            ),
                            color,
                        );
                    }
                    messages = outcome.messages;
                    prompt_tracker.invalidate();
                    apply_post_compaction_continuation(
                        worktree_session,
                        &mut messages,
                        &mut narration_nudges,
                        outcome.action,
                        step_ledger,
                        prompt_context,
                        round > 0 && action_nudges,
                        |candidate| {
                            anthropic_wire::anthropic_wire_messages(candidate).is_ok_and(
                                |(_, wire)| {
                                    preflight_full_message_request(
                                        &wire,
                                        tools_supported.then_some(&tools),
                                        authoritative_request_budget(
                                            send_budget,
                                            send_budget_authoritative,
                                            mid_loop_trim_tokens,
                                        ),
                                        cal,
                                        estimation,
                                        model,
                                    )
                                    .is_ok()
                                },
                            )
                        },
                    );
                    record_compaction_artifact(
                        &mut repeat_calls,
                        artifact_sink,
                        artifact_context,
                        outcome.action,
                        outcome.tokens_before,
                        outcome.tokens_after,
                        pipeline_budget,
                        round,
                        trigger.primary_cause.artifact_reason(),
                        Some(&trigger),
                        send_budget_authoritative,
                        compress_state.floor_trend(),
                        color,
                    );
                }
            }
        }

        // #1528: inner recovery loop — a cw-400 (or a tools-unsupported
        // error) retries THIS logical round IN PLACE (mirrors the OpenAI
        // path); a `pause_turn` stop re-dispatches the same history once.
        let (model_reply, printed_live, round_est_raw): (
            anthropic_wire::AnthropicRound,
            bool,
            usize,
        ) = loop {
            // Convert the internal transcript to the Anthropic wire at
            // dispatch only: leading system run → top-level `system`,
            // assistant `tool_calls` → `tool_use` blocks, `role:"tool"` runs
            // → ONE user message of `tool_result` blocks.
            if let Some(harness) = smart_harness {
                harness.record_messages(&messages)?;
            }
            let (system, wire_messages) = anthropic_wire::anthropic_wire_messages(&messages)?;

            // Mirror the OpenAI full-request gate.
            preflight_full_message_request(
                &wire_messages,
                tools_supported.then_some(&tools),
                authoritative_request_budget(
                    send_budget,
                    send_budget_authoritative,
                    mid_loop_trim_tokens,
                ),
                cal,
                estimation,
                model,
            )?;

            // Phase 20 §2.2: chars/4 estimate of exactly the request about to
            // be dispatched — mirrors the OpenAI path.
            let round_est_raw = estimate_request_tokens(
                &wire_messages,
                tools_supported.then_some(&tools),
                estimation,
            );

            let use_tools = tools_supported && !tools_anthropic.is_empty();
            let body = anthropic_wire::build_messages_body(
                model,
                max_tokens,
                system.as_deref(),
                &wire_messages,
                use_tools.then_some(tools_anthropic.as_slice()),
                streaming_enabled,
            );
            let dispatch = anthropic_dispatch_round(
                &dispatcher,
                &body,
                &messages,
                streaming_enabled,
                cancel,
                attempts,
            )
            .await;
            match dispatch {
                // Interrupted mid-dispatch: same contract as the round-
                // boundary checkpoint (mirrors the Ollama raced probe).
                Ok(None) => {
                    return Ok((
                        smart_harness::cancelled(smart_harness, &mut end_reason)?,
                        false,
                        accumulated_usage,
                        hallucination_count,
                    ))
                }
                Ok(Some((reply, printed))) => {
                    // A completed generation (including pause_turn) ends the
                    // rejection streak; tightened input limits remain in force.
                    cw_retries = 0;
                    // `pause_turn`: the server paused a long turn; re-dispatch
                    // the SAME history once — bounded so a façade that always
                    // pauses cannot spin the loop.
                    if reply.stop_reason.as_deref() == Some("pause_turn") && !pause_turn_retried {
                        pause_turn_retried = true;
                        // #2313: the paused reply generated tokens the turn pays for.
                        accumulated_usage = merge_round_usage(accumulated_usage, reply.usage);
                        if debug {
                            print_debug("pause_turn — re-dispatching the same history once", color);
                        }
                        continue;
                    }
                    break (reply, printed, round_est_raw);
                }
                Err(e) => {
                    // No-tools recovery (mirrors the OpenAI path): drop tools,
                    // notice once, and re-dispatch the same round.
                    if tools_supported && is_tools_unsupported_error(&e) {
                        tools_supported = false;
                        if !tools_unsupported_notified {
                            tools_unsupported_notified = true;
                            print_newt(
                                &format!(
                                "{model} does not support tools — tools disabled for this session"
                            ),
                                color,
                                false,
                            );
                        }
                        continue;
                    }
                    // Graceful context-window overflow recovery (mirrors the
                    // OpenAI path): Anthropic's "prompt is too long: N tokens
                    // > M maximum" 400 is parsed by the same shared hook;
                    // numberless overflows fall back to deriving a tightened
                    // cap from the current send budget.
                    let overflow = cw_overflow::is_context_overflow(&e.to_string());
                    // Record the rejected size BEFORE increasing estimation slack.
                    let refused_tokens = cw_overflow::parse_context_window_error(&e.to_string())
                        .map(|(tokens, _)| usize::try_from(tokens).unwrap_or(usize::MAX))
                        .unwrap_or_else(|| calibrate_up(round_est_raw, cal));
                    if overflow {
                        cal = compress_state.calibration.overflow(cal);
                        tool_tokens_real = calibrate_up(tool_tokens, cal);
                    }
                    if cw_retries < 2 {
                        let recovered_window = recover_cw_400.and_then(|f| f(&e, model, &today));
                        if let Some(recovered_budget) = recovered_window
                            .map(|context_window| {
                                recovered_input_budget(
                                    context_window,
                                    input_ceiling_pct,
                                    Some(max_tokens),
                                    effective_input_ceiling,
                                )
                            })
                            .or_else(|| {
                                cw_overflow::core_recover_overflow(
                                    &e.to_string(),
                                    send_budget,
                                    None,
                                )
                                .map(|cap| cap as usize)
                            })
                            .or_else(|| {
                                overflow.then_some(
                                    send_budget.unwrap_or_else(|| calibrate_up(round_est_raw, cal)),
                                )
                            })
                            .and_then(|budget| {
                                cw_overflow::recovery_target(
                                    budget,
                                    refused_tokens,
                                    effective_input_ceiling,
                                )
                            })
                        {
                            if let Some(context_window) = recovered_window {
                                emit_context_window_400(&mut on_round_usage, context_window);
                            }
                            let new_budget = effective_input_ceiling
                                .map_or(recovered_budget, |c| recovered_budget.min(c));
                            let new_budget = authoritative_request_budget(
                                Some(new_budget),
                                true,
                                mid_loop_trim_tokens,
                            )
                            .unwrap_or(new_budget);
                            emit_overflow_notice(
                                color,
                                &display::OverflowReason::Refused {
                                    request_estimate: Some(
                                        refused_tokens.min(u32::MAX as usize) as u32
                                    ),
                                    window: recovered_window,
                                    trim_to: new_budget.min(u32::MAX as usize) as u32,
                                },
                                model,
                                cw_retries + 1,
                            );
                            send_budget = Some(new_budget);
                            effective_input_ceiling = Some(new_budget);
                            send_budget_authoritative = true;
                            let compression = context_recovery::compress(
                                CompressRequest {
                                    messages: &messages,
                                    budget: context_recovery::target(
                                        &messages,
                                        calibrate_down(
                                            new_budget.saturating_sub(tool_tokens_real),
                                            cal,
                                        ),
                                        estimation,
                                    ),
                                    max_messages: None,
                                    replay_protected_tail_len:
                                        compress::protected_reasoning_tail_len(
                                            &messages,
                                            reasoning_replay_scope,
                                        )
                                        .max(context_recovery::protected_tool_tail(&messages)),
                                    task: active_task,
                                    hard_budget: true,
                                    authoritative: true,
                                    focus: None,
                                    est: estimation,
                                    summary_input_cap_floor_chars,
                                    rewrites_history,
                                    compaction_store,
                                    compaction_stage: None,
                                },
                                summarizer,
                                compress_state,
                                smart_harness,
                            );
                            let Some(outcome) = cancellable(cancel, compression).await else {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Ok((
                                    smart_harness::cancelled(smart_harness, &mut end_reason)?,
                                    false,
                                    accumulated_usage,
                                    hallucination_count,
                                ));
                            };
                            let outcome = match outcome {
                                Ok(outcome) => outcome,
                                Err(error) => {
                                    context_recovery::record(
                                        &mut solve_obs,
                                        smart_harness,
                                        round,
                                        cw_retries + 1,
                                        round_est_raw,
                                        None,
                                    )?;
                                    return Err(e.context(format!(
                                        "context re-projection failed: {error}"
                                    )));
                                }
                            };
                            if let Some(notice) = outcome.notice {
                                print_harness_notice(&notice, color);
                            }
                            if outcome.action == CompressAction::Refused
                                || !outcome.fired
                                || outcome.tokens_after >= outcome.tokens_before
                            {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Err(e);
                            }
                            if outcome.fired {
                                messages = outcome.messages;
                                prompt_tracker.invalidate();
                                apply_post_compaction_continuation(
                                    worktree_session,
                                    &mut messages,
                                    &mut narration_nudges,
                                    outcome.action,
                                    step_ledger,
                                    prompt_context,
                                    round > 0 && action_nudges,
                                    |candidate| {
                                        anthropic_wire::anthropic_wire_messages(candidate)
                                            .is_ok_and(|(_, wire)| {
                                                preflight_full_message_request(
                                                    &wire,
                                                    tools_supported.then_some(&tools),
                                                    authoritative_request_budget(
                                                        send_budget,
                                                        send_budget_authoritative,
                                                        mid_loop_trim_tokens,
                                                    ),
                                                    cal,
                                                    estimation,
                                                    model,
                                                )
                                                .is_ok()
                                            })
                                    },
                                );
                                record_compaction_artifact(
                                    &mut repeat_calls,
                                    artifact_sink,
                                    artifact_context,
                                    outcome.action,
                                    outcome.tokens_before,
                                    outcome.tokens_after,
                                    calibrate_down(
                                        new_budget.saturating_sub(tool_tokens_real),
                                        cal,
                                    ),
                                    round,
                                    "context_window_400",
                                    None,
                                    false,
                                    compress_state.floor_trend(),
                                    color,
                                );
                            }
                            let projected = estimate_request_tokens(
                                &messages,
                                tools_supported.then_some(&tools),
                                estimation,
                            );
                            if projected >= round_est_raw
                                || calibrate_up(projected, cal) > new_budget
                            {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Err(e);
                            }
                            context_recovery::record(
                                &mut solve_obs,
                                smart_harness,
                                round,
                                cw_retries + 1,
                                round_est_raw,
                                Some(calibrate_up(projected, cal)),
                            )?;
                            cw_retries += 1;
                            continue;
                        }
                    }
                    if overflow {
                        context_recovery::record(
                            &mut solve_obs,
                            smart_harness,
                            round,
                            cw_retries + 1,
                            round_est_raw,
                            None,
                        )?;
                    }
                    return Err(e);
                }
            }
        };
        // Merge per-round token usage (input = max single prompt, output =
        // sum — Step 18.1) and anchor the context-size tracker.
        let round_usage = model_reply.usage;
        if let Some(u) = round_usage {
            compress_state
                .calibration
                .observe(Some(u.input_tokens), round_est_raw);
            cal = compress_state.calibration.ratio(estimate_ratio);
            tool_tokens_real = calibrate_up(tool_tokens, cal);
            prompt_tracker.record(u.input_tokens, messages.len());
        }
        accumulated_usage = merge_round_usage(accumulated_usage, round_usage);

        // Phase 20 §2.2: no silent head-truncation mode on this wire either —
        // oversize requests get a parseable 400 (mirrors the OpenAI path).
        let truncation_suspect = false;
        if let (Some(u), Some(budget), false) = (round_usage, send_budget, truncation_suspect) {
            let raised = capped_accepted_prompt_tokens(u.input_tokens, effective_input_ceiling);
            if raised > budget {
                send_budget = Some(raised);
                if debug {
                    print_debug(
                        &format!(
                            "send budget raised to ~{raised} tokens (backend accepted \
                             {}-token prompt)",
                            u.input_tokens
                        ),
                        color,
                    );
                }
            }
        }

        if model_reply.stop_reason.as_deref() == Some("max_tokens") {
            if output_recovery.retry(
                !model_reply.tool_uses.is_empty() || model_reply.unfinished_tool_use,
                &mut messages,
                smart_harness,
            )? {
                continue;
            }
            let text = finalize_final_text(
                generation_bounds::output_limit_notice(model_reply.text, round_usage),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            if let Some(slot) = &mut end_reason {
                **slot = Some(crate::TurnEndReason::Failed);
            }
            if let Some(harness) = smart_harness {
                harness.outcome(crate::TurnEndReason::Failed, &text)?;
            }
            return Ok((text, false, accumulated_usage, hallucination_count));
        }

        // `refusal` stop semantics (this wire only): NOT a tool round, NOT an
        // error. The streamed/parsed text — if any — IS the answer; an empty
        // refusal gets an honest placeholder. No rescue nudges: nudging a
        // refusal toward action would fight the provider's decline.
        if model_reply.stop_reason.as_deref() == Some("refusal") {
            if !model_reply.text.is_empty() {
                emit_accepted(
                    &mut on_round_usage,
                    round_usage,
                    truncation_suspect,
                    round_est_raw,
                );
            }
            if let Some(slot) = &mut end_reason {
                **slot = Some(crate::TurnEndReason::Completed);
            }
            let streamed = printed_live && !model_reply.text.is_empty();
            if model_reply.text.is_empty() {
                let out =
                    FinalReply::harness("the model declined this request (refusal)".to_string());
                let out = finalize_final_text(
                    out,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                observability::observe_harness_reply(&mut solve_obs);
                return Ok((out, streamed, accumulated_usage, hallucination_count));
            }
            // #1964: this normal (non-cap) finish gets the same claim check
            // + disclosure gate as a cap-exit summary.
            let out = finalize_final_text(
                model_reply.text.clone(),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            // Finalization can append evidence warnings or redact content;
            // the live stream did not display that finalized answer.
            let streamed = streamed && out == model_reply.text;
            return Ok((out, streamed, accumulated_usage, hallucination_count));
        }

        // This wire separates thinking natively — `text` arrives clean, so
        // the OpenAI path's `split_reasoning` has no work to do here.
        let oa_content = model_reply.text.clone();
        let separate_reasoning = {
            let t = model_reply.thinking.trim();
            (!t.is_empty()).then_some(t)
        };
        if debug && separate_reasoning.is_some() {
            let n = separate_reasoning.map(str::len).unwrap_or(0);
            print_debug(
                &format!("reasoning ({n} chars) surfaced to the trace, not the answer"),
                color,
            );
        }
        let native_calls = (!model_reply.tool_uses.is_empty()).then_some(&model_reply.tool_uses);
        // Recover tool calls emitted as content instead of native tool_use —
        // mirrors the OpenAI path: real Anthropic emits native blocks, but a
        // weak model behind a façade can drop content-emitted calls too.
        let mut recovered = if native_calls.is_none() {
            tool_recovery::recover_tool_calls(&oa_content)
        } else {
            tool_recovery::Recovery::default()
        };
        let recovered_identities = tool_recovery::assign_ids(
            &mut recovered,
            attempt_ledger.and_then(|l| l.lock().ok().and_then(|l| l.latest_primary())),
        );
        let tool_calls: Option<&Vec<serde_json::Value>> = match native_calls {
            Some(t) => Some(t),
            _ if !recovered.calls.is_empty() => Some(&recovered.calls),
            _ => None,
        };
        let has_tools = tool_calls.map(|tc| !tc.is_empty()).unwrap_or(false);
        // `stop_reason` plays the OpenAI `finish_reason` role from here on.
        let finish_reason = model_reply.stop_reason.as_deref();
        if let Some(obs) = solve_obs.as_deref_mut() {
            obs.behavior_signals
                .push(observability::BehaviorSignal::ChatCompletionFinish {
                    round,
                    finish_reason: finish_reason.map(str::to_string),
                });
        }
        let reasoning_text = separate_reasoning;
        // Mirrors the OpenAI path's `reasoning_overflow_signature`, with the
        // condition adapted to this wire's length stop: `max_tokens` with no
        // visible text but non-empty thinking and no executable call.
        let reasoning_overflow = finish_reason == Some("max_tokens")
            && oa_content.is_empty()
            && reasoning_text.is_some()
            && !has_tools;

        // Resolve the pending telemetry record on the first response after a
        // continuation (mirrors the OpenAI path).
        if reasoning_continuation_attempted && !reasoning_overflow {
            if has_tools || !oa_content.is_empty() {
                if let (Some(obs), Some(index)) =
                    (solve_obs.as_deref_mut(), reasoning_overflow_signal_index)
                {
                    if let Some(signal) = obs.behavior_signals.get_mut(index) {
                        signal.mark_continuation_succeeded();
                    }
                }
            }
            reasoning_overflow_signal_index = None;
        }

        if reasoning_overflow {
            let has_round_budget = workflow_runtime.has_next_round(
                round,
                current_tool_round_limit,
                workflow_grace_rounds,
            );
            let can_continue = generation_policy
                .allows_reasoning_continuation(reasoning_continuation_attempted, has_round_budget);

            let resolving_existing_continuation =
                reasoning_continuation_attempted && reasoning_overflow_signal_index.is_some();
            if !resolving_existing_continuation {
                if let Some(obs) = solve_obs.as_deref_mut() {
                    let index = obs.behavior_signals.len();
                    obs.behavior_signals
                        .push(observability::BehaviorSignal::ReasoningOverflow {
                            round,
                            reasoning_overflow_detected: true,
                            continuation_attempted: can_continue,
                            continuation_succeeded: false,
                            finish_reason: "max_tokens".into(),
                            reasoning_tokens_estimate: estimation.tokens_for_chars(
                                reasoning_text
                                    .map(|reasoning| reasoning.chars().count())
                                    .unwrap_or(0),
                            ),
                        });
                    reasoning_overflow_signal_index = Some(index);
                }
            }

            if can_continue {
                print_newt(
                    "reasoning reached the output limit before an answer — continuing once",
                    color,
                    false,
                );
                // Thinking replay onto this wire is a follow-up; the bounded
                // continuation replays the (empty) visible text only, which
                // the wire conversion drops — the re-dispatch is the same
                // history plus one more attempt (mirrors the OpenAI path's
                // structure).
                messages.push(serde_json::json!({
                    "role": "assistant",
                    "content": oa_content,
                }));
                reasoning_continuation_attempted = true;
                continue 'round_loop;
            }

            let reason = if resolving_existing_continuation {
                "the bounded continuation also reached the output limit"
            } else if reasoning_continuation_attempted {
                "the turn already used its bounded continuation"
            } else if !generation_policy.one_bounded_reasoning_continuation {
                "the endpoint does not advertise bounded continuation"
            } else if reasoning_replay_scope == crate::model_card::ReasoningReplayScope::Never {
                "the endpoint does not allow current-turn reasoning replay"
            } else {
                "the turn has no remaining round budget"
            };
            print_newt(
                &format!("reasoning overflow detected — {reason}"),
                color,
                false,
            );
        }
        // W0 (#1511): served-model + parse-status observation — mirrors the
        // OpenAI path.
        if let Some(obs) = solve_obs.as_deref_mut() {
            if let Some(m) = model_reply.model.as_deref().filter(|m| !m.is_empty()) {
                obs.served_model = Some(m.to_string());
            }
            let native = native_calls.is_some();
            if let Some(sig) = observability::round_parse_signal(
                round,
                !oa_content.is_empty(),
                native,
                recovered.dialect,
                recovered_identities.clone(),
            ) {
                obs.parse_signals.push(sig);
            }
        }
        if debug && !recovered.calls.is_empty() {
            print_debug(
                &format!(
                    "recovered {} tool call(s) from content (non-native emission)",
                    recovered.calls.len()
                ),
                color,
            );
        }

        if debug {
            let excerpt: String = oa_content.chars().take(80).collect();
            let tc_count = tool_calls.map(|tc| tc.len()).unwrap_or(0);
            let usage_str = match round_usage {
                Some(u) => format!("{} in / {} out", u.input_tokens, u.output_tokens),
                None => "no usage".into(),
            };
            print_debug(
                &format!(
                    "round {round}: tool_calls={tc_count} usage=[{usage_str}] content={excerpt:?}"
                ),
                color,
            );
        }

        if !has_tools {
            if let Some(mut nudge) = capability_evidence.correction(
                &oa_content,
                &tools,
                &mut probe_correction_used,
                tools_supported
                    && workflow_runtime.has_next_round(
                        round,
                        current_tool_round_limit,
                        workflow_grace_rounds,
                    )
                    && !is_cancelled(cancel),
            ) {
                if let Some(harness) = smart_harness {
                    nudge = harness.correct_answer(&oa_content, &nudge)?;
                }
                messages.push(serde_json::json!({"role":"assistant", "content":oa_content}));
                messages.push(serde_json::json!({"role":"user", "content":nudge}));
                continue 'round_loop;
            }
            if let Some(harness) = smart_harness {
                let more = workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                );
                let control = harness
                    .classify(&oa_content, narration_nudge_cap, more, cancel)
                    .await?;
                let control = harness
                    .verify_answer(
                        control,
                        self_verify::Concluding {
                            messages: &messages,
                            workspace,
                            task,
                            rounds_left: more,
                            round,
                            ledger: &verification,
                            solve_obs: solve_obs.as_deref_mut(),
                        },
                        smart_verify,
                        &oa_content,
                    )
                    .await?;
                let (text, reason) = match control {
                    smart_harness::Control::Continue(nudge) => {
                        messages
                            .push(serde_json::json!({"role":"assistant", "content":oa_content}));
                        messages.push(serde_json::json!({"role":"user", "content":nudge}));
                        continue 'round_loop;
                    }
                    smart_harness::Control::Answer => (
                        FinalReply::from(oa_content.clone()),
                        crate::TurnEndReason::Completed,
                    ),
                    smart_harness::Control::Finish { text, reason } => (text, reason),
                };
                if let Some(slot) = &mut end_reason {
                    **slot = Some(reason);
                }
                let text = finalize_final_text(
                    text,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                harness.outcome(reason, &text)?;
                return Ok((text, false, accumulated_usage, hallucination_count));
            }

            // Format-hallucination tracker (mirrors the OpenAI path).
            if recovered.tool_shaped {
                hallucination_count += 1;
                if debug {
                    print_debug(
                        "format-hallucination: tool call emitted as unrecoverable text",
                        color,
                    );
                }
            }
            let content = oa_content.clone();
            if !is_cancelled(cancel)
                && readonly_completion_pending(prompt_disposition, &nudge_classifier, &content)
            {
                let more_rounds = workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                );
                if retry_readonly_completion(
                    &mut messages,
                    &content,
                    None,
                    &mut readonly_completion_retried,
                    more_rounds,
                ) {
                    continue 'round_loop;
                }
                let out = readonly_completion_handoff(
                    &content,
                    &mut end_reason,
                    more_rounds,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                return Ok((out, false, accumulated_usage, hallucination_count));
            }
            if content.is_empty() && debug {
                print_debug(
                    "empty content with no tool calls — model produced nothing",
                    color,
                );
            }
            // Narrate-then-stop rescue and its siblings — mirror the OpenAI
            // path. A superseded streamed round re-prints on the next round
            // (accepted UX; no re-print suppression).
            let nudge_classification =
                (!content.is_empty()).then(|| nudge_classifier.classify(&content));
            let workflow_classifier_text = workflow_classifier_text(&messages, &content);
            let workflow_hint = nudge_classification
                .as_ref()
                .filter(|classification| classification.is_plan_update())
                .and_then(|_| workflow_steerer.plan_update_hint(&workflow_classifier_text));
            let classifier_plan_direction = nudge_classification
                .as_ref()
                .filter(|classification| classification.is_plan_update())
                .and_then(|_| nudge_classifier.direction_for(crate::NudgeClass::PlanUpdate));
            let plan_nudge_hint =
                combine_nudge_hints(classifier_plan_direction, workflow_hint.as_deref());
            if should_ground_unverified_run_command_blocker(
                &content,
                &tools,
                run_command_denial_observed,
                exec_grounding_turn,
                unverified_exec_blocker_nudges,
                workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                ),
            ) {
                if debug {
                    print_debug(
                        "unsupported run_command blocker — requiring a ground-truth probe",
                        color,
                    );
                }
                messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                messages.push(serde_json::json!({
                    "role": "user",
                    "content": format!(
                        "{} {}",
                        compress::LOOP_GUIDANCE_PREFIX,
                        run_command_ground_truth_nudge()
                    )
                }));
                unverified_exec_blocker_nudges += 1;
                continue 'round_loop;
            }
            if !content.is_empty()
                && pending_plan_nudges < PENDING_PLAN_NUDGE_CAP
                && workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                )
                && action_turn
            {
                let needs_plan_update = nudge_classification
                    .as_ref()
                    .is_some_and(|c| c.is_plan_update());
                if let Some(nudge) = pending_plan_completion_nudge(
                    step_ledger,
                    needs_plan_update,
                    plan_nudge_hint.as_deref(),
                ) {
                    if debug {
                        print_debug(
                            "active plan has unfinished steps — nudging before final answer",
                            color,
                        );
                    }
                    messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                    messages.push(serde_json::json!({
                        "role": "user",
                        "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, nudge)
                    }));
                    pending_plan_nudges += 1;
                    continue 'round_loop;
                }
            }
            if !content.is_empty()
                && stale_file_nudges < STALE_FILE_NUDGE_CAP
                && workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                )
                && action_nudges
                && looks_like_unverified_stale_file_blocker(&content)
            {
                if debug {
                    print_debug(
                        "unverified stale-file blocker — nudging to check ground truth",
                        color,
                    );
                }
                messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                messages.push(serde_json::json!({
                    "role": "user",
                    "content": format!(
                        "{} {}",
                        compress::LOOP_GUIDANCE_PREFIX,
                        stale_file_ground_truth_nudge()
                    ),
                }));
                stale_file_nudges += 1;
                continue 'round_loop;
            }
            if !content.is_empty()
                && narration_nudges < narration_nudge_cap
                && workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                )
                && action_turn
                && nudge_classification
                    .as_ref()
                    .is_some_and(|c| c.is_pending_action())
            {
                if debug {
                    print_debug(
                        "narrated intent with no tool call — nudging to act and continuing",
                        color,
                    );
                }
                // #1158: ephemeral — replace the prior nudge, don't stack.
                strip_trailing_nudge_exchange(&mut messages);
                messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                let direction = if narration_nudges == 0 {
                    nudge_classification
                        .as_ref()
                        .and_then(|classification| {
                            nudge_classifier.direction_for(classification.class)
                        })
                        .map(workflow_guidance)
                        .unwrap_or_else(narration_action_nudge)
                } else {
                    escalated_narration_action_nudge(
                        narration_nudges + 1,
                        narration_nudge_cap,
                        step_ledger,
                    )
                };
                messages.push(serde_json::json!({
                    "role": "user",
                    "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, direction),
                }));
                narration_nudges += 1;
                continue 'round_loop;
            }
            // Self-verify gate (#23) — mirrors the OpenAI path.
            // #2315: in the opt-in result-aware mode the same position decides
            // from observed outcomes instead (A12: one decision, three callers).
            let mut verification_stop = None;
            if verification.result_aware() && action_nudges && !content.is_empty() {
                match self_verify::conclude_turn(
                    self_verify::Concluding {
                        messages: &messages,
                        workspace,
                        task: active_task,
                        rounds_left: workflow_runtime.has_next_round(
                            round,
                            current_tool_round_limit,
                            workflow_grace_rounds,
                        ),
                        round,
                        ledger: &verification,
                        solve_obs: solve_obs.as_deref_mut(),
                    },
                    verification_nudges,
                )
                .await
                {
                    self_verify::Decision::Nudge(nudge) => {
                        strip_trailing_nudge_exchange(&mut messages);
                        messages
                            .push(serde_json::json!({ "role": "assistant", "content": content }));
                        messages.push(serde_json::json!({
                            "role": "user",
                            "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, nudge),
                        }));
                        verification_nudges += 1;
                        continue 'round_loop;
                    }
                    self_verify::Decision::Stop(reason) => verification_stop = Some(reason),
                    self_verify::Decision::Accept => {}
                }
            } else if self_verify::enabled()
                && action_nudges
                && self_verify_nudges < SELF_VERIFY_CAP
                && workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                )
                && !content.is_empty()
            {
                let cmds = self_verify::commands_from_messages(&messages);
                let checks = verification
                    .applicable_checks(workspace, active_task, &cmds)
                    .await
                    .unwrap_or_default();
                if let Some(nudge) = self_verify::verify_gate_nudge(&checks, &cmds) {
                    if debug {
                        print_debug(
                            "concluding with unrun verification — self-verify nudge",
                            color,
                        );
                    }
                    strip_trailing_nudge_exchange(&mut messages);
                    messages.push(serde_json::json!({ "role": "assistant", "content": content }));
                    messages.push(serde_json::json!({
                        "role": "user",
                        "content": format!("{} {}", compress::LOOP_GUIDANCE_PREFIX, nudge),
                    }));
                    self_verify_nudges += 1;
                    continue 'round_loop;
                }
            }
            // Phase 20 §2.2: non-empty final content is usable output —
            // report the accepted prompt before returning.
            if !content.is_empty() {
                emit_accepted(
                    &mut on_round_usage,
                    round_usage,
                    truncation_suspect,
                    round_est_raw,
                );
            }
            // Acceptance forensics — mirrors the OpenAI path.
            let accepted_reason = if content.is_empty() {
                crate::TurnEndReason::Empty
            } else if nudge_classification
                .as_ref()
                .is_some_and(|c| c.is_pending_action())
                && action_turn
            {
                if !workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                ) {
                    crate::TurnEndReason::NarrationFinalRound
                } else {
                    crate::TurnEndReason::NarrationCapExhausted
                }
            } else {
                crate::TurnEndReason::Completed
            };
            let accepted_reason = verification_stop.unwrap_or(accepted_reason);
            if debug && accepted_reason != crate::TurnEndReason::Completed {
                print_debug(
                    &format!("no-tool reply accepted as final answer ({accepted_reason:?})"),
                    color,
                );
            }
            if let Some(slot) = &mut end_reason {
                **slot = Some(accepted_reason);
            }
            // The streamed flag is true iff THIS round's SSE already printed
            // the accepted text live (so the TUI doesn't re-print).
            let streamed = printed_live && !content.is_empty();
            if content.is_empty() {
                let out = FinalReply::harness("(model returned an empty response — try rephrasing, or check the model with `newt doctor`)".to_string());
                let out = finalize_final_text(
                    out,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                observability::observe_harness_reply(&mut solve_obs);
                return Ok((out, streamed, accumulated_usage, hallucination_count));
            }
            // #1964: this normal (non-cap) finish gets the same claim check
            // + disclosure gate as a cap-exit summary.
            let out = finalize_final_text(
                content,
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            let streamed = streamed && out == oa_content;
            return Ok((out, streamed, accumulated_usage, hallucination_count));
        }

        // Record the assistant turn, then VALIDATE the whole batch before
        // emitting acceptance or running any call (#1528 B4 — mirrors the
        // OpenAI path). The replay stays in the INTERNAL shape: the executed
        // tool_calls (native or recovered) ride on the assistant turn so
        // `anthropic_wire_messages` re-derives tool_use blocks (ids replayed
        // verbatim) on the next dispatch — that's the round trip.
        messages.push(serde_json::json!({
            "role": "assistant",
            "content": oa_content,
            "tool_calls": tool_calls.unwrap(),
        }));
        let mut round_modified_workspace = false;
        let mut round_progress = false;
        let mut round_succeeded = false;
        let tcs = tool_calls.unwrap();
        // Phase 1 (invariant #3, BATCH level) — mirrors the OpenAI path. The
        // decoded `tool_uses` are already the internal shape (arguments as
        // objects), so the same extractor and batch validation apply; the
        // flat `name`/`input` fallback covers content-recovered calls.
        let extracted: Vec<(Option<&str>, Option<&str>, &serde_json::Value)> = tcs
            .iter()
            .map(|tc| {
                if tc["function"].is_null() {
                    (tc["id"].as_str(), tc["name"].as_str(), &tc["input"])
                } else {
                    (
                        tc["id"].as_str(),
                        tc["function"]["name"].as_str(),
                        &tc["function"]["arguments"],
                    )
                }
            })
            .collect();
        let validated = match tools::validate_tool_call_batch(&extracted, true) {
            Ok(v) => {
                uncorrelatable_batches = 0;
                Some(v)
            }
            Err(tools::BatchRejection::CorrelationImpossible(reason)) => {
                // A missing/blank/duplicate id: a tool result cannot
                // be correlated. Never fabricate an id — re-ask, or abort once
                // the budget is spent.
                let reask = tools::reask_uncorrelatable(
                    &mut uncorrelatable_batches,
                    &reason,
                    smart_harness,
                    tool_events.as_deref_mut(),
                )?;
                if let Some(turn) = messages.last_mut() {
                    tools::withdraw_tool_calls(turn);
                }
                messages.push(serde_json::json!({"role": "user", "content": reask}));
                continue 'round_loop;
            }
            Err(tools::BatchRejection::ContentInvalid(reason)) => {
                uncorrelatable_batches = 0;
                if let Some(harness) = smart_harness {
                    harness.reject_tools(&reason, true)?;
                }
                // ids are valid + unique → echo a correctly keyed rejection
                // per call and re-dispatch so the model can retry.
                for tc in tcs {
                    let id = tc["id"].as_str().unwrap_or("");
                    print_synthetic_tool_result(
                        "(rejected tool-call batch)",
                        &serde_json::Value::Null,
                        workspace,
                        &reason,
                        color,
                        &completed_spill_renderer,
                    );
                    if let Some(rec) = tool_events.as_deref_mut() {
                        rec.push(crate::ToolEvent::from_call(
                            "(rejected tool-call batch)",
                            &serde_json::Value::Null,
                            false,
                            Some(0),
                        ));
                    }
                    smart_harness::push_tool_message(
                        &mut messages,
                        serde_json::json!({
                            "role": "tool",
                            "tool_call_id": id,
                            "content": format!("tool-call batch rejected before execution: {reason}"),
                        }),
                        smart_harness,
                        true,
                        "(rejected tool-call batch)",
                    )?;
                }
                None
            }
        };
        // #1528 B4 — mirrors the OpenAI path: a FULLY-VALIDATED batch is
        // usable output; emit the accepted-prompt observation before the
        // first tool side effect.
        let batch = smart_harness
            .zip(validated.as_ref())
            .map(|(harness, calls)| harness.tool_batch(calls, &messages))
            .transpose()?;
        let mut tool_warnings = Vec::new();
        if validated.is_some() {
            emit_accepted(
                &mut on_round_usage,
                round_usage,
                truncation_suspect,
                round_est_raw,
            );
            commit_tool_round_narration(
                &oa_content,
                printed_live,
                completed_spill_renderer.as_deref(),
                color,
            );
        }
        // Phase 2: every call is valid — execute in order (empty when rejected).
        for (call_index, (tc, vc)) in tcs.iter().zip(validated.iter().flatten()).enumerate() {
            let id = vc.call_id.as_str();
            let name = vc.name.as_str();
            let args = vc.args.clone();
            announce_tool_activity(name);
            // Per-tool head: any frame from the PREVIOUS tool in this batch
            // comes down before this iteration's first writer (the debug /
            // trace echoes below print BEFORE the wired `call()` erase).
            dismiss_completed_spill(&completed_spill_renderer);
            if debug && tc["function"].is_null() {
                print_debug(
                    &format!(
                        "tool call in flat native format inside the executed batch \
                         (no `function` key) — name={name:?}"
                    ),
                    color,
                );
            }
            if trace {
                print_trace(
                    &format!(
                        "raw tool_call element: {}",
                        serde_json::to_string(tc).unwrap_or_else(|_| "?".into())
                    ),
                    color,
                );
            }
            let mcp_handles = mcp.handles(name);
            if debug {
                print_debug(
                    &format!("dispatching tool name={name:?} mcp_handles={mcp_handles}"),
                    color,
                );
            }
            if is_hallucination(name, &args) {
                hallucination_count += 1;
            }
            // #2637: never refuse an exact bare re-read — serve it silently
            // from the memo when the file's actual current content still
            // matches; otherwise fall through to a real read below.
            if let Some(content) =
                repeat_calls.cached_read(name, &args, ReadScope { workspace, caveats })
            {
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &content,
                    color,
                    &completed_spill_renderer,
                );
                if let Some(rec) = tool_events.as_deref_mut() {
                    rec.push(crate::ToolEvent::from_cache(name, &args));
                }
                let offloaded =
                    maybe_offload_tool_result(name, content, tool_offload, spill_store, disclosure);
                smart_harness::push_tool_resolution(
                    &mut messages,
                    serde_json::json!({
                        "role": "tool",
                        "tool_call_id": id,
                        "content": offloaded,
                    }),
                    batch.as_ref(),
                    call_index,
                )?;
                continue;
            }
            // Step 27.3/#771: short-circuit selected exact repeats (mirrors
            // the OpenAI path).
            if let Some(steer) = repeat_calls.repeat_steer(name, &args) {
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &steer,
                    color,
                    &completed_spill_renderer,
                );
                if let Some(rec) = tool_events.as_deref_mut() {
                    rec.push(crate::ToolEvent::from_call(name, &args, false, Some(0)));
                }
                smart_harness::push_tool_resolution(
                    &mut messages,
                    serde_json::json!({
                        "role": "tool",
                        "tool_call_id": id,
                        "content": steer,
                    }),
                    batch.as_ref(),
                    call_index,
                )?;
                continue;
            }
            let invocation = batch
                .as_ref()
                .map(|batch| batch.start(call_index, disclosure))
                .transpose()?;
            record_organic_note_use(name, &note_sink, &mut note_nudge);
            // retry technique: snapshot the file's pre-write bytes before the
            // write tool runs (mirrors the OpenAI path).
            let before_change =
                progress_workspace_state(name, &args, workspace, &caveats.fs_read).await;
            ledger_note_write(write_ledger, name, &args, workspace);
            let tool_t0 = std::time::Instant::now();
            let execution = std::sync::OnceLock::new();
            let retry_authorized = std::sync::OnceLock::new();
            let routed_to = std::sync::OnceLock::new();
            let governed_pr = std::sync::OnceLock::new();
            let report_capture = std::sync::Mutex::new(observed_report::Capture::default());
            let command_directory = std::sync::OnceLock::new();
            let attribution_epoch = AttributionEpoch::new(attribution, git_tool, model, name);
            // #727: intercept the read-only budget self-read (mirrors the
            // OpenAI path — `num_ctx` never rides this wire either).
            let result = if tools::is_context_remaining_call(name) {
                let report = budget::render_context_budget(
                    prompt_tracker.current(&messages, Some(&tools), cal, estimation),
                    effective_input_ceiling,
                    num_ctx,
                    input_ceiling_pct,
                    low_budget_pct,
                );
                if let Some(invocation) = &invocation {
                    invocation.host();
                    invocation.observe(&report, None, spill_store)?;
                }
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &report,
                    color,
                    &completed_spill_renderer,
                );
                report
            } else {
                // #1947: distil the ledger BEFORE the call. What a
                // `render_report` in THIS call can be checked against is what
                // the turn has already done — the events for this very call
                // are pushed after it returns.
                let tool_evidence = tool_events
                    .as_deref()
                    .map(|e| capability_check::Evidence::from_events(e));
                let Some(result) = tools::execute_tool_with_collaborators(
                    name,
                    &args,
                    workspace,
                    color,
                    tool_output_lines,
                    caveats,
                    mcp,
                    tools::ToolCollaborators {
                        command_budget,
                        shell_dialect,
                        read_history: Some(&mut read_history),
                        default_command_cwd,
                        worktree_session,
                        invocation: invocation.as_ref(),
                        build_check_cmd: build_check_cmd.as_deref(),
                        tool_evidence: tool_evidence.as_ref(),
                        // Reborrow + re-coerce — see the OpenAI path.
                        note_sink: note_sink
                            .as_deref_mut()
                            .map(|s| &mut *s as &mut dyn NoteSink),
                        recall_source,
                        memory_source,
                        prompt_context: Some(prompt_context),
                        artifact_context,
                        artifact_sink,
                        permission_gate: permission_gate
                            .as_deref_mut()
                            .map(|g| &mut *g as &mut dyn PermissionGate),
                        exec_floor,
                        git_tool,
                        crew_runner,
                        scratchpad_store,
                        code_search,
                        where_is,
                        nav,
                        experience_store,
                        step_ledger,
                        operating_mode_control,
                        plan_mode_control,
                        plan_draft_sink,
                        spill_store,
                        persona_tools,
                        hidden_tools: Some(&hidden_tools),
                        live_tool_output: live_tool_output.clone(),
                        completed_spill_renderer: completed_spill_renderer.clone(),
                        execution: Some(&execution),
                        retry_authorized: Some(&retry_authorized),
                        governed_pr: Some(&governed_pr),
                        report_capture: Some(&report_capture),
                        command_directory: Some(&command_directory),
                        routed_to: Some(&routed_to),
                        pending_rerun: Some(&mut pending_rerun),
                    },
                    tool_offload,
                    prompt_disposition,
                    cancel,
                )
                .await?
                else {
                    return Ok((
                        smart_harness::cancelled(smart_harness, &mut end_reason)?,
                        false,
                        accumulated_usage,
                        hallucination_count,
                    ));
                };
                result
            };
            if debug {
                // This line lands directly below the viewport `result` just
                // painted — take the frame down first or its later rewind
                // erases this line and strands frame rows.
                dismiss_completed_spill(&completed_spill_renderer);
                let excerpt: String = result.chars().take(120).collect();
                print_debug(&format!("tool result: {excerpt:?}"), color);
            }
            // 17.6 + 27.3 — mirrors the OpenAI path.
            let ok = tools::tool_ok(&result, execution.get().copied());
            round_succeeded |= ok;
            attribution_epoch.finish(&args, ok);
            run_command_denial_observed |= run_command_result_is_denial(name, ok, &result);
            capability_evidence.record(name, ok, execution.get().copied());
            let after_change = if before_change.is_some() {
                progress_workspace_state(name, &args, workspace, &caveats.fs_read).await
            } else {
                None
            };
            round_modified_workspace |=
                workflow_runtime.record_workspace_change(before_change, after_change);
            round_progress |= workflow_runtime.record_observation(
                name,
                &args,
                &result,
                ok,
                execution.get().copied(),
                routed_to.get(),
            );
            repeat_calls.record(
                name,
                &args,
                ok,
                &result,
                execution.get().copied(),
                ReadScope { workspace, caveats },
            );
            repeat_calls.permit_authorized_retry(name, &args, &retry_authorized);
            append_clean_build_warning(
                if batch.is_some() {
                    &mut tool_warnings
                } else {
                    &mut messages
                },
                &mut clean_build,
                &args,
                None,
            )?;
            record_completed_tool_event(
                &mut tool_events,
                name,
                &args,
                ok,
                execution.get().copied(),
                tool_t0,
            );
            turn_claims.observe_report(
                workspace,
                &caveats.fs_read,
                &report_capture.lock().expect("report capture"),
                execution.get().copied(),
                governed_pr.get(),
            );
            if let Some(outcome) = governed_pr.get() {
                verification.record_publication_outcome(outcome);
            }
            if ok {
                if let Some(directory) = command_directory.get() {
                    verification.record_command_directory(directory);
                }
            }
            verification
                .observe_routed(
                    name,
                    &args,
                    ok,
                    execution.get().copied(),
                    workspace,
                    routed_to.get(),
                )
                .await;
            record_phantom_reach(
                &mut phantom_reaches,
                name,
                &args,
                &result,
                ok,
                advertise_team,
            );
            // #867 Part A: ledger verified paths (mirrors the OpenAI path).
            observed_paths.record(&result, &mut observed_resolver);
            // The tool result stays `role:"tool"` in the internal shape;
            // `anthropic_wire_messages` folds each consecutive run into ONE
            // user message of tool_result blocks (`tool_use_id` = this id)
            // on the next dispatch.
            smart_harness::push_tool_return(
                &mut messages,
                serde_json::json!({
                    "role": "tool",
                    "tool_call_id": id,
                    "content": smart_harness::tool_result(name, result, tool_offload, spill_store, disclosure, invocation.as_ref())?,
                }),
                invocation.as_ref(),
            )?;
        }
        for message in tool_warnings {
            smart_harness::push_tool_message(
                &mut messages,
                message,
                smart_harness,
                true,
                "build guidance",
            )?;
        }
        if let Some(harness) = smart_harness {
            harness.record_messages(&messages)?;
        }
        if round_succeeded {
            output_recovery.completed_tool_round();
        }
        workflow_runtime.record_round_outcome(round_modified_workspace, round_progress);
        if let Some(text) = pending_plan_approval_handoff(
            plan_mode_control,
            PlanRoundFacts {
                disposition: prompt_disposition,
                step_ledger,
                plan_at_turn_start: &plan_at_turn_start,
                progressed: round_modified_workspace || round_progress,
            },
            smart_harness,
            cancel,
            &mut end_reason,
        )? {
            dismiss_completed_spill(&completed_spill_renderer);
            let text = finalize_final_text(
                FinalReply::harness(text),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
    }

    // Reached the round cap; the last tool's completed viewport is still up
    // and nothing has written since — dismiss before any summary output.
    dismiss_completed_spill(&completed_spill_renderer);
    // Trim the message list and make ONE final
    // tools-disabled completion (mirrors the OpenAI path).
    let protected_head = protected_prompt_head_len(&messages, prompt_read::ACTIVE_PROMPT_PREFIX);
    let replay_protected_tail_len =
        compress::protected_reasoning_tail_len(&messages, reasoning_replay_scope);
    let trimmed = trim_for_summary(&messages, protected_head, 6.max(replay_protected_tail_len));
    // Step 27.5: salvage progress + failed-call count (mirrors the OpenAI path).
    let progress = cap_exit_progress(worktree_session, step_ledger, scratchpad_store);
    // #2374: a failed check at the round limit is a scored repair exhaustion.
    let cap_reason = verification
        .cap_exit_reason(
            workspace,
            if smart_harness.is_some() {
                smart_verify
            } else {
                action_nudges
            },
            current_tool_round_limit,
            solve_obs.as_deref_mut(),
        )
        .await;
    if let Some(hit) = &mut round_cap_hit {
        **hit = true;
    }
    if let Some(harness) = smart_harness {
        harness.record_messages(&messages)?;
        let text = cap_exit_fallback(
            current_tool_round_limit,
            accumulated_usage,
            repeat_calls.total_failures(),
            progress.as_deref(),
        );
        let text = finalize_final_text(
            text,
            workspace,
            &caveats.fs_read,
            &capability_evidence,
            disclosure,
            &turn_claims,
            &verification,
        );
        harness.outcome(cap_reason, &text)?;
        if let Some(slot) = &mut end_reason {
            **slot = Some(cap_reason);
        }
        return Ok((text, false, accumulated_usage, hallucination_count));
    }

    let cap = CapExit {
        max_tool_rounds: current_tool_round_limit,
        accumulated: accumulated_usage,
        wasted_calls: repeat_calls.total_failures(),
        progress,
        observed: observed_paths.into_vec(),
        request_budget: authoritative_request_budget(
            send_budget,
            send_budget_authoritative,
            mid_loop_trim_tokens,
        ),
        calibration: cal,
        estimation,
        ollama_options: None,
        prompt_measurement: Default::default(),
        fell_back: Default::default(),
    };
    let result = final_summary_anthropic(
        &client,
        &messages_url,
        model,
        api_key,
        trimmed,
        generation_policy,
        &cap,
        attempts,
    )
    .await;
    let (text, streamed, usage) = cap.recover_rejection(
        result,
        &mut solve_obs,
        compress_state,
        current_tool_round_limit,
        cw_retries + 1,
    )?;
    let text = finalize_final_text(
        text,
        workspace,
        &caveats.fs_read,
        &capability_evidence,
        disclosure,
        &turn_claims,
        &verification,
    );
    if let Some(slot) = &mut end_reason {
        **slot = Some(cap_reason);
    }
    Ok((text, streamed, usage, hallucination_count))
}

// ── OpenAI Responses API (`POST /v1/responses`) ────────────────────────────
//
// The newer OpenAI surface. Models like `gpt-5-codex` are served ONLY here and
// 404 on `/v1/chat/completions`. The request/response shapes differ (input vs
// messages, instructions vs system message, a flatter tool schema, `output[]`
// items vs `choices`, `input_tokens`/`output_tokens` usage), so this is a
// parallel — deliberately leaner — loop. Selected per backend via
// `api = "responses"` (surfaced to the loop as `NEWT_OPENAI_API`). Non-streaming
// in v1 (matching the chat path's UX). Reactive context-window-400 recovery is
// now present here too (#1528): a hard cw-400 learns the true window, tightens a
// monotone input ceiling, compacts the running history through the shared
// `compress::compress` (via `responses_compaction`), and re-dispatches — bounded
// to 2 recoveries. The remaining #1528 follow-ups are PROACTIVE mid-loop
// compaction (compact before overflow) and usage-learning ceiling raises.

/// `true` when the active OpenAI backend selected the Responses API
/// Used only for the legacy constructor default; explicit hosts supply typed API.
fn responses_api_selected() -> bool {
    std::env::var("NEWT_OPENAI_API")
        .ok()
        .is_some_and(|v| v.eq_ignore_ascii_case("responses"))
}

/// Serialize only the effort admitted by the captured Responses policy.
fn responses_reasoning_field(
    effort: Option<crate::model_card::ReasoningEffort>,
) -> Option<serde_json::Value> {
    effort.map(|value| serde_json::json!({ "effort": value }))
}

/// Translate the chat/completions tool array (`{type:function,
/// function:{name,…}}` elements, as returned by `merged_tool_definitions`) to
/// the Responses API's flatter `{type:function, name, description, parameters}`.
/// An already-flat (or unknown) element passes through.
fn tools_to_responses(tools: &serde_json::Value) -> Vec<serde_json::Value> {
    tools
        .as_array()
        .map(|arr| {
            arr.iter()
                .map(|t| {
                    let f = &t["function"];
                    if f.is_object() {
                        // `parameters` is copied wholesale, so `required` /
                        // `additionalProperties` / nested schemas keep their exact
                        // validation semantics.
                        let mut tool = serde_json::json!({
                            "type": "function",
                            "name": f["name"],
                            "description": f["description"],
                            "parameters": f["parameters"],
                        });
                        // #1526 (invariant #6): a schema conversion must not
                        // silently change validation semantics. Chat Completions
                        // puts `strict` on the `function` object; the Responses API
                        // puts it at the tool's TOP level. Dropping it would
                        // downgrade a strict schema (additionalProperties:false +
                        // all-required enforced) to permissive — so the model could
                        // send args the strict schema rejects. Carry it through
                        // verbatim; absent stays absent (no spurious strictness).
                        if let Some(strict) = f.get("strict").filter(|s| !s.is_null()) {
                            tool["strict"] = strict.clone();
                        }
                        tool
                    } else {
                        t.clone()
                    }
                })
                .collect()
        })
        .unwrap_or_default()
}

/// Extract `(assistant_text, function_call_items, echo_items)` from a Responses
/// reply's `output[]`. `text` is the concatenation of `output_text` parts inside
/// `message` items. `function_call_items` are the calls the loop executes.
/// `echo_items` is the ordered subsequence of `reasoning` AND `function_call`
/// items that must be echoed VERBATIM into the next request's `input`: a
/// reasoning model (gpt-5.6-sol, gpt-5-codex) pairs each `function_call` with a
/// preceding `reasoning` item (`rs_…`) and 400s ("function_call … without its
/// required 'reasoning' item") if the call is sent back without it. Preserving
/// original order keeps each reasoning item adjacent to its call. Falls back to a
/// flattened top-level `output_text` if the structured walk found no text.
/// The OpenAI **Responses API** agentic loop (`POST {endpoint}/v1/responses`).
/// Parallel to [`openai_chat_complete`] but over the Responses shapes, for
/// models served only there (`gpt-5-codex`). Non-streaming; selected via
/// `api = "responses"`.
///
/// ## Long-turn budgeting: fail-closed ceiling + reactive cw-400 recovery
///
/// This loop enforces a configured context window as a local ceiling and
/// reserves output headroom (`BHV-CONTEXT-001`), refusing an over-budget request
/// **before** dispatch. On top of that (#1528 slice 1) it now mirrors the Chat
/// Completions path's **reactive** context-limit survival: a hard context-window
/// 400 learns the endpoint's true window (`recover_cw_400`), tightens a
/// **monotonically** shrinking learned input ceiling, **compacts** the running
/// history to fit through the shared [`compress`] pipeline (bridged in/out of the
/// Responses `input` shape by [`responses_compaction`], and reported through
/// `on_round_usage` / `compress_state`), and **re-dispatches** — bounded to 2
/// recoveries, after which the raw 400 surfaces. A numberless overflow falls back
/// to a derived cap. So a long tool turn that overflows now compacts and
/// continues instead of failing (still never a silent truncation).
///
/// Remaining #1528 follow-ups (NOT in this slice): **proactive** mid-loop
/// compaction (compact *before* the overflow, driven by the mid-loop trim
/// threshold) and **usage-learning** acceptance-side ceiling *raises* (an
/// `on_round_usage` `Accepted` widening the budget on proven-good rounds).
pub async fn openai_responses_complete(
    ctx: ChatCtx<'_>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    openai_responses_complete_with_prompt(ctx, None, None, mcp).await
}

pub async fn openai_responses_complete_with_prompt(
    ctx: ChatCtx<'_>,
    turn_prompt_context: Option<&crate::TurnPromptContext>,
    prompt_source: Option<&dyn PromptSource>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    openai_responses_complete_with_prompt_and_artifacts(
        ctx,
        turn_prompt_context,
        prompt_source,
        None,
        None,
        mcp,
    )
    .await
}

fn responses_source_messages(
    instructions: Option<&str>,
    input: &[serde_json::Value],
) -> Vec<serde_json::Value> {
    let mut messages = Vec::with_capacity(input.len() + 1);
    if let Some(text) = instructions {
        messages.push(serde_json::json!({"role":"system", "content":text}));
    }
    messages.extend_from_slice(input);
    messages
}

/// One retrying Responses dispatch: POST the VALIDATED body, classify + retry
/// transient transport failures via [`with_backoff_notify_error`], surface a typed
/// HTTP-status error, and parse the JSON body. BOTH the per-round loop and the final
/// tools-disabled summary go through this, so a transient 500 / timeout /
/// connection reset on the LAST request no longer discards the turn after every
/// tool round was already spent — the summary retries like any other round.
///
/// #1528 B5: this takes a [`ValidatedResponsesRequest`] — a newtype with no public
/// constructor other than a successful [`validate_responses_request`] — so an
/// unvalidated `serde_json::Value` body cannot compile its way to `POST /v1/responses`.
#[allow(clippy::too_many_arguments)]
async fn dispatch_responses_json<'a>(
    client: &reqwest::Client,
    url: &str,
    api_key: Option<&str>,
    validated: &responses_wire_validation::ValidatedResponsesRequest,
    retry: &RetryPolicy,
    color: bool,
    smart_harness: Option<(&smart_harness::SmartHarness, &[serde_json::Value])>,
    attempts: Option<attempt_capture::AttemptScope<'a>>,
) -> anyhow::Result<(serde_json::Value, Option<attempt_capture::Attempt<'a>>)> {
    let body = validated.body();
    let body_bytes = smart_harness
        .map(|(h, messages)| h.prepare_with_messages(body, "responses", messages))
        .transpose()?;
    dispatch_with_decoder(
        retry,
        attempts,
        || async {
            let mut req = match &body_bytes {
                Some(bytes) => client
                    .post(url)
                    .header(reqwest::header::CONTENT_TYPE, "application/json")
                    .body(bytes.clone()),
                None => client.post(url).json(body),
            };
            if let Some(key) = api_key {
                req = req.bearer_auth(key);
            }
            Ok(req)
        },
        // Keep the status prefix exact: retry classification reads the message.
        "inference endpoint",
        |attempt, delay, error| {
            print_retry_indicator(attempt, retry.max_retries, delay, error, color);
        },
        smart_harness.map(|(h, _)| h),
        |bytes| Ok(serde_json::from_slice(bytes)?),
    )
    .await
}

/// Send with retries and decode. With an attempt scope, every try is one
/// recorded attempt; the caller completes the returned attempt with the usage
/// it extracts, because only it knows the wire's usage shape.
async fn dispatch_with_decoder<'a, Fut>(
    retry: &RetryPolicy,
    attempts: Option<attempt_capture::AttemptScope<'a>>,
    request: impl Fn() -> Fut,
    http_error_prefix: &str,
    on_retry: impl FnMut(u32, std::time::Duration, &anyhow::Error),
    smart_harness: Option<&smart_harness::SmartHarness>,
    decode: fn(&[u8]) -> anyhow::Result<serde_json::Value>,
) -> anyhow::Result<(serde_json::Value, Option<attempt_capture::Attempt<'a>>)>
where
    Fut: std::future::Future<Output = anyhow::Result<reqwest::RequestBuilder>>,
{
    with_backoff_notify_error(
        retry,
        || async {
            // Typed classification at the source (W0 #1511).
            let (resp, attempt) =
                attempt_capture::send(attempts, "primary", request().await?, "request failed")
                    .await?;
            let json = smart_harness::response_with_decoder(
                resp,
                smart_harness,
                http_error_prefix,
                decode,
            )
            .await
            .inspect_err(|error| attempt_capture::failed(attempt.as_ref(), error))?;
            Ok((json, attempt))
        },
        on_retry,
    )
    .await
}

/// Record a decoded 2xx Responses reply's attempt by the #2313 state rule: a
/// complete terminal response is ok whatever its content shape — an answer, a
/// refusal, a truncation (`incomplete`), or content the loop rejects: a mixed
/// refusal and tool calls (whatever the status, since it is real output), or
/// malformed content under status `completed`. A failed, provider-error or
/// non-terminal body is failed, and so is a body with neither a status nor any
/// output: that is not a Responses reply at all. How the loop handles the content is
/// separate from the attempt state. The usage the body reported attaches either
/// way.
fn complete_responses_attempt(
    attempt: Option<&attempt_capture::Attempt<'_>>,
    json: &serde_json::Value,
    decoded: &Result<
        crate::responses_wire::DecodedResponse,
        crate::responses_wire::ResponseDecodeError,
    >,
) {
    use crate::attempts::AttemptState;
    use crate::responses_wire::ResponseDecodeError as E;
    // Every variant is named, so a new one cannot default to ok.
    let state = match decoded {
        Ok(_)
        | Err(E::Refused { .. } | E::Incomplete { .. } | E::MixedRefusalAndToolCalls { .. }) => {
            AttemptState::Ok
        }
        Err(E::Malformed(_)) if json["status"].as_str() == Some("completed") => AttemptState::Ok,
        Err(E::Malformed(_) | E::ProviderError(_) | E::Failed(_) | E::NonTerminal(_)) => {
            AttemptState::Failed
        }
    };
    attempt_capture::finish(
        attempt,
        state,
        crate::responses_wire::decode_usage(&json["usage"]),
    );
}

async fn openai_responses_complete_with_prompt_and_artifacts(
    ctx: ChatCtx<'_>,
    turn_prompt_context: Option<&crate::TurnPromptContext>,
    prompt_source: Option<&dyn PromptSource>,
    artifact_source: Option<&dyn artifact_read::ArtifactSource>,
    artifact_sink: Option<&dyn artifact_read::PromptArtifactSink>,
    mcp: &mut dyn McpTools,
) -> anyhow::Result<(String, bool, Option<crate::TokenUsage>, u32)> {
    let ChatCtx {
        shell_dialect,
        command_budget,
        verify_outcomes,
        smart_harness,
        url,
        model,
        kind: _,
        api_key,
        messages: mem_messages,
        task,
        workspace,
        default_command_cwd,
        worktree_session,
        color,
        markdown: _,
        tool_offload,
        spill_store,
        disclosure,
        compaction_store,
        scratchpad,
        scratchpad_store,
        code_search,
        where_is,
        nav,
        exposure,
        experience_store,
        step_ledger,
        caveats,
        persona_tools,
        cognition,
        chat_completions_capability: _,
        responses_capability,
        openai_api: _,
        output_allowance,
        overflow_retry: _,
        attempt_ledger,
        reasoning_replay_scope: _,
        max_tool_rounds,
        workflow_grace_rounds,
        narration_nudge_cap,
        action_nudges,
        prompt_disposition,
        prompt_intake,
        tool_output_lines,
        debug,
        trace,
        // #727: bound (not `_`) so get_context_remaining can report the budget;
        // on the Responses wire num_ctx is normally unset (cloud), so the report
        // is honestly ceiling-less.
        num_ctx,
        connect_timeout_secs,
        inference_timeout_secs,
        mid_loop_trim_threshold: _,
        compaction_trigger_policy: _,
        mid_loop_trim_tokens,
        max_ok_input,
        build_check_cmd,
        safe_context,
        // #1528: activated — the Responses loop now recovers a hard cw-400 by
        // learning the window, tightening a monotone ceiling, compacting via the
        // shared `compress::compress`, and re-dispatching (bounded to 2).
        recover_cw_400,
        mut note_sink,
        mut note_nudge,
        recall_source,
        memory_source,
        summarizer,
        compress_state,
        mut tool_events,
        mut phantom_reaches,
        mut end_reason,
        mut round_cap_hit,
        mut solve_obs,
        mut permission_gate,
        mut on_round_usage,
        estimate_ratio,
        // #727: bound for the get_context_remaining used-token estimate.
        estimation,
        summary_input_cap_floor_chars,
        rewrites_history,
        input_ceiling_pct,
        low_budget_pct,
        exec_floor,
        write_ledger,
        attribution,
        cancel,
        run_allowance,
        live_tool_output,
        git_tool,
        crew_runner,
        operating_mode_control,
        plan_mode_control,
        plan_draft_sink,
        steering,
        completed_spill_renderer,
        // The Responses wire carries reasoning in its own items, never as a
        // lone leading `</think>` closer, so the declared #528 shape does not
        // apply. Bound and ignored rather than dropped from the pattern: a
        // future field added to ChatCtx then fails HERE, forcing a decision
        // about what it means for this wire instead of silently defaulting.
        emits_leading_reasoning: _,
    } = ctx;
    let mut generation_window = num_ctx;
    let generation_policy = generation_policy::GenerationPolicy::resolve_responses(
        cognition,
        output_allowance,
        &responses_capability,
    )?;
    if let Some(obs) = solve_obs.as_deref_mut() {
        obs.responses_capability = Some(responses_capability);
        obs.reasoning_effort = generation_policy.reasoning_effort;
    }
    // Any completed viewport this turn paints must not outlive the turn's
    // bookkeeping: on EVERY exit (return, `?`, cancel, panic) the guard
    // discards it — without terminal writes — so a stale rewind can never
    // replay over a later turn's prompt.
    let _completed_spill_guard = CompletedSpillDismissGuard(&completed_spill_renderer);
    if let Some(harness) = smart_harness {
        harness.start_turn()?;
    }
    // Smart mode retains full tool output before the existing shell cap runs.
    let spill_store = smart_harness.map(|h| h.spill_store()).or(spill_store);
    let tool_offload = tool_offload || smart_harness.is_some();
    let smart_verify = action_nudges && prompt_disposition == PromptDisposition::Act;
    let action_nudges = action_nudges && smart_harness.is_none();
    let max_tool_rounds = prompt_disposition.tool_round_limit(max_tool_rounds);
    // #1528: headless callers may pass no session state — fall back to a local
    // one so the cw-400 recovery's `compress::compress` always has anti-thrash
    // state to consult (mirrors the Chat Completions path).
    let mut local_compress_state = CompressState::new();
    let compress_state = match compress_state {
        Some(s) => s,
        None => &mut local_compress_state,
    };

    let client = reqwest::Client::builder()
        .connect_timeout(std::time::Duration::from_secs(connect_timeout_secs))
        .read_timeout(std::time::Duration::from_secs(inference_timeout_secs))
        .build()?;
    let responses_url = format!("{}/v1/responses", url.trim_end_matches('/'));
    let retry = tui_retry_policy(url);
    let advertise_save_note = note_sink.is_some();
    let advertise_recall = recall_source.is_some();
    let advertise_memory_fetch = memory_source.is_some();
    // Step 26.4 (#583): state tools only when the feature is on AND a store exists.
    let advertise_scratchpad = scratchpad_store.is_some() && scratchpad;
    // Step 26.5.5 (#582): the code_search tool when a searcher is present.
    let advertise_code_search = code_search.is_some();
    // Step 26.6a (#585): the experiential tools when a store is present.
    let advertise_experiential = experience_store.is_some();
    // Step 26.6b (#586): the scheduled plan tools when a ledger is present.
    let advertise_scheduled = step_ledger.is_some();
    // Native Git is the default interface; the injected adapter remains internal.
    let advertise_git = false;
    let advertise_team = crew_runner.is_some();
    let advertise_operating_mode = operating_mode_control.is_some();
    let advertise_plan_mode = plan_mode_control.is_some();
    let advertise_plan_mode_active =
        plan_mode_control.is_some_and(|control| control.is_plan_mode());

    let mem_messages = observed_report::replay_messages(mem_messages);
    let mut msgs_json: Vec<serde_json::Value> = mem_messages
        .iter()
        .map(|m| serde_json::json!({"role": m.role.as_str(), "content": m.content}))
        .collect();
    if let Some(harness) = smart_harness {
        msgs_json = harness.initial_messages(msgs_json)?;
    }
    if let (Some(session), Some(context)) = (worktree_session, turn_prompt_context) {
        session
            .report
            .lock()
            .expect("report state")
            .begin(context.active().root_prompt_id());
    }
    let ephemeral_prompt = prompt_read::headless_prompt_fallback(turn_prompt_context, task);
    let turn_prompt_context = turn_prompt_context.or(ephemeral_prompt.as_ref());
    let prompt_context =
        prompt_read::PromptReadContext::new(turn_prompt_context, task, prompt_source);
    let artifact_context = turn_prompt_context
        .map(|turn| artifact_read::ArtifactReadContext::from_turn(turn, artifact_source));
    prompt_read::ensure_active_prompt_card(&mut msgs_json, prompt_context, prompt_intake);
    // #2313: one ledger attempt per primary request, keyed at the send.
    let attempt_turn = turn_prompt_context
        .map(|turn| turn.active_operator_prompt().id().to_string())
        .unwrap_or_default();
    // An explicit inference budget applies even without an audit sink.
    let fallback_ledger = std::sync::Mutex::new(crate::attempts::AttemptLedger::default());
    let attempt_ledger = attempt_ledger.or_else(|| run_allowance.map(|_| &fallback_ledger));
    let attempts = attempt_ledger.map(|ledger| attempt_capture::AttemptScope {
        ledger,
        turn: &attempt_turn,
        model,
        backend: url,
        cancel,
        run_allowance,
    });
    let exec_grounding_turn = action_nudges && prompt_disposition == PromptDisposition::Act;
    let (mut instructions, mut input) = crate::responses_wire::build_responses_input(&msgs_json);
    // Smart preflight, pin registration and composition must all see the same
    // canonical sources. Split system instructions only in the wire renderer.
    if smart_harness.is_some() {
        if let Some(text) = instructions.take() {
            input.insert(0, serde_json::json!({"role":"system", "content":text}));
        }
    }
    let tools_chat = merged_tool_definitions(
        mcp,
        advertise_save_note,
        advertise_recall,
        advertise_memory_fetch,
        advertise_git.then_some(&caveats.fs_read),
        advertise_team,
        advertise_scratchpad,
        advertise_code_search,
        advertise_experiential,
        advertise_scheduled,
        advertise_operating_mode,
        advertise_plan_mode,
        advertise_plan_mode_active,
        command_budget,
        shell_dialect,
    );
    // FR-1 part 2 (#997): scope the advertised catalog to the active persona
    // (Responses wire). No-op when `persona_tools` is `None`.
    let tools_chat = filter_advertised_tools(tools_chat, persona_tools);
    let tools_chat = filter_tools_for_disposition(
        smart_harness::advertise(tools_chat, smart_harness),
        prompt_disposition,
    );
    // #TEC Pass 1: exposure stage on the chat-shaped catalog before it is
    // projected to Responses tools, so the estimate and the wire agree.
    // Identity under `ExposureProfile::Full`. The send budget is computed just
    // below on this wire, so derive the live budget inline here.
    // #1526 (invariant #4): the configured context window is a LOCAL safety
    // limit even though the Responses wire never carries `num_ctx` (provider-side
    // limits). Derive its input ceiling here and thread it through every local
    // budget below, so a request that would overflow a declared window is refused
    // pre-dispatch instead of relying solely on a reactive 400 / silent
    // truncation. `None` num_ctx (the cloud default) resolves to `None` and
    // leaves the prior behaviour unchanged.
    //
    // R4: RESERVE local output headroom in the ceiling. This wire sends no
    // `max_output_tokens`, but a configured window must still leave room for the
    // model's generation — else the input ceiling over-counts and a long turn
    // refuses with no headroom. Reserve uses the cognition dial directly (opt-in:
    // `None` cognition reserves nothing), so a declared window now composes with
    // the output reserve exactly as the Chat Completions path does.
    // #1526 (invariant #4) + #1528: ONE budget state is the single source of
    // truth for this loop's context budget — the declared-window hard ceiling,
    // the soft send budget, the monotone learned ceiling, and the authoritative
    // preflight refusal budget all derive from it (see `ResponsesBudgetState`).
    // It reserves local output headroom via the cognition dial (this wire sends
    // no `max_output_tokens`) so a declared window composes with the reserve
    // exactly as the Chat Completions path does; `None` num_ctx (the cloud
    // default) stays ceiling-less, leaving hosted OpenAI unchanged.
    //
    // NOTE (out of #1528 B1 scope): the Ollama (~1363) and Chat Completions
    // (~4887) loops rebuild this identical trio inline and differ ONLY in the
    // output-reserve argument — the sibling duplication this state is designed to
    // absorb next (one-issue-one-PR).
    let mut budget_state = resolve_responses_budget(
        num_ctx,
        safe_context,
        max_ok_input,
        mid_loop_trim_tokens,
        input_ceiling_pct,
        None,
        generation_policy.output_allowance,
    );
    observability::observe_output_allowance(&mut solve_obs, budget_state.output_reserve(), false);
    let (tools_chat, hidden_tools) = crate::agentic::tools::select_exposed(
        tools_chat,
        &exposure,
        budget_state.exposure_budget(),
        &std::collections::BTreeSet::new(),
        estimation,
    );
    let mut tools_chat =
        crate::agentic::tools::select_openai_compatible_tools(tools_chat, &hidden_tools);
    let mut tools = tools_to_responses(&tools_chat);
    let mut tools_for_estimate = serde_json::Value::Array(tools.clone());
    let mut cal = compress_state.calibration.ratio(estimate_ratio);
    // #1528: real-token schema overhead of the EXPOSED tool set — subtracted from
    // a recovered input cap before the compaction budget is converted back to
    // chars/4 currency, so the compacted history leaves room for the tool schemas
    // that ride every request. Known only after exposure, so it is set on the
    // state here (mirrors the Chat Completions path's `tool_tokens_real`).
    budget_state.set_tool_schema_tokens(calibrate_up(
        estimate_value_tokens(&tools_for_estimate, estimation),
        cal,
    ));
    // #1528: consecutive context-window recoveries (parse limit → tighten
    // → compact → redispatch), bounded to 2 until a generation succeeds.
    let mut cw_retries: u32 = 0;
    let mut output_recovery = output_limit_recovery::Recovery::default();
    let today = chrono::Local::now().format("%Y-%m-%d").to_string();
    preflight_irreducible_request(
        &msgs_json,
        Some(&tools_for_estimate),
        budget_state.actionable_input_budget(),
        cal,
        estimation,
        model,
    )?;

    let mut accumulated_usage: Option<crate::TokenUsage> = None;
    let mut hallucination_count: u32 = 0;
    // Step 27.3/#771: guard against exact-repeat tool loops this run.
    // #2315: result-aware verification for this turn, decided once.
    let result_aware = self_verify::enabled() && verify_outcomes;
    let mut repeat_calls = RepeatCallGuard::default();
    // Plan-before-act: the ledger as this turn began (see `PlanRoundFacts`).
    let plan_at_turn_start = step_ledger
        .map(|ledger| ledger.snapshot())
        .unwrap_or_default();
    let mut read_history = tools::ReadHistory::default();
    // #2315: what each check actually did, fed at the per-tool-result funnel.
    let mut verification = self_verify::VerificationLedger::for_turn(task, result_aware);
    // #2683: HEAD before this turn's own tool calls run, so a "committed"
    // claim in the final report can be checked against whether HEAD actually
    // moved. `None` (off-repo, or the read scope refuses the probe) must
    // never manufacture a false refutation — see `claim_check::TurnGitEvidence`.
    let turn_claims =
        claim_check::TurnClaims::capture(workspace, &caveats.fs_read, worktree_session)
            .with_evidence(observed_report::review::Evidence {
                sink: artifact_sink,
                context: artifact_context,
                spill: spill_store,
            });
    // #1948: DETECTION beside the guard — it notices a clean-then-build
    // loop and says so once; it never blocks or rewrites the call.
    let mut clean_build = crate::loop_watch::CleanBuildWatch::default();
    let mut tools_supported = true;
    let mut tools_unsupported_notified = false;
    let mut unverified_exec_blocker_nudges: usize = 0;
    let mut run_command_denial_observed = false;
    // #2628: see the primary loop declaration above for the invariant.
    let mut pending_rerun: Option<tools::PendingRerun> = None;
    let mut capability_evidence = capability_check::Evidence::default();
    let mut probe_correction_used = false;
    let mut readonly_completion_retried = false;
    let nudge_classifier = crate::NudgeClassifier::load_default();
    // Keep the same cap-exit evidence ledger as the three chat-shaped wires.
    // It must record before result offload/compaction removes the source text.
    let mut observed_paths = claim_check::ObservedPaths::default();
    let mut observed_resolver = claim_check::workspace_resolver(workspace);

    let reasoning = responses_reasoning_field(generation_policy.reasoning_effort);
    // Tools are passed per call (#2331): a promotion can append to them.
    let build_body = |input: &[serde_json::Value], tools: &[serde_json::Value]| {
        // `store` is set EXPLICITLY (#1526, invariant #5): the Responses API
        // defaults it to `true` (server-side retention). Newt is stateless — it
        // replays the full history here and never uses `previous_response_id` —
        // so retention buys nothing and would leave an unaudited copy of the
        // operator's prompts/source/reasoning on the provider. Policy lives in
        // one place (`responses_wire::STORE_RESPONSE_SERVER_SIDE`).
        let source = responses_source_messages(instructions.as_deref(), input);
        let (wire_instructions, input) = crate::responses_wire::build_responses_input(&source);
        let mut body = serde_json::json!({
            "model": model,
            "input": input,
            "stream": false,
            "store": crate::responses_wire::STORE_RESPONSE_SERVER_SIDE,
        });
        if let Some(ins) = &wire_instructions {
            body["instructions"] = serde_json::json!(ins);
        }
        // Psyche cognition → `reasoning.effort` (omitted entirely when unset).
        if let Some(reasoning) = &reasoning {
            body["reasoning"] = reasoning.clone();
        }
        if !tools.is_empty() {
            body["tools"] = serde_json::json!(tools);
            body["tool_choice"] = serde_json::json!("auto");
        }
        body
    };

    // #1965: the turn's only whole-turn wall-clock signal. The evidenced
    // 32-minute turn emitted none — this file has per-tool `Instant` timers
    // and nothing watching the turn as a whole.
    let turn_started = std::time::Instant::now();
    let mut turn_heartbeat = TurnHeartbeat::default();
    // The same progress tracker, cap renewal, and brake as the chat arms.
    let mut workflow_runtime = WorkflowRuntimeState {
        no_progress: crate::initiative::installed_no_progress(),
        ..Default::default()
    };
    let mut uncorrelatable_batches: u32 = 0;
    let mut current_tool_round_limit = max_tool_rounds;
    let mut selected_source = selected_target::Projection::default();
    let mut observed_facts = semantic_pins::Projection::default();
    for round in 0..usize::MAX {
        let round = round.saturating_sub(output_recovery.skipped_rounds);
        selected_source.refresh(
            &mut input,
            step_ledger,
            workspace,
            &caveats.fs_read,
            worktree_session,
            true,
        );
        observed_facts.planning = output_budget::guidance(
            Some(generation_bounds::output_cap(
                generation_policy.output_allowance,
                None,
                0,
            )?),
            step_ledger,
            &selected_target::root(workspace, worktree_session),
            &caveats.fs_read,
            estimation,
        );
        semantic_pins::refresh(
            &mut observed_facts,
            smart_harness,
            &mut input,
            prompt_context,
            selected_source.current(),
            &turn_claims,
            workspace,
            &caveats.fs_read,
        )?;
        // #2331: a call to an authorized tool whose schema was off the wire
        // promoted it; its schema rides every request from here on.
        if hidden_tools.append_promoted(&mut tools_chat) {
            tools = tools_to_responses(&tools_chat);
            tools_for_estimate = serde_json::Value::Array(tools.clone());
            budget_state.set_tool_schema_tokens(calibrate_up(
                estimate_value_tokens(&tools_for_estimate, estimation),
                cal,
            ));
        }
        // Bounded to ONE line per interval, and the policy is pure over the
        // elapsed it is handed — this reads the clock, `due` does not.
        let turn_elapsed = turn_started.elapsed();
        if let Some(line) = turn_heartbeat.notice(turn_elapsed, round, current_tool_round_limit) {
            print_newt(&line, color, false);
        }
        // FIRST statement of every round: the previous round's completed
        // viewport comes down while the cursor is still just below it — before
        // the cancel checkpoint's return, the trace writer, or any dispatch
        // output can land a canonical line under the frame.
        dismiss_completed_spill(&completed_spill_renderer);
        if !workflow_runtime.admit_round(
            round,
            &mut current_tool_round_limit,
            workflow_grace_rounds,
        ) {
            break;
        }
        if is_cancelled(cancel) {
            return Ok((
                smart_harness::cancelled(smart_harness, &mut end_reason)?,
                false,
                accumulated_usage,
                hallucination_count,
            ));
        }
        // #952/#1669: operator steering, delivered BEFORE this round's model
        // call and AFTER any tool that was already running finished above.
        // Steering changes what the agent does NEXT; it never abandons the
        // turn (that is `cancel`, checked immediately above).
        if drain_steering_into(steering, &mut input, color) > 0 {
            workflow_runtime.note_operator_steering();
        }
        // The drain precedes the gate: steering delivered now resets the brake.
        // U4b: the brake's gate runs EVERY round (see the chat arms).
        if round > 0 {
            no_progress_gate!(
                workflow_runtime,
                action_nudges,
                input,
                end_reason,
                solve_obs,
                accumulated_usage,
                hallucination_count,
                smart_harness,
                (
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification
                ),
                |harness| harness.record_responses_messages(instructions.as_deref(), &input)?
            );
        }
        // #1528: inner recovery loop — a cw-400 (or a tools-unsupported error)
        // retries THIS logical round IN PLACE. Only a COMPLETED dispatch `break`s
        // out and lets `round` advance, so recovery never consumes a tool-capable
        // round (critical at max_tool_rounds == 1 or near the cap): the recovered
        // request is re-sent WITH tools, never demoted to the tools-disabled summary.
        let (json, attempt) = loop {
            // #1528 B3: PROACTIVE pre-dispatch compaction — when the request is
            // LOCALLY known to exceed the budget, compact BEFORE dispatch instead of
            // paying a round-trip to learn it from a cw-400. Reuses the ONE
            // `compact_responses_input` (the SAME path the reactive recovery uses).
            // It fires at the TOP of the inner loop, BEFORE `build_body`, within the
            // SAME iteration — so the outer `round` counter never advances
            // (retry-in-place, the B2 P1 invariant). BEST-EFFORT + BOUNDED: a SINGLE
            // compaction attempt that commits `input` only to a form which fits the
            // post-bridge budget (BHV-BUDGET-004; otherwise `input` is untouched).
            // The `preflight_responses_request` below is the ONE authoritative
            // fail-closed gate: if the request still does not fit — an irreducible
            // head or a fresh, un-summarizable newest tool output — it refuses THERE,
            // with the precise "function outputs were not truncated" message. So this
            // never spins compact→still-too-big→compact and never dispatches oversized.
            // B3-CG-003: the compaction target reserves tool-schema overhead ONLY if
            // THIS request actually carries tools (`tools_supported`) — an
            // unsupported-tools retry sends none, so it must not subtract them.
            // B3-CG-004: `compact_responses_input` is TRANSACTIONAL — on any reject it
            // leaves `input` / `compress_state` / the notice stream untouched; the
            // rejection REASON rides the preflight error chain (item 4), not a notice.
            let mut proactive_rejection: Option<CompactionRejection> = None;
            if let Some(budget) = budget_state.actionable_input_budget() {
                let before = estimate_responses_request_real_tokens(
                    instructions.as_deref(),
                    &input,
                    tools_supported.then_some(tools.as_slice()),
                    estimation,
                    cal,
                );
                if before > budget {
                    let compression = compact_responses_input(
                        Some(&observed_facts),
                        worktree_session,
                        &mut input,
                        instructions.as_deref(),
                        tools_supported.then_some(tools.as_slice()),
                        Some(budget),
                        budget_state.compaction_budget(cal, tools_supported),
                        cal,
                        estimation,
                        task,
                        summary_input_cap_floor_chars,
                        rewrites_history,
                        compaction_store,
                        summarizer,
                        compress_state,
                        color,
                        smart_harness,
                        false,
                    );
                    let Some(outcome) = cancellable(cancel, compression).await else {
                        return Ok((
                            smart_harness::cancelled(smart_harness, &mut end_reason)?,
                            false,
                            accumulated_usage,
                            hallucination_count,
                        ));
                    };
                    // #2555: this loop's ONE compaction entry point
                    // (`compact_responses_input`) reports a committed
                    // compaction as `Compacted` — release repeat-read memos
                    // there, mirroring `record_compaction_artifact`'s hook
                    // in the three legacy chat loops.
                    if matches!(outcome, ResponsesCompaction::Compacted) {
                        repeat_calls.release_read_memos();
                    }
                    proactive_rejection = outcome.rejection();
                }
            }
            // #1528 B5: the ONE typed strict-wire gate. Build the EXACT body, then
            // validate it — the budget-fit refusal is the same `preflight_responses_request`
            // primitive, now wrapped by the full wire-invariant set (store policy,
            // no num_ctx, one instruction source, supported input shapes, correlation,
            // flattened+strict tools, in-session CID markers). A failure dispatches
            // NOTHING and does not advance the round; if compaction could not fit the
            // request, the local reason is attached so the headless error chain
            // explains WHY. Only a `ValidatedResponsesRequest` reaches the dispatcher.
            if let Some(harness) = smart_harness {
                harness.record_responses_messages(instructions.as_deref(), &input)?;
            }
            let mut body = build_body(&input, if tools_supported { &tools } else { &[] });
            let output_cap = generation_bounds::apply_responses(
                &mut body,
                generation_policy.output_allowance,
                generation_window,
                estimate_responses_request_real_tokens(
                    instructions.as_deref(),
                    &input,
                    tools_supported.then_some(tools.as_slice()),
                    estimation,
                    cal,
                ),
            );
            let policy = responses_wire_validation::ResponsesWirePolicy {
                store: crate::responses_wire::STORE_RESPONSE_SERVER_SIDE,
                tools_permitted: true,
                model,
                authoritative_budget: budget_state.actionable_input_budget(),
                calibration: cal,
                estimation,
                spill: spill_store,
                compaction: compaction_store,
            };
            let validated = responses_wire_validation::validate_responses_request(&body, &policy)
                .map_err(|e| match proactive_rejection.take() {
                Some(reason) => anyhow::Error::new(e).context(reason.to_string()),
                None => anyhow::Error::new(e),
            })?;
            observability::observe_output_allowance(&mut solve_obs, Some(output_cap?), true);
            let source = responses_source_messages(instructions.as_deref(), &input);
            let dispatch = dispatch_responses_json(
                &client,
                &responses_url,
                api_key,
                &validated,
                &retry,
                color,
                smart_harness.map(|h| (h, source.as_slice())),
                attempts,
            )
            .await;

            match dispatch {
                Ok(j) => {
                    // Success renews recovery attempts, not the learned budget.
                    cw_retries = 0;
                    break j;
                }
                Err(e) => {
                    if tools_supported && is_tools_unsupported_error(&e) {
                        tools_supported = false;
                        if !tools_unsupported_notified {
                            tools_unsupported_notified = true;
                            print_newt(
                                &format!(
                                "{model} does not support tools — tools disabled for this session"
                            ),
                                color,
                                false,
                            );
                        }
                        continue;
                    }
                    // #1528: graceful context-window overflow recovery on the
                    // Responses wire — parse the model's real limit, tighten the input
                    // ceiling MONOTONICALLY, compact the running history via the shared
                    // `compress::compress` (bridged in/out of the Responses `input`
                    // shape), and re-dispatch. Bounded to 2 recoveries; a numberless
                    // overflow falls back to a derived cap. Mirrors the Chat
                    // Completions path (see #223 + the block above `chat_url`).
                    let overflow = cw_overflow::is_context_overflow(&e.to_string());
                    let round_est_raw = estimate_responses_request_tokens(
                        instructions.as_deref(),
                        &input,
                        tools_supported.then_some(tools.as_slice()),
                        estimation,
                    );
                    // Record the rejected size BEFORE increasing estimation slack.
                    let refused_tokens = cw_overflow::parse_context_window_error(&e.to_string())
                        .map(|(tokens, _)| usize::try_from(tokens).unwrap_or(usize::MAX))
                        .unwrap_or_else(|| calibrate_up(round_est_raw, cal));
                    if overflow {
                        cal = compress_state.calibration.overflow(cal);
                        budget_state.set_tool_schema_tokens(calibrate_up(
                            estimate_value_tokens(&tools_for_estimate, estimation),
                            cal,
                        ));
                    }
                    if cw_retries < 2 {
                        let recovered_window = recover_cw_400.and_then(|f| f(&e, model, &today));
                        if let Some(recovered_budget) = recovered_window
                            .map(|context_window| {
                                budget_state.recovered_budget_for_window(context_window)
                            })
                            .or_else(|| {
                                cw_overflow::core_recover_overflow(
                                    &e.to_string(),
                                    budget_state.soft_send_budget(),
                                    None,
                                )
                                .map(|cap| cap as usize)
                            })
                            .or_else(|| {
                                overflow.then_some(
                                    budget_state
                                        .soft_send_budget()
                                        .unwrap_or_else(|| calibrate_up(round_est_raw, cal)),
                                )
                            })
                            .and_then(|budget| {
                                cw_overflow::recovery_target(
                                    budget,
                                    refused_tokens,
                                    budget_state.actionable_input_budget(),
                                )
                            })
                        {
                            if let Some(context_window) = recovered_window {
                                generation_window = Some(
                                    generation_window
                                        .map_or(context_window, |old| old.min(context_window)),
                                );
                                emit_context_window_400(&mut on_round_usage, context_window);
                            }
                            // Tighten the shared state MONOTONICALLY (a recovery may
                            // only tighten the input budget, never raise it), collapse
                            // the soft budget to the new hard ceiling, and recompute
                            // the authoritative preflight bound — the endpoint's parsed
                            // hard limit is authoritative from here on.
                            budget_state.recover_from_cw400(recovered_budget);
                            // #1528 B3: the compaction "dance" is the ONE shared
                            // `compact_responses_input` — the SAME path the PROACTIVE
                            // pre-dispatch guard uses. A successful compaction (or a
                            // no-op that keeps the round eligible) falls through to the
                            // bounded redispatch below; a refusal / bridge error /
                            // post-fence overflow surfaces the provider's ORIGINAL 400
                            // (ZERO redispatch) with the local compaction reason attached
                            // to the error chain (item 4) — no separate notice.
                            // B3-CG-003: the compaction target reserves tool-schema
                            // overhead ONLY if this recovered request actually carries
                            // tools (`tools_supported`) — after a tools-unsupported error
                            // it does not, so it must not subtract them.
                            let target = context_recovery::target(
                                &input,
                                budget_state.compaction_budget(cal, tools_supported),
                                estimation,
                            );
                            let compression = compact_responses_input(
                                Some(&observed_facts),
                                worktree_session,
                                &mut input,
                                instructions.as_deref(),
                                tools_supported.then_some(tools.as_slice()),
                                budget_state.actionable_input_budget(),
                                target,
                                cal,
                                estimation,
                                task,
                                summary_input_cap_floor_chars,
                                rewrites_history,
                                compaction_store,
                                summarizer,
                                compress_state,
                                color,
                                smart_harness,
                                true,
                            );
                            let Some(outcome) = cancellable(cancel, compression).await else {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Ok((
                                    smart_harness::cancelled(smart_harness, &mut end_reason)?,
                                    false,
                                    accumulated_usage,
                                    hallucination_count,
                                ));
                            };
                            // #2555: same release as the proactive branch above.
                            if matches!(outcome, ResponsesCompaction::Compacted) {
                                repeat_calls.release_read_memos();
                            }
                            match outcome {
                                ResponsesCompaction::Compacted | ResponsesCompaction::NotFired => {}
                                // ZERO second inference: surface the original 400 with the
                                // local compaction context attached for headless callers.
                                other => {
                                    context_recovery::record(
                                        &mut solve_obs,
                                        smart_harness,
                                        round,
                                        cw_retries + 1,
                                        round_est_raw,
                                        None,
                                    )?;
                                    return Err(match other.rejection() {
                                        Some(reason) => e.context(reason.to_string()),
                                        None => e,
                                    });
                                }
                            }
                            let projected = estimate_responses_request_tokens(
                                instructions.as_deref(),
                                &input,
                                tools_supported.then_some(tools.as_slice()),
                                estimation,
                            );
                            if projected >= round_est_raw {
                                context_recovery::record(
                                    &mut solve_obs,
                                    smart_harness,
                                    round,
                                    cw_retries + 1,
                                    round_est_raw,
                                    None,
                                )?;
                                return Err(e);
                            }
                            context_recovery::record(
                                &mut solve_obs,
                                smart_harness,
                                round,
                                cw_retries + 1,
                                round_est_raw,
                                Some(calibrate_up(projected, cal)),
                            )?;
                            cw_retries += 1;
                            continue;
                        }
                    }
                    if overflow {
                        context_recovery::record(
                            &mut solve_obs,
                            smart_harness,
                            round,
                            cw_retries + 1,
                            round_est_raw,
                            None,
                        )?;
                    }
                    return Err(e);
                }
            }
        };

        // Fail-closed decode (invariant #2). A `200 OK` is NOT a completed turn:
        // only affirmative success output decodes to `Ok`. A refusal is the
        // model's final answer for this turn; every other error (provider error,
        // failed / incomplete / non-terminal status, malformed/empty body) is
        // surfaced — never mistaken for a benign empty reply.
        let decoded = crate::responses_wire::decode_response(&json);
        complete_responses_attempt(attempt.as_ref(), &json, &decoded);
        if generation_bounds::output_limited(&json) {
            let usage = crate::responses_wire::decode_usage(&json["usage"]);
            accumulated_usage = merge_round_usage(accumulated_usage, usage);
            if output_recovery.retry(
                json["output"]
                    .as_array()
                    .is_some_and(|items| items.iter().any(|item| item["type"] == "function_call")),
                &mut input,
                smart_harness,
            )? {
                continue;
            }
            let text = finalize_final_text(
                generation_bounds::output_limit_notice(
                    generation_bounds::partial_responses_text(&json),
                    usage,
                ),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            if let Some(slot) = &mut end_reason {
                **slot = Some(crate::TurnEndReason::Failed);
            }
            if let Some(harness) = smart_harness {
                harness.outcome(crate::TurnEndReason::Failed, &text)?;
            }
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
        let refused = matches!(
            decoded,
            Err(crate::responses_wire::ResponseDecodeError::Refused { .. })
        );
        let decoded = match decoded {
            Ok(d) => d,
            Err(crate::responses_wire::ResponseDecodeError::Refused { message, usage })
                if smart_harness.is_some() =>
            {
                crate::responses_wire::DecodedResponse {
                    text: message,
                    tool_calls: Vec::new(),
                    echo: Vec::new(),
                    model: None,
                    usage,
                }
            }
            Err(crate::responses_wire::ResponseDecodeError::Refused { message, usage }) => {
                accumulated_usage = merge_round_usage(accumulated_usage, usage);
                // #1964: this normal (non-cap) finish gets the same claim
                // check + disclosure gate as a cap-exit summary.
                let out = finalize_final_text(
                    FinalReply::from(message).with_notice("The model refused the request.".into()),
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                return Ok((out, false, accumulated_usage, hallucination_count));
            }
            Err(e) => {
                if let Some(harness) = smart_harness {
                    harness.provider_failure(&e.to_string())?;
                }
                return Err(anyhow::anyhow!("Responses turn not usable: {e}"));
            }
        };
        compress_state.calibration.observe(
            decoded.usage.map(|usage| usage.input_tokens),
            estimate_responses_request_tokens(
                instructions.as_deref(),
                &input,
                tools_supported.then_some(tools.as_slice()),
                estimation,
            ),
        );
        cal = compress_state.calibration.ratio(estimate_ratio);
        budget_state.set_tool_schema_tokens(calibrate_up(
            estimate_value_tokens(&tools_for_estimate, estimation),
            cal,
        ));
        accumulated_usage = merge_round_usage(accumulated_usage, decoded.usage);
        let (text, calls, echo) = (decoded.text, decoded.tool_calls, decoded.echo);

        if debug {
            let excerpt: String = text.chars().take(80).collect();
            print_debug(
                &format!(
                    "responses round {round}: function_calls={} content={excerpt:?}",
                    calls.len()
                ),
                color,
            );
        }

        if calls.is_empty() {
            if let Some(mut nudge) = capability_evidence.correction(
                &text,
                &tools_chat,
                &mut probe_correction_used,
                !refused
                    && tools_supported
                    && workflow_runtime.has_next_round(
                        round,
                        current_tool_round_limit,
                        workflow_grace_rounds,
                    )
                    && !is_cancelled(cancel),
            ) {
                if let Some(harness) = smart_harness {
                    nudge = harness.correct_answer(&text, &nudge)?;
                }
                input.extend(echo.clone());
                input.push(serde_json::json!({"role":"assistant", "content":text}));
                input.push(serde_json::json!({"role":"user", "content":nudge}));
                continue;
            }
            if let Some(harness) = smart_harness {
                let more = workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                );
                let control = harness
                    .classify(&text, narration_nudge_cap, more, cancel)
                    .await?;
                let control = harness
                    .verify_answer(
                        control,
                        self_verify::Concluding {
                            messages: &input,
                            workspace,
                            task,
                            rounds_left: more,
                            round,
                            ledger: &verification,
                            solve_obs: solve_obs.as_deref_mut(),
                        },
                        smart_verify,
                        &text,
                    )
                    .await?;
                let (text, reason) = match control {
                    smart_harness::Control::Continue(nudge) => {
                        input.extend(echo.clone());
                        input.push(serde_json::json!({"role":"assistant", "content":text}));
                        input.push(serde_json::json!({"role":"user", "content":nudge}));
                        continue;
                    }
                    smart_harness::Control::Answer => {
                        (FinalReply::from(text), crate::TurnEndReason::Completed)
                    }
                    smart_harness::Control::Finish { text, reason } => (text, reason),
                };
                if let Some(slot) = &mut end_reason {
                    **slot = Some(reason);
                }
                let text = finalize_final_text(
                    text,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                harness.outcome(reason, &text)?;
                return Ok((text, false, accumulated_usage, hallucination_count));
            }

            if !is_cancelled(cancel)
                && readonly_completion_pending(prompt_disposition, &nudge_classifier, &text)
            {
                let more_rounds = workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                );
                if retry_readonly_completion(
                    &mut input,
                    &text,
                    Some(&echo),
                    &mut readonly_completion_retried,
                    more_rounds,
                ) {
                    continue;
                }
                let out = readonly_completion_handoff(
                    &text,
                    &mut end_reason,
                    more_rounds,
                    workspace,
                    &caveats.fs_read,
                    &capability_evidence,
                    disclosure,
                    &turn_claims,
                    &verification,
                );
                return Ok((out, false, accumulated_usage, hallucination_count));
            }
            if should_ground_unverified_run_command_blocker(
                &text,
                &tools_chat,
                run_command_denial_observed,
                exec_grounding_turn && tools_supported,
                unverified_exec_blocker_nudges,
                workflow_runtime.has_next_round(
                    round,
                    current_tool_round_limit,
                    workflow_grace_rounds,
                ),
            ) {
                if debug {
                    print_debug(
                        "unsupported run_command blocker — requiring a ground-truth probe",
                        color,
                    );
                }
                input.push(serde_json::json!({ "role": "assistant", "content": text }));
                input.push(serde_json::json!({
                    "role": "user",
                    "content": format!(
                        "{} {}",
                        compress::LOOP_GUIDANCE_PREFIX,
                        run_command_ground_truth_nudge()
                    )
                }));
                unverified_exec_blocker_nudges += 1;
                continue;
            }
            // The decoder guarantees affirmative output here (text or calls); with
            // no calls, `text` is non-empty — return it as the turn's answer.
            // #1964: this normal (non-cap) finish gets the same claim check
            // + disclosure gate as a cap-exit summary.
            let text = finalize_final_text(
                text,
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            return Ok((text, false, accumulated_usage, hallucination_count));
        }

        // Echo the model's reasoning + function_call items back into the running
        // input (in output order, so each call keeps its required reasoning item),
        // then run each call and append its function_call_output.
        // Phase 1 (invariant #3, BATCH level): validate the ENTIRE batch BEFORE
        // echoing anything into `input` and before any side effect. Nothing is
        // echoed until validation decides, so a correlation-impossible batch
        // leaves `input` untouched and no follow-up request is issued.
        let extracted: Vec<(Option<&str>, Option<&str>, &serde_json::Value)> = calls
            .iter()
            .map(|c| {
                (
                    c["call_id"].as_str().or_else(|| c["id"].as_str()),
                    c["name"].as_str(),
                    &c["arguments"],
                )
            })
            .collect();
        let validated = match tools::validate_tool_call_batch(&extracted, true) {
            Ok(v) => {
                uncorrelatable_batches = 0;
                v
            }
            Err(tools::BatchRejection::CorrelationImpossible(reason)) => {
                // A missing/blank/duplicate call id: a `function_call_output`
                // cannot be correlated. Never fabricate an id — re-ask, or abort
                // once the budget is spent. Nothing was echoed, so `input` needs
                // only the plain user message.
                let reask = tools::reask_uncorrelatable(
                    &mut uncorrelatable_batches,
                    &reason,
                    smart_harness,
                    tool_events.as_deref_mut(),
                )?;
                input.push(serde_json::json!({"role": "user", "content": reask}));
                continue;
            }
            Err(tools::BatchRejection::ContentInvalid(reason)) => {
                uncorrelatable_batches = 0;
                if let Some(harness) = smart_harness {
                    harness.reject_tools(&reason, true)?;
                }
                // ids are valid + unique → echo the calls and a correctly keyed
                // rejection per call, then re-dispatch so the model can retry.
                for item in &echo {
                    input.push(item.clone());
                }
                for call in &calls {
                    let call_id = call["call_id"]
                        .as_str()
                        .or_else(|| call["id"].as_str())
                        .unwrap_or("");
                    print_synthetic_tool_result(
                        "(rejected tool-call batch)",
                        &serde_json::Value::Null,
                        workspace,
                        &reason,
                        color,
                        &completed_spill_renderer,
                    );
                    if let Some(rec) = tool_events.as_deref_mut() {
                        rec.push(crate::ToolEvent::from_call(
                            "(rejected tool-call batch)",
                            &serde_json::Value::Null,
                            false,
                            Some(0),
                        ));
                    }
                    smart_harness::push_tool_message(
                        &mut input,
                        serde_json::json!({
                            "type": "function_call_output",
                            "call_id": call_id,
                            "output": format!("tool-call batch rejected before execution: {reason}"),
                        }),
                        smart_harness,
                        true,
                        "(rejected tool-call batch)",
                    )?;
                }
                continue;
            }
        };
        // Every call is valid: echo the reasoning + function_call items (in output
        // order, so each call keeps its required reasoning item), then execute.
        for item in &echo {
            input.push(item.clone());
        }
        commit_tool_round_narration(&text, false, completed_spill_renderer.as_deref(), color);
        let batch = smart_harness
            .map(|harness| {
                let mut messages = Vec::with_capacity(input.len() + 1);
                if let Some(text) = &instructions {
                    messages.push(serde_json::json!({"role":"system","content":text}));
                }
                messages.extend_from_slice(&input);
                harness.tool_batch(&validated, &messages)
            })
            .transpose()?;
        let mut round_modified_workspace = false;
        let mut round_progress = false;
        let mut round_succeeded = false;
        let mut tool_warnings = Vec::new();
        // Phase 2: execute in order.
        for (call_index, (call, vc)) in calls.iter().zip(validated.iter()).enumerate() {
            let call_id = vc.call_id.as_str();
            let name = vc.name.as_str();
            let args = vc.args.clone();
            announce_tool_activity(name);
            // Per-tool head: any frame from the PREVIOUS tool in this batch
            // comes down before this iteration's first writer (the debug /
            // trace echoes below print BEFORE the wired `call()` erase).
            dismiss_completed_spill(&completed_spill_renderer);
            if trace {
                print_trace(
                    &format!(
                        "raw function_call: {}",
                        serde_json::to_string(call).unwrap_or_else(|_| "?".into())
                    ),
                    color,
                );
            }
            if is_hallucination(name, &args) {
                hallucination_count += 1;
            }
            // #2637: never refuse an exact bare re-read — serve it silently
            // from the memo when the file's actual current content still
            // matches; otherwise fall through to a real read below.
            if let Some(content) =
                repeat_calls.cached_read(name, &args, ReadScope { workspace, caveats })
            {
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &content,
                    color,
                    &completed_spill_renderer,
                );
                if let Some(rec) = tool_events.as_deref_mut() {
                    rec.push(crate::ToolEvent::from_cache(name, &args));
                }
                let offloaded =
                    maybe_offload_tool_result(name, content, tool_offload, spill_store, disclosure);
                smart_harness::push_tool_resolution(
                    &mut input,
                    serde_json::json!({
                        "type": "function_call_output",
                        "call_id": call_id,
                        "output": offloaded,
                    }),
                    batch.as_ref(),
                    call_index,
                )?;
                continue;
            }
            // Step 27.3/#771: short-circuit selected exact repeats (Responses
            // shape: echo a function_call_output with the steer).
            // Counted as a hallucination above first when applicable.
            if let Some(steer) = repeat_calls.repeat_steer(name, &args) {
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &steer,
                    color,
                    &completed_spill_renderer,
                );
                if let Some(rec) = tool_events.as_deref_mut() {
                    rec.push(crate::ToolEvent::from_call(name, &args, false, Some(0)));
                }
                smart_harness::push_tool_resolution(
                    &mut input,
                    serde_json::json!({
                        "type": "function_call_output",
                        "call_id": call_id,
                        "output": steer,
                    }),
                    batch.as_ref(),
                    call_index,
                )?;
                continue;
            }
            let invocation = batch
                .as_ref()
                .map(|batch| batch.start(call_index, disclosure))
                .transpose()?;
            record_organic_note_use(name, &note_sink, &mut note_nudge);
            let before_change =
                progress_workspace_state(name, &args, workspace, &caveats.fs_read).await;
            ledger_note_write(write_ledger, name, &args, workspace);
            let tool_t0 = std::time::Instant::now();
            let execution = std::sync::OnceLock::new();
            let retry_authorized = std::sync::OnceLock::new();
            let routed_to = std::sync::OnceLock::new();
            let governed_pr = std::sync::OnceLock::new();
            let report_capture = std::sync::Mutex::new(observed_report::Capture::default());
            let command_directory = std::sync::OnceLock::new();
            let attribution_epoch = AttributionEpoch::new(attribution, git_tool, model, name);
            // #727: intercept the read-only budget self-read (see the Ollama path).
            // The Responses loop has no PromptTracker, so `used` is the chars/4
            // estimate of the ACTUAL Responses request; num_ctx is normally unset
            // here, so the report is honestly ceiling-less.
            let result = if tools::is_context_remaining_call(name) {
                // #1528: the self-read must describe the NEXT dispatch, so it reads
                // the SAME derivation the preflight enforces against — the
                // `actionable_input_budget` (hard ceiling / soft send / mid-loop
                // trim, the value dispatch refuses at) as the ceiling, and the SAME
                // CALIBRATED real-token estimate of the exact request (instructions
                // + the running Responses `input` + the real Responses-wire tool
                // schemas, respecting tools-disabled) as `used` — via the shared
                // `responses_context_remaining_report`. Both operate in real-token
                // currency (BHV-BUDGET-001/002/003). The pre-fix path subtracted the
                // RAW chars/4 estimate from the calibrated ceiling — over-reporting
                // remaining by the calibration factor — and, earlier, read
                // `learned_hard_ceiling` and the Chat-shaped catalog.
                let report = responses_context_remaining_report(
                    instructions.as_deref(),
                    &input,
                    tools_supported.then_some(tools.as_slice()),
                    &budget_state,
                    cal,
                    estimation,
                    low_budget_pct,
                );
                if let Some(invocation) = &invocation {
                    invocation.host();
                    invocation.observe(&report, None, spill_store)?;
                }
                print_synthetic_tool_result(
                    name,
                    &args,
                    workspace,
                    &report,
                    color,
                    &completed_spill_renderer,
                );
                report
            } else {
                // #1947: distil the ledger BEFORE the call. What a
                // `render_report` in THIS call can be checked against is what
                // the turn has already done — the events for this very call
                // are pushed after it returns.
                let tool_evidence = tool_events
                    .as_deref()
                    .map(|e| capability_check::Evidence::from_events(e));
                let Some(result) = tools::execute_tool_with_collaborators(
                    name,
                    &args,
                    workspace,
                    color,
                    tool_output_lines,
                    caveats,
                    mcp,
                    tools::ToolCollaborators {
                        command_budget,
                        shell_dialect,
                        read_history: Some(&mut read_history),
                        default_command_cwd,
                        worktree_session,
                        invocation: invocation.as_ref(),
                        build_check_cmd: build_check_cmd.as_deref(),
                        tool_evidence: tool_evidence.as_ref(),
                        // Reborrow + re-coerce: shortens the trait-object
                        // lifetime to this call (Option<&mut dyn _> is
                        // invariant, so the longer ChatCtx lifetime can't
                        // unify directly).
                        note_sink: note_sink
                            .as_deref_mut()
                            .map(|s| &mut *s as &mut dyn NoteSink),
                        recall_source,
                        memory_source,
                        prompt_context: Some(prompt_context),
                        artifact_context,
                        artifact_sink,
                        // #263 prompted grants — same reborrow pattern.
                        permission_gate: permission_gate
                            .as_deref_mut()
                            .map(|g| &mut *g as &mut dyn PermissionGate),
                        exec_floor,
                        git_tool,
                        crew_runner,
                        scratchpad_store,
                        code_search,
                        where_is,
                        nav,
                        experience_store,
                        step_ledger,
                        operating_mode_control,
                        plan_mode_control,
                        plan_draft_sink,
                        spill_store,
                        persona_tools,
                        hidden_tools: Some(&hidden_tools),
                        live_tool_output: live_tool_output.clone(),
                        completed_spill_renderer: completed_spill_renderer.clone(),
                        execution: Some(&execution),
                        retry_authorized: Some(&retry_authorized),
                        governed_pr: Some(&governed_pr),
                        report_capture: Some(&report_capture),
                        command_directory: Some(&command_directory),
                        routed_to: Some(&routed_to),
                        pending_rerun: Some(&mut pending_rerun),
                    },
                    tool_offload,
                    prompt_disposition,
                    cancel,
                )
                .await?
                else {
                    return Ok((
                        smart_harness::cancelled(smart_harness, &mut end_reason)?,
                        false,
                        accumulated_usage,
                        hallucination_count,
                    ));
                };
                result
            };
            if debug {
                // This line lands directly below the viewport `result` just
                // painted — take the frame down first or its later rewind
                // erases this line and strands frame rows.
                dismiss_completed_spill(&completed_spill_renderer);
                let excerpt: String = result.chars().take(120).collect();
                print_debug(&format!("tool result: {excerpt:?}"), color);
            }
            // Step 27.3/#771: classify once; remember repeat-steered outcomes
            // (mirrors Ollama path).
            let ok = tools::tool_ok(&result, execution.get().copied());
            round_succeeded |= ok;
            let after_change = if before_change.is_some() {
                progress_workspace_state(name, &args, workspace, &caveats.fs_read).await
            } else {
                None
            };
            round_modified_workspace |=
                workflow_runtime.record_workspace_change(before_change, after_change);
            round_progress |= workflow_runtime.record_observation(
                name,
                &args,
                &result,
                ok,
                execution.get().copied(),
                routed_to.get(),
            );
            attribution_epoch.finish(&args, ok);
            run_command_denial_observed |= run_command_result_is_denial(name, ok, &result);
            capability_evidence.record(name, ok, execution.get().copied());
            repeat_calls.record(
                name,
                &args,
                ok,
                &result,
                execution.get().copied(),
                ReadScope { workspace, caveats },
            );
            repeat_calls.permit_authorized_retry(name, &args, &retry_authorized);
            append_clean_build_warning(
                if batch.is_some() {
                    &mut tool_warnings
                } else {
                    &mut input
                },
                &mut clean_build,
                &args,
                None,
            )?;
            record_completed_tool_event(
                &mut tool_events,
                name,
                &args,
                ok,
                execution.get().copied(),
                tool_t0,
            );
            turn_claims.observe_report(
                workspace,
                &caveats.fs_read,
                &report_capture.lock().expect("report capture"),
                execution.get().copied(),
                governed_pr.get(),
            );
            if let Some(outcome) = governed_pr.get() {
                verification.record_publication_outcome(outcome);
            }
            if ok {
                if let Some(directory) = command_directory.get() {
                    verification.record_command_directory(directory);
                }
            }
            verification
                .observe_routed(
                    name,
                    &args,
                    ok,
                    execution.get().copied(),
                    workspace,
                    routed_to.get(),
                )
                .await;
            record_phantom_reach(
                &mut phantom_reaches,
                name,
                &args,
                &result,
                ok,
                advertise_team,
            );
            observed_paths.record(&result, &mut observed_resolver);
            smart_harness::push_tool_return(
                &mut input,
                serde_json::json!({
                    "type": "function_call_output",
                    "call_id": call_id,
                    // Step 26.3 (#584): see the Ollama path (Responses output shape).
                    "output": smart_harness::tool_result(name, result, tool_offload, spill_store, disclosure, invocation.as_ref())?,
                }),
                invocation.as_ref(),
            )?;
        }
        for message in tool_warnings {
            smart_harness::push_tool_message(
                &mut input,
                message,
                smart_harness,
                true,
                "build guidance",
            )?;
        }
        if let Some(harness) = smart_harness {
            harness.record_responses_messages(instructions.as_deref(), &input)?;
        }
        if round_succeeded {
            output_recovery.completed_tool_round();
        }
        workflow_runtime.record_round_outcome(round_modified_workspace, round_progress);
        if let Some(text) = pending_plan_approval_handoff(
            plan_mode_control,
            PlanRoundFacts {
                disposition: prompt_disposition,
                step_ledger,
                plan_at_turn_start: &plan_at_turn_start,
                progressed: round_modified_workspace || round_progress,
            },
            smart_harness,
            cancel,
            &mut end_reason,
        )? {
            dismiss_completed_spill(&completed_spill_renderer);
            let text = finalize_final_text(
                FinalReply::harness(text),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
    }

    // The Responses wire reaches the same semantic cap as the chat backends:
    // ask for a grounded progress handoff, then return it as a resumable pause.
    // Keep the pre-summary usage separate so the footer's "across N rounds"
    // count does not include this extra tools-disabled completion.
    let cap_accumulated = accumulated_usage;
    let progress = cap_exit_progress(worktree_session, step_ledger, scratchpad_store);
    // #2374: a failed check at the round limit is a scored repair exhaustion.
    let cap_reason = verification
        .cap_exit_reason(
            workspace,
            smart_harness.is_some() && smart_verify,
            current_tool_round_limit,
            solve_obs.as_deref_mut(),
        )
        .await;
    if let Some(hit) = &mut round_cap_hit {
        **hit = true;
    }
    if let Some(harness) = smart_harness {
        harness.record_responses_messages(instructions.as_deref(), &input)?;
        let text = cap_exit_fallback(
            current_tool_round_limit,
            accumulated_usage,
            repeat_calls.total_failures(),
            progress.as_deref(),
        );
        let text = finalize_final_text(
            text,
            workspace,
            &caveats.fs_read,
            &capability_evidence,
            disclosure,
            &turn_claims,
            &verification,
        );
        harness.outcome(cap_reason, &text)?;
        if let Some(slot) = &mut end_reason {
            **slot = Some(cap_reason);
        }
        return Ok((text, false, accumulated_usage, hallucination_count));
    }

    let observed = observed_paths.into_vec();
    input.push(serde_json::json!({
        "role": "user",
        "content": cap_exit_nudge(current_tool_round_limit, progress.as_deref(), &observed),
    }));

    // #1528 B3: proactively compact the tools-DISABLED final summary if it is
    // LOCALLY over budget. No round to protect (the loop is over), so it is a
    // BEST-EFFORT, single-shot compaction; the `preflight_responses_request` below
    // is the ONE authoritative fail-closed gate. Every tools argument is `None` —
    // the summary sends NO tool schemas — so the estimate drops them AND the
    // compaction target does NOT reserve their overhead (`with_tool_schemas =
    // false`), avoiding over-compaction (req #7).
    let mut summary_rejection: Option<CompactionRejection> = None;
    if let Some(budget) = budget_state.actionable_input_budget() {
        let before = estimate_responses_request_real_tokens(
            instructions.as_deref(),
            &input,
            None,
            estimation,
            cal,
        );
        if before > budget {
            let compression = compact_responses_input(
                Some(&observed_facts),
                worktree_session,
                &mut input,
                instructions.as_deref(),
                None,
                Some(budget),
                budget_state.compaction_budget(cal, false),
                cal,
                estimation,
                task,
                summary_input_cap_floor_chars,
                rewrites_history,
                compaction_store,
                summarizer,
                compress_state,
                color,
                smart_harness,
                false,
            );
            let Some(outcome) = cancellable(cancel, compression).await else {
                return Ok((
                    smart_harness::cancelled(smart_harness, &mut end_reason)?,
                    false,
                    accumulated_usage,
                    hallucination_count,
                ));
            };
            // #2555: same release as the proactive branch above.
            if matches!(outcome, ResponsesCompaction::Compacted) {
                repeat_calls.release_read_memos();
            }
            summary_rejection = outcome.rejection();
        }
    }

    // Round cap: the last tool's completed viewport is still up and nothing
    // has written since — dismiss before any summary output.
    dismiss_completed_spill(&completed_spill_renderer);
    // One final tools-disabled call for a summary answer (mirrors
    // the chat path's final_summary, in the Responses shape). #1528 B5: the SAME
    // typed strict-wire gate the rounds use, with `tools_permitted = false` so the
    // final summary can carry NO tools; a proactive-compaction reason (if any) rides
    // its error chain. Only a `ValidatedResponsesRequest` reaches the dispatcher.
    let mut body = build_body(&input, &[]);
    let output_cap = generation_bounds::apply_responses(
        &mut body,
        generation_policy.output_allowance,
        generation_window,
        estimate_responses_request_real_tokens(
            instructions.as_deref(),
            &input,
            None,
            estimation,
            cal,
        ),
    )?;
    observability::observe_output_allowance(&mut solve_obs, Some(output_cap), true);
    let policy = responses_wire_validation::ResponsesWirePolicy {
        store: crate::responses_wire::STORE_RESPONSE_SERVER_SIDE,
        tools_permitted: false,
        model,
        authoritative_budget: budget_state.actionable_input_budget(),
        calibration: cal,
        estimation,
        spill: spill_store,
        compaction: compaction_store,
    };
    let validated = match responses_wire_validation::validate_responses_request(&body, &policy) {
        Ok(validated) => validated,
        Err(e) => {
            let error = match summary_rejection.take() {
                Some(reason) => anyhow::Error::new(e).context(reason.to_string()),
                None => anyhow::Error::new(e),
            };
            tracing::warn!(
                error = %error,
                "Responses cap-exit summary validation failed; returning captured progress"
            );
            let text = finalize_final_text(
                cap_exit_fallback(
                    current_tool_round_limit,
                    cap_accumulated,
                    repeat_calls.total_failures(),
                    progress.as_deref(),
                ),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            if let Some(slot) = &mut end_reason {
                **slot = Some(cap_reason);
            }
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
    };
    // Shared retrying dispatch (R5): the tools-disabled final summary retries
    // transient transport failures exactly like every round, so a 500 / timeout /
    // reset on the LAST request no longer discards the turn after all tool rounds
    // were spent.
    let summary_estimate =
        estimate_responses_request_tokens(instructions.as_deref(), &input, None, estimation);
    let source = responses_source_messages(instructions.as_deref(), &input);
    let (json, attempt) = match dispatch_responses_json(
        &client,
        &responses_url,
        api_key,
        &validated,
        &retry,
        color,
        smart_harness.map(|h| (h, source.as_slice())),
        attempts,
    )
    .await
    {
        Ok(dispatched) => dispatched,
        Err(error) => {
            if crate::retry::classify(&error) == crate::retry::Retryability::ContextExceeded {
                context_recovery::terminal_optional(
                    &mut solve_obs,
                    compress_state,
                    cal,
                    current_tool_round_limit,
                    cw_retries + 1,
                    summary_estimate,
                )?;
            }
            tracing::warn!(
                error = %error,
                "Responses cap-exit summary dispatch failed; returning captured progress"
            );
            let mut reply = cap_exit_fallback(
                current_tool_round_limit,
                cap_accumulated,
                repeat_calls.total_failures(),
                progress.as_deref(),
            );
            generation_bounds::append_notice(&mut reply, &error);
            let text = finalize_final_text(
                reply,
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            if let Some(slot) = &mut end_reason {
                **slot = Some(cap_reason);
            }
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
    };
    // Fail closed on provider output: unusable text never becomes the model's
    // answer. At this already-reached cap, however, the deterministic progress
    // handoff is still a successful paused turn so the interactive caller can
    // persist it and retain the continuation link.
    let decoded = crate::responses_wire::decode_response(&json);
    complete_responses_attempt(attempt.as_ref(), &json, &decoded);
    if generation_bounds::output_limited(&json) {
        let usage = crate::responses_wire::decode_usage(&json["usage"]);
        accumulated_usage = merge_round_usage(accumulated_usage, usage);
        let text = finalize_final_text(
            generation_bounds::output_limit_notice(
                generation_bounds::partial_responses_text(&json),
                usage,
            ),
            workspace,
            &caveats.fs_read,
            &capability_evidence,
            disclosure,
            &turn_claims,
            &verification,
        );
        if let Some(slot) = &mut end_reason {
            **slot = Some(crate::TurnEndReason::Failed);
        }
        return Ok((text, false, accumulated_usage, hallucination_count));
    }
    let decoded = match decoded {
        Ok(d) => d,
        Err(crate::responses_wire::ResponseDecodeError::Refused { message, usage }) => {
            accumulated_usage = merge_round_usage(accumulated_usage, usage);
            let text = cap_exit_progress_handoff(
                current_tool_round_limit,
                cap_accumulated,
                &message,
                false,
                progress.as_deref(),
            );
            let text = finalize_final_text(
                text,
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            if let Some(slot) = &mut end_reason {
                **slot = Some(cap_reason);
            }
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
        Err(error) => {
            tracing::warn!(
                error = %error,
                "Responses cap-exit summary decode failed; returning captured progress"
            );
            let text = finalize_final_text(
                cap_exit_fallback(
                    current_tool_round_limit,
                    cap_accumulated,
                    repeat_calls.total_failures(),
                    progress.as_deref(),
                ),
                workspace,
                &caveats.fs_read,
                &capability_evidence,
                disclosure,
                &turn_claims,
                &verification,
            );
            if let Some(slot) = &mut end_reason {
                **slot = Some(cap_reason);
            }
            return Ok((text, false, accumulated_usage, hallucination_count));
        }
    };
    accumulated_usage = merge_round_usage(accumulated_usage, decoded.usage);
    let text = cap_exit_model_reply(
        current_tool_round_limit,
        cap_accumulated,
        &decoded.text,
        progress.as_deref(),
    );
    let text = finalize_final_text(
        text,
        workspace,
        &caveats.fs_read,
        &capability_evidence,
        disclosure,
        &turn_claims,
        &verification,
    );
    if let Some(slot) = &mut end_reason {
        **slot = Some(cap_reason);
    }
    Ok((text, false, accumulated_usage, hallucination_count))
}

/// Whether the reasoning spinner is enabled: `NEWT_THINKING` (set by
/// `/thinking`) overrides `[tui] thinking`; default on.
///
/// Public because `/settings thinking` must report what the setting IS, and
/// this is the one function that owns the precedence. A second reading of
/// `NEWT_THINKING` in the form would show `on` while `[tui] thinking = "off"`
/// quietly won (#1981).
#[must_use]
pub fn thinking_mode(report: &mut dyn FnMut(crate::tty::Notice<'static>)) -> crate::ThinkingMode {
    match std::env::var("NEWT_THINKING").ok().as_deref() {
        Some("off") => return crate::ThinkingMode::Off,
        // `stream` asks for the UNBOUNDED cargo-style trickle by name; plain
        // `on` asks to see the reasoning and gets the bounded default.
        Some("stream") => return crate::ThinkingMode::Stream,
        Some("on" | "fold") => return crate::ThinkingMode::Fold,
        _ => {}
    }
    crate::Config::resolve_unpublished(report)
        .ok()
        .and_then(|c| c.tui)
        .map(|t| t.thinking)
        .unwrap_or_default()
}

/// Whether reasoning is displayed AT ALL — the spinner gate.
///
/// Deliberately not `mode == Stream`. Both display modes show the live
/// spinner; they differ only in how much of the body reaches scrollback. When
/// `Fold` was added, leaving this as an equality against `Stream` would have
/// turned the new DEFAULT into "no thinking spinner, ever" with no compile
/// error anywhere — the gate-collapse this split exists to prevent.
#[must_use]
pub fn thinking_stream_enabled() -> bool {
    display::with_migration_notices(thinking_mode) != crate::ThinkingMode::Off
}

/// Commit a complete reasoning body as a fold block.
///
/// The non-streaming half of the same treatment `ReasoningTrickle` gives a
/// stream: a whole body arrives at once, so the budget is spent in one pass
/// rather than line by line. Both end at the same closing line, and both route
/// the count through [`display::Fold`], so the two wires cannot drift into two
/// different ways of saying the same thing.
fn commit_reasoning_fold(
    reasoning: Option<String>,
    elapsed: std::time::Duration,
    retain: Option<&dyn CompletedSpillRenderer>,
    color: bool,
) {
    if display::with_migration_notices(thinking_mode) == crate::ThinkingMode::Off {
        return;
    }
    let Some(reasoning) = reasoning.filter(|r| !r.trim().is_empty()) else {
        return;
    };
    let budget = if display::with_migration_notices(thinking_mode) == crate::ThinkingMode::Fold {
        display::spill_lines()
    } else {
        0
    };
    let mut fold = display::ThinkingFold::default();
    let mut shown: Vec<String> = Vec::new();
    for line in reasoning.lines().filter(|l| !l.trim().is_empty()) {
        if fold.offer(line, budget) {
            shown.push(format!("  {line}"));
        }
    }
    // Retain BEFORE printing the handle, so the id names a body that is already
    // there rather than one that is about to be.
    let retained = retain.and_then(|r| r.retain_completed(fold.body()));
    let hint = retained
        .zip(retain)
        .map(|(id, renderer)| renderer.recovery_hint(id));
    let recovery = hint
        .as_deref()
        .map_or_else(display::Recovery::default, display::Recovery::Command);
    if let Some(closing) = fold.closing_line(elapsed, recovery) {
        shown.push(closing);
    }
    if shown.is_empty() {
        return;
    }
    let block = shown.join("\n");
    emit_notice_line(crate::tty::Level::Thinking, "", &block, color);
}

/// One permanent, arbiter-cooperating stdout line in a named register: live
/// ephemerals (a tool or thinking spinner) are erased first, and nothing
/// gates on capability, so a piped or headless run receives the same bytes
/// the `⚙` header does. Reasoning folds, and the tool-round narration below,
/// share this one writer so the two cannot drift into two ways of saying it.
fn emit_notice_line(level: crate::tty::Level, glyph: &str, text: &str, color: bool) {
    let notice = crate::tty::Notice::new(level, glyph, text).gap(2);
    crate::tty::Terminal::emit_line(crate::tty::Sink::Stdout, notice.writer(color));
}

/// The prose a model sent WITH this tool batch — what every loop used to
/// replay into history and show to nobody — bounded the way a tool result
/// and a reasoning block are: the first `[tui] spill_lines` rows commit, the
/// rest are retained behind the one fold marker so `/spill open <id>` raises
/// the whole of it, and the conversation spine is never buried. Rows are
/// `▹`-glyphed, the hollow sibling of the `▸` reply marker, in the theme's
/// `narration` colour, so the model's interim voice is told apart from its
/// reply, its reasoning, and the operator's own text. Skipped when the wire
/// already streamed the text live (Anthropic) and when nothing readable
/// remains once the call text itself is dropped.
fn commit_tool_round_narration(
    content: &str,
    already_printed: bool,
    retain: Option<&dyn CompletedSpillRenderer>,
    color: bool,
) {
    emit_tool_round_narration(
        content,
        already_printed,
        retain,
        display::reply_cols(crate::tty::term_cols()),
        display::spill_lines(),
        |level, glyph, text| emit_notice_line(level, glyph, text, color),
    );
}

/// The production narration path with layout and output injected for testing.
fn emit_tool_round_narration(
    content: &str,
    already_printed: bool,
    retain: Option<&dyn CompletedSpillRenderer>,
    width: usize,
    budget: usize,
    mut emit: impl FnMut(crate::tty::Level, &str, &str),
) {
    if already_printed {
        return;
    }
    let rows = display::tool_round_prose(content);
    if rows.is_empty() {
        return;
    }
    let rendered: Vec<_> = rows
        .iter()
        .flat_map(|row| crate::tty::wrap_line(row, width))
        .collect();
    let shown = if budget == 0 {
        rendered.len()
    } else {
        rendered.len().min(budget)
    };
    for (i, line) in rendered.iter().take(shown).enumerate() {
        let glyph = if i == 0 { "▹" } else { " " };
        emit(crate::tty::Level::Narration, glyph, line);
    }
    let hidden = rendered.len() - shown;
    if hidden == 0 {
        return;
    }
    // Retain BEFORE printing the marker, so the id names a body that is
    // already there — the same order the reasoning fold keeps.
    let body = rows.join("\n");
    let retained = retain.and_then(|r| r.retain_completed(&body));
    let hint = retained
        .zip(retain)
        .map(|(id, renderer)| renderer.recovery_hint(id));
    let recovery = hint
        .as_deref()
        .map_or_else(display::Recovery::default, display::Recovery::Command);
    emit(
        crate::tty::Level::Dim,
        "▲",
        &display::Fold::lines(hidden, recovery).marker(),
    );
}

/// The streaming half of a [`ThinkingFold`]: it owns the partial-line buffer
/// and the decision of what reaches the spinner.
///
/// The split matters because reasoning arrives in token-sized chunks with no
/// respect for line boundaries, while the budget is counted in LINES. This
/// holds the tail until its newline — the same shape `Spinner::detail` already
/// uses internally, and the reason the two must not both buffer.
#[derive(Default)]
struct ReasoningTrickle {
    fold: display::ThinkingFold,
    /// Partial line awaiting its newline.
    partial: String,
}

impl ReasoningTrickle {
    /// Feed a chunk. Completed lines within the budget go to the spinner with
    /// the thinking style; the rest are retained by the fold and never printed.
    fn feed(&mut self, spinner: &crate::tty::Spinner, chunk: &str, budget: usize) {
        self.partial.push_str(chunk);
        while let Some(nl) = self.partial.find('\n') {
            let line: String = self.partial.drain(..=nl).collect();
            let trimmed = line.trim_end_matches(['\n', '\r']).to_string();
            if trimmed.trim().is_empty() {
                continue;
            }
            if self.fold.offer(&trimmed, budget) {
                // Hand back the newline `detail` splits on, so the spinner's
                // own buffering sees exactly one complete line.
                spinner.detail(&format!("{trimmed}\n"));
            }
        }
    }

    /// Commit the closing line, retaining the body so its handle is real.
    ///
    /// Written straight to stdout rather than through the spinner, because the
    /// spinner is about to be torn down and this line is durable transcript,
    /// not progress.
    fn close(
        &mut self,
        elapsed: std::time::Duration,
        retain: Option<&dyn CompletedSpillRenderer>,
        color: bool,
    ) {
        if !self.partial.trim().is_empty() {
            let tail = std::mem::take(&mut self.partial);
            self.fold.offer(tail.trim_end(), 0);
        }
        if self.fold.is_empty() {
            return;
        }
        // Retain FIRST: the handle the line prints has to name a body that is
        // already there, or the offer is a lie for as long as the race lasts.
        let retained = retain.and_then(|r| r.retain_completed(self.fold.body()));
        let hint = retained
            .zip(retain)
            .map(|(id, renderer)| renderer.recovery_hint(id));
        let recovery = hint
            .as_deref()
            .map_or_else(display::Recovery::default, display::Recovery::Command);
        let Some(line) = self.fold.closing_line(elapsed, recovery) else {
            return;
        };
        emit_notice_line(crate::tty::Level::Thinking, "", &line, color);
    }
}

/// Decode one wire chunk, holding an INCOMPLETE trailing character back for
/// the next one.
///
/// It replaces a per-chunk `String::from_utf8_lossy`, which was wrong for
/// exactly the reason a per-chunk `lines()` split is wrong: `reqwest` splits
/// where the socket did, not where the protocol did. A multi-byte character
/// therefore straddles a chunk boundary whenever the boundary happens to fall
/// inside it — and lossy decoding replaces the half that arrived with U+FFFD.
/// That corruption is silent and permanent: the mangled text is what gets
/// printed, returned, persisted, and re-sent to the model. Where the boundary
/// falls is a function of machine load, so the same reply is clean on an idle
/// box and mangled on a busy one; `café` arrives as `caf\u{FFFD}\u{FFFD}`.
///
/// Only a TRUNCATED tail is carried (`Utf8Error::error_len() == None`).
/// Genuinely invalid bytes are consumed lossily and the loop continues, so a
/// server emitting garbage cannot grow `carry` without bound or stall the
/// stream waiting for a continuation that will never come.
fn decode_chunk(carry: &mut Vec<u8>, chunk: &[u8]) -> String {
    carry.extend_from_slice(chunk);
    let mut out = String::new();
    loop {
        let err = match std::str::from_utf8(carry) {
            Ok(s) => {
                out.push_str(s);
                carry.clear();
                return out;
            }
            Err(e) => e,
        };
        let good = err.valid_up_to();
        // Valid by construction, so this is a decode and never a replacement.
        out.push_str(&String::from_utf8_lossy(&carry[..good]));
        match err.error_len() {
            // Cut at the boundary: the rest is in the next chunk.
            None => {
                carry.drain(..good);
                return out;
            }
            // Not a cut — actually invalid. Spend it and keep going.
            Some(n) => {
                carry.drain(..good + n);
                out.push(char::REPLACEMENT_CHARACTER);
            }
        }
    }
}

#[cfg(test)]
#[path = "mod_tests/repeat_call_guard_tests.rs"]
mod repeat_call_guard_tests;

#[cfg(test)]
#[path = "mod_tests/cap_exit_unit_tests.rs"]
mod cap_exit_unit_tests;

// ---------------------------------------------------------------------------
// Tool-call round cap + graceful cap-exit (issue: configurable max_tool_rounds)
// ---------------------------------------------------------------------------
//
// These tests exercise both agentic loops (`chat_complete` -> Ollama path and
// `openai_chat_complete`) against a wiremock backend. The mock returns tool
// calls while `tools` are present in the request and a real text answer once
// they are absent — letting us assert that:
//   (1) the loop honours the configured `max_tool_rounds` cap, and
//   (2) on hitting the cap newt issues ONE final tools-disabled completion and
//       returns its text (NOT the `(reached tool-round limit)` placeholder).
//
// Hard context-window recovery is covered both by the headless driver tests
// and by a TUI-side integration test that grounds capability-cache persistence.

/// Token weight of the builtin tool catalog the loop advertises at
/// `disposition` (default advertise flags, no MCP) — the same
/// `merged_tool_definitions` → `filter_tools_for_disposition` →
/// `estimate_value_tokens` pipeline `chat_complete` runs over its advertised
/// tools each turn (see the loop setup near the top of `chat_complete`).
///
/// Token-budget fixtures size their `safe_context` / `num_ctx` / trim
/// thresholds RELATIVE to this live figure plus a scenario-specific,
/// catalog-INDEPENDENT message/headroom offset — so adding a tool or a schema
/// property shifts the catalog and the derived budget together, preserving each
/// fixture's fit-vs-refuse intent instead of tipping it over a pinned magic
/// number.
#[cfg(test)]
pub(crate) fn builtin_catalog_tokens(disposition: PromptDisposition) -> usize {
    let tools = filter_tools_for_disposition(
        merged_tool_definitions(
            &NoMcp,
            false,
            false,
            false,
            None,
            false,
            false,
            false,
            false,
            false,
            false,
            false,
            false,
            Default::default(),
            crate::agentic::shell_dialect_sentence(false, false),
        ),
        disposition,
    );
    estimate_value_tokens(&tools, crate::tokens::TokenEstimation::default())
}

#[cfg(test)]
#[path = "mod_tests/tool_round_cap_tests.rs"]
mod tool_round_cap_tests;

// ---------------------------------------------------------------------------
// HTTP-loop tests — streaming, overflow retry, mid-loop trim, and final
// summary, all against wiremock backends.
// ---------------------------------------------------------------------------

#[cfg(test)]
#[path = "mod_tests/artifact_compaction_provenance.rs"]
mod artifact_compaction_provenance_tests;
#[cfg(test)]
#[path = "mod_tests/artifact_provenance.rs"]
mod artifact_provenance_tests;
#[cfg(test)]
#[path = "mod_tests/http_loop.rs"]
mod http_loop_tests;
// The Anthropic (`/v1/messages`) loop — dispatch, SSE streaming, tool
// round-trips, stop-reason semantics, and recovery arms, all against
// wiremock backends.
#[cfg(test)]
#[path = "mod_tests/anthropic_loop.rs"]
mod anthropic_loop_tests;
#[cfg(test)]
pub(crate) use anthropic_loop_tests::EnvGuard as TestEnvGuard;
// The OpenAI-compatible final answer (#123, #2372): one generation, returned
// as the gates accepted it, with no display reissue.
#[cfg(test)]
#[path = "mod_tests/openai_stream_loop.rs"]
mod openai_stream_loop_tests;
// #1265: EPIC #1257's acceptance gate — the "10 largest Rust files" session
// replayed end-to-end (BAT tier: scripted backend, simulated workspace).
#[cfg(test)]
#[path = "mod_tests/bat_largest_files.rs"]
mod bat_largest_files_tests;
// #2051: the `hello?` turn that narrated its own disposition, replayed through
// the same simulated environment.
#[cfg(test)]
#[path = "mod_tests/bat_disposition_voice.rs"]
mod bat_disposition_voice_tests;

// ---------------------------------------------------------------------------
// save_note tool + memory nudge — loop integration (Step 19.3, #248)
// ---------------------------------------------------------------------------
//
// Wiremock-backed tests against both agentic loops, pinning:
//   (1) save_note is advertised iff a NoteSink is present, and a save_note
//       tool call routes through the sink with the result fed back;
//   (2) the in-band memory nudge is appended to the user message when due —
//       and ONLY when a sink exists;
//   (3) organic save_note use resets the nudge counter (the read-only-rounds
//       reset pattern, hermes's reset-on-memory-write).
#[cfg(test)]
#[path = "mod_tests/save_note_loop_tests.rs"]
mod save_note_loop_tests;

// ---------------------------------------------------------------------------
// Compression v2 — summarize, don't discard (Step 18.4, #247)
// ---------------------------------------------------------------------------
//
// End-to-end wiremock tests for the compression pipeline wired into both
// loops. The headline property is B5's acceptance criterion from the context
// baseline (docs/testing/results/context-baseline-f0f4f6e.md): a long
// tool-heavy conversation crosses the token budget, compression fires, and
// the ORIGINAL TASK still reaches the next request — where the baseline
// measured 9/10 silently wrong answers because truncation discarded it (B6).
#[cfg(test)]
#[path = "mod_tests/compression_loop_tests.rs"]
mod compression_loop_tests;

// ---------------------------------------------------------------------------
// Per-round observation hook + mid-turn budget raise (Phase 20,
// docs/design/model-self-tuning.md §2.2) — wiremock e2e against both gates.
// ---------------------------------------------------------------------------

#[cfg(test)]
#[path = "mod_tests/observation_hook_tests.rs"]
mod observation_hook_tests;

/// Contribution accounting consumes only the host-confirmed commit signal,
/// for native and embedded Git alike. The tests cover failed tails, cancelled
/// calls, no-publication operations, and work recorded after an epoch.
#[cfg(test)]
#[path = "mod_tests/attribution_epoch_tests.rs"]
mod attribution_epoch_tests;

#[cfg(test)]
#[path = "mod_tests/narration_output.rs"]
mod narration_output_tests;