falsegreen_agent/

agent.rs

use std::cell::RefCell;
use std::rc::Rc;
use std::time::{Duration, SystemTime, UNIX_EPOCH};

use serde::{Deserialize, Serialize};
use serde_json::{Value, json};
use thiserror::Error;

use crate::context::{ContextBuilder, ContextError};
use crate::event::{EventError, EventKind, EventStore};
use crate::falsegreen::{FalseGreenError, FalseGreenResult, FalseGreenVerifier};
use crate::genui::{
    ActionCatalog, ActionSourceType, HostCapabilities, HostConfirmation, NegotiatedCapabilities,
    Surface, derive_host_workspace_state_identity,
};
use crate::genui_composition::{
    AdmittedComposedSurface, AuthorityClass, CompositionContext, CompositionFailureCode,
    CompositionLimits, LiveAdmissionSnapshot, ProductionComposition, TrustedDataHandle,
    TrustedNegotiationContext, request_from_provider, trusted_fallback,
};
use crate::inference::{
    InferenceError, InferenceProvider, InferenceRequest, ModelAction, ToolCall, parse_action,
};
use crate::session::{Session, SessionError, SessionState};
use crate::tools::{NativeTools, ToolError, ToolResult};
use crate::workspace::WorkspaceError;

#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
pub struct AgentLimits {
    pub max_model_turns: u32,
    pub max_tool_calls: u32,
    pub max_repair_cycles: u32,
    pub max_wall_time: Duration,
}

impl Default for AgentLimits {
    fn default() -> Self {
        Self {
            max_model_turns: 40,
            max_tool_calls: 80,
            max_repair_cycles: 2,
            max_wall_time: Duration::from_secs(1_800),
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct RunOutcome {
    pub session_id: String,
    pub state: SessionState,
    pub model_turns: u32,
    pub tool_calls: u32,
    pub repair_cycles: u32,
    pub falsegreen_result: Option<FalseGreenResult>,
    pub metrics: RunMetrics,
}

#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct RunMetrics {
    pub approximate_input_tokens: u64,
    pub reported_input_tokens: Option<u64>,
    pub reported_output_tokens: Option<u64>,
    pub peak_context_tokens: u64,
    pub failed_tool_calls: u32,
    pub invalid_tool_calls: u32,
    pub shell_commands: u32,
    pub test_executions: u32,
    pub candidate_count: u32,
    pub falsegreen_attempts: u32,
    pub patch_attempts: u32,
    pub rejected_patch_attempts: u32,
    pub total_wall_time_ms: u64,
}

#[derive(Debug, Error)]
pub enum AgentError {
    #[error(transparent)]
    Event(#[from] EventError),
    #[error(transparent)]
    Session(#[from] SessionError),
    #[error(transparent)]
    Context(#[from] ContextError),
    #[error(transparent)]
    Workspace(#[from] WorkspaceError),
    #[error(transparent)]
    Tool(#[from] ToolError),
    #[error("system clock is before the session start")]
    InvalidClock,
    #[error("event store must be outside the implementation workspace: {0}")]
    EventStoreInsideWorkspace(String),
    #[error(
        "workspace fingerprint changed since the persisted turn boundary (expected {expected}, found {actual})"
    )]
    ResumeFingerprintMismatch { expected: String, actual: String },
    #[error("replacement session must be in candidate_ready state, found {0:?}")]
    InvalidReplacementState(SessionState),
    #[error("GenUI composition failed: {0}")]
    Composition(String),
}

#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum VerificationMode {
    Ordinary,
    ReplacementOnly,
}

type CompositionAdmissionHook = Box<dyn FnOnce(&mut CompositionContext, &mut ActionCatalog)>;
type LiveCompositionAdmissionHook = Box<dyn FnOnce(&mut NativeTools)>;
type LiveCompositionAuthorityHook = Box<dyn FnOnce(&mut NativeTools, &mut EventStore)>;
type LiveCompositionPublicationHook = Box<dyn FnOnce(&mut ActionCatalog)>;
type LiveCompositionPublicationAuthorityHook =
    Box<dyn FnOnce(&mut NativeTools, &mut EventStore, &mut ActionCatalog)>;

pub struct Agent<'a, P, V>
where
    P: InferenceProvider,
    V: FalseGreenVerifier,
{
    store: &'a mut EventStore,
    session: Session,
    provider: P,
    verifier: V,
    tools: NativeTools,
    context_builder: ContextBuilder,
    limits: AgentLimits,
    temperature: f32,
    latest_falsegreen: Option<FalseGreenResult>,
    pause_after_model_turns: Option<u32>,
    composition_admission_hook: Option<CompositionAdmissionHook>,
    live_composition_admission_hook: Option<LiveCompositionAdmissionHook>,
    live_composition_authority_hook: Option<LiveCompositionAuthorityHook>,
    live_composition_publication_hook: Option<LiveCompositionPublicationHook>,
    live_composition_publication_authority_hook: Option<LiveCompositionPublicationAuthorityHook>,
}

impl<'a, P, V> Agent<'a, P, V>
where
    P: InferenceProvider,
    V: FalseGreenVerifier,
{
    #[allow(clippy::too_many_arguments)]
    pub const fn new(
        store: &'a mut EventStore,
        session: Session,
        provider: P,
        verifier: V,
        tools: NativeTools,
        context_builder: ContextBuilder,
        limits: AgentLimits,
    ) -> Self {
        Self {
            store,
            session,
            provider,
            verifier,
            tools,
            context_builder,
            limits,
            temperature: 0.0,
            latest_falsegreen: None,
            pause_after_model_turns: None,
            composition_admission_hook: None,
            live_composition_admission_hook: None,
            live_composition_authority_hook: None,
            live_composition_publication_hook: None,
            live_composition_publication_authority_hook: None,
        }
    }

    /// Canonical Agent-owned bridge for a trusted GenUI action. This keeps
    /// event persistence and MCP invocation under the same Agent instance.
    pub fn execute_genui_action(
        &mut self,
        principal: &str,
        surface: &Surface,
        catalog: &ActionCatalog,
        action_id: &str,
        payload: Value,
        confirmation: Option<&HostConfirmation>,
    ) -> Result<ToolResult, AgentError> {
        catalog
            .validate_surface(surface, &HostCapabilities::default())
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        let source_type = catalog
            .resolve(action_id)
            .map(|binding| binding.source_type())
            .ok_or_else(|| AgentError::Composition("action is not in host catalog".to_owned()))?;
        match source_type {
            ActionSourceType::Mcp => self
                .tools
                .execute_genui_action(
                    self.store,
                    &self.session.id,
                    principal,
                    surface,
                    catalog,
                    action_id,
                    payload,
                    confirmation,
                )
                .map_err(AgentError::from),
            ActionSourceType::HostLocal => self.execute_host_local_genui_action_direct(
                principal,
                catalog,
                action_id,
                payload,
                confirmation,
            ),
            ActionSourceType::Auto => Err(AgentError::Composition(
                "source_unresolved: executable dispatch requires an explicit transport".to_owned(),
            )),
        }
    }

    /// Execute an action selected from a previously admitted composition. The
    /// cached rendering is never treated as authority: the live composition
    /// context, source identity, catalog binding, durable state, and normal
    /// G1/G2 transport fence are all revalidated immediately before dispatch.
    #[allow(clippy::too_many_arguments)]
    pub fn execute_admitted_genui_action(
        &mut self,
        context: &CompositionContext,
        admitted: &AdmittedComposedSurface,
        catalog: &ActionCatalog,
        action_id: &str,
        payload: Value,
        confirmation: Option<&HostConfirmation>,
    ) -> Result<ToolResult, AgentError> {
        if !admitted
            .surface()
            .actions
            .iter()
            .any(|action| action.id == action_id)
        {
            return Err(AgentError::Composition(
                "action is not present in the admitted composition".to_owned(),
            ));
        }
        admitted
            .validate_for_execution(context, catalog, self.store)
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        match context.action_source_type_for_action(action_id) {
            Some(crate::genui_composition::ActionSourceType::HostLocal) => self
                .execute_host_local_genui_action(
                    context,
                    catalog,
                    action_id,
                    payload,
                    confirmation,
                ),
            Some(crate::genui_composition::ActionSourceType::Mcp) => self.execute_genui_action(
                context.principal(),
                admitted.surface(),
                catalog,
                action_id,
                payload,
                confirmation,
            ),
            Some(crate::genui_composition::ActionSourceType::Auto) | None => {
                Err(AgentError::Composition(
                    "source_unresolved: executable dispatch requires an explicit transport"
                        .to_owned(),
                ))
            }
        }
    }

    /// Execute an explicitly host-local action through the host adapter. It
    /// never touches the MCP registry or transport; consequential local
    /// actions still require the exact host-issued confirmation identity.
    fn execute_host_local_genui_action(
        &mut self,
        context: &CompositionContext,
        catalog: &ActionCatalog,
        action_id: &str,
        payload: Value,
        confirmation: Option<&HostConfirmation>,
    ) -> Result<ToolResult, AgentError> {
        self.execute_host_local_genui_action_direct(
            context.principal(),
            catalog,
            action_id,
            payload,
            confirmation,
        )
    }

    fn execute_host_local_genui_action_direct(
        &mut self,
        principal: &str,
        catalog: &ActionCatalog,
        action_id: &str,
        payload: Value,
        confirmation: Option<&HostConfirmation>,
    ) -> Result<ToolResult, AgentError> {
        let binding = catalog.resolve(action_id).ok_or_else(|| {
            AgentError::Composition("host-local action is not in the catalog".to_owned())
        })?;
        if binding.source_type() != ActionSourceType::HostLocal {
            return Err(AgentError::Composition(
                "catalog binding is not host-local".to_owned(),
            ));
        }
        if binding.session_id() != self.session.id || binding.principal() != principal {
            return Err(AgentError::Composition(
                "session or principal changed".to_owned(),
            ));
        }
        let identity = catalog
            .identity_for(action_id, &payload)
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        if binding.requires_confirmation() {
            let supplied = confirmation.ok_or_else(|| {
                AgentError::Composition("host confirmation is required".to_owned())
            })?;
            if supplied.identity() != &identity {
                return Err(AgentError::Composition(
                    "confirmation is stale or bound to another action".to_owned(),
                ));
            }
        }
        catalog
            .validate_durable_current_action(self.store, action_id)
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        self.store
            .start_genui_action(
                &self.session.id,
                action_id,
                &identity,
                binding.requires_confirmation(),
            )
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        catalog
            .validate_current_action(action_id)
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        catalog
            .validate_durable_current_action(self.store, action_id)
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        let metadata = json!({
            "authority_state": "host_local",
            "transport": "host_local_adapter",
            "session_id": self.session.id,
            "principal": principal,
        });
        let result_digest = crate::genui::digest_value(&metadata);
        self.store
            .complete_genui_action(&self.session.id, action_id, &identity, true, &result_digest)
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        Ok(ToolResult {
            tool: action_id.to_owned(),
            tool_call_id: None,
            ok: true,
            exit_code: Some(0),
            timed_out: false,
            stdout: String::new(),
            stderr: String::new(),
            output_truncated: false,
            metadata,
        })
    }

    /// Run the canonical production G5 path through the Agent's configured
    /// provider: strict bounded JSON response -> host handle resolution ->
    /// mandatory authority checks -> durable negotiated renderer admission.
    /// Any provider/proposal failure uses the deterministic host-owned,
    /// read-only fallback and records privacy-safe audit metadata.
    pub fn compose_genui(
        &mut self,
        context: &CompositionContext,
        untrusted_task_data: &str,
        host: &HostCapabilities,
        _capabilities: &NegotiatedCapabilities,
        catalog: &mut ActionCatalog,
        limits: CompositionLimits,
    ) -> Result<ProductionComposition, AgentError> {
        // Work from a host-owned snapshot. The optional qualification hook is
        // invoked after provider resolution but before admission, allowing
        // adversarial tests to mutate the snapshot at the exact boundary.
        let admission_hook = self.composition_admission_hook.take();
        let admission_context = context.clone();
        let context = &admission_context;
        let negotiated = TrustedNegotiationContext::from_host(host)
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        if context.session_id() != self.session.id {
            return Err(AgentError::Composition(
                "composition context is bound to a different Agent session".to_owned(),
            ));
        }
        // Capture the live workspace identity before provider generation. The
        // admission fence compares a fresh read against this host-owned
        // baseline after all qualification hooks and staged bindings run.
        let (workspace_identity, workspace_generation) = self
            .tools
            .live_workspace_token(context.session_id(), context.principal())?;
        let context_digest = context
            .identity_digest_for_audit()
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        self.store.append(
            &self.session.id,
            EventKind::CompositionRequested,
            &json!({
                "context_id": context.context_id(),
                "context_digest": context_digest,
                "session_id": context.session_id(),
                "principal": context.principal(),
                "generation": context.generation(),
            }),
        )?;

        let proposal =
            request_from_provider(&mut self.provider, context, untrusted_task_data, limits);
        let composed: Result<(), crate::genui_composition::CompositionError> = match proposal {
            Ok(envelope) => {
                let digest = crate::genui::mcp_schema_digest(
                    &serde_json::to_value(&envelope)
                        .map_err(|error| AgentError::Composition(error.to_string()))?,
                );
                let raw_size = serde_json::to_vec(&envelope)
                    .map_err(|error| AgentError::Composition(error.to_string()))?
                    .len();
                self.store.append(
                    &self.session.id,
                    EventKind::ModelProposalReceived,
                    &json!({
                        "proposal_digest": digest,
                        "proposal_bytes": raw_size,
                        "provider": crate::genui_composition::bounded_audit_identity(
                            &self.provider.capabilities().provider,
                        ),
                    }),
                )?;
                match crate::genui_composition::compose(context, &envelope, host, limits) {
                    Ok(composed) => {
                        self.store.append(
                            &self.session.id,
                            EventKind::TrustedHandleResolved,
                            &json!({
                                "context_id": context.context_id(),
                                "data_refs": composed.resolved_data_ref_count(),
                                "action_refs": composed.resolved_action_ref_count(),
                            }),
                        )?;
                        let mut post_resolution_context = admission_context.clone();
                        if let Some(hook) = admission_hook {
                            hook(&mut post_resolution_context, catalog);
                        }
                        let live_hook = self.live_composition_admission_hook.take();
                        if let Some(hook) = live_hook {
                            hook(&mut self.tools);
                        }
                        let authority_hook = self.live_composition_authority_hook.take();
                        if let Some(hook) = authority_hook {
                            hook(&mut self.tools, self.store);
                        }
                        let publication_hook = self.live_composition_publication_hook.take();
                        let publication_authority_hook =
                            self.live_composition_publication_authority_hook.take();
                        // Both fences and the publication seam operate on the
                        // same real NativeTools instance.  A RefCell keeps
                        // those borrows sequential: the ordinary/final
                        // fences only read it, while the post-fence seam gets
                        // exclusive access before the guarded CAS.
                        let tools_cell = Rc::new(RefCell::new(&mut self.tools));
                        let live_tools_cell = Rc::clone(&tools_cell);
                        let publication_tools_cell = Rc::clone(&tools_cell);
                        let expected_workspace_identity = workspace_identity.clone();
                        let expected_workspace_generation = workspace_generation;
                        let (expected_catalog_generation, expected_catalog_digest) =
                            crate::genui_composition::action_catalog_authority(catalog);
                        match composed.admit_with_store_and_live_fence_and_agent_publication(
                            &post_resolution_context,
                            host,
                            negotiated.capabilities(),
                            catalog,
                            self.store,
                            |staged, store, previous| {
                                let tools = live_tools_cell.borrow();
                                Self::validate_live_admission_authority(
                                    &tools,
                                    &composed,
                                    &post_resolution_context,
                                    staged,
                                    store,
                                    &expected_workspace_identity,
                                    expected_workspace_generation,
                                    previous,
                                )
                            },
                            move |catalog, staged, final_snapshot, live_fence, store| {
                                // Hold the exclusive publication guard across
                                // the commit-time authority re-read and the
                                // catalog assignment. This closes the exact
                                // read -> publish gap rejected in V6.
                                let (catalog_generation, catalog_digest) =
                                    crate::genui_composition::action_catalog_authority(catalog);
                                if catalog_digest != expected_catalog_digest
                                    || catalog_generation != expected_catalog_generation
                                {
                                    return Err(
                                        crate::genui_composition::CompositionError::LiveAdmission(
                                            CompositionFailureCode::LiveDurableStateChanged,
                                        ),
                                    );
                                }
                                if let Some(hook) = publication_authority_hook {
                                    // Qualification-only seam: mutate the
                                    // actual workspace/MCP/EventStore after
                                    // the ordinary final fence and before the
                                    // guarded authority reread.
                                    let mut tools = publication_tools_cell.borrow_mut();
                                    hook(&mut tools, store, catalog);
                                }
                                // The authority hook may itself use the
                                // normal EventStore/MCP mutation APIs, each
                                // of which takes this global guard. Acquire
                                // it only after that hook returns, then hold
                                // it across the final reread and CAS.
                                let _guard = crate::mcp::acquire_publication_guard();
                                let commit_snapshot = live_fence(
                                    &staged,
                                    store,
                                    Some(&final_snapshot),
                                )?;
                                if !commit_snapshot.authority_eq(&final_snapshot)
                                    || commit_snapshot.catalog_digest() != staged.digest()
                                {
                                    return Err(
                                        crate::genui_composition::CompositionError::LiveAdmission(
                                            classify_live_snapshot_change(
                                                &final_snapshot,
                                                &commit_snapshot,
                                            ),
                                        ),
                                    );
                                }
                                if let Some(hook) = publication_hook {
                                    // Qualification-only seam: the callback
                                    // mutates the real live catalog
                                    // after the ordinary final fence and
                                    // before the guarded CAS publication.
                                    hook(catalog);
                                }
                                crate::genui_composition::commit_staged_catalog_with_cas_for_publication(
                                    catalog,
                                    staged,
                                    &commit_snapshot,
                                )
                            },
                        ) {
                            Ok(admitted) => {
                                let surface_digest = admitted
                                    .surface()
                                    .digest()
                                    .map_err(|error| AgentError::Composition(error.to_string()))?;
                                self.store.append(
                                    &self.session.id,
                                    EventKind::CompositionAccepted,
                                    &json!({
                                        "context_id": context.context_id(),
                                        "surface_digest": surface_digest,
                                    }),
                                )?;
                                return Ok(ProductionComposition::Admitted(admitted));
                            }
                            Err(error) => Err(error),
                        }
                    }
                    Err(error) => Err(error),
                }
            }
            Err(error) => Err(error),
        };

        let error = composed.expect_err("composition result is an error");
        // Durable composition events receive only the typed, bounded audit
        // projection. The internal error (which may retain provider details
        // for the transient caller) never crosses this persistence boundary.
        let provider_id = self.provider.capabilities().provider;
        let audit = error.audit_metadata(&provider_id, &context_digest);
        self.store.append(
            &self.session.id,
            EventKind::CompositionRejected,
            &json!({
                "context_id": context.context_id(),
                "context_digest": audit.context_digest.clone(),
                "reason_code": audit.reason_code,
                "provider": audit.provider.clone(),
                "http_status": audit.http_status,
                "response_bytes": audit.response_bytes,
            }),
        )?;
        let safe_reason = audit.reason_code.as_str().to_owned();
        let fallback = trusted_fallback(context, &safe_reason, host, limits)
            .map_err(|fallback_error| AgentError::Composition(fallback_error.to_string()))?;
        if !context.required_data_renderable(&negotiated.capabilities().supported_components) {
            return Err(AgentError::Composition(
                "negotiated renderer cannot display required authoritative data".to_owned(),
            ));
        }
        let rendered = crate::genui::render_surface_with_capabilities_and_catalog_with_store(
            &fallback,
            negotiated.capabilities(),
            catalog,
            self.store,
        )
        .map_err(|fallback_error| AgentError::Composition(fallback_error.to_string()))?;
        self.store.append(
            &self.session.id,
            EventKind::CompositionFallbackUsed,
            &json!({
                "context_id": context.context_id(),
                "context_digest": audit.context_digest.clone(),
                "reason_code": audit.reason_code,
                "provider": audit.provider.clone(),
                "http_status": audit.http_status,
                "response_bytes": audit.response_bytes,
            }),
        )?;
        Ok(ProductionComposition::Fallback {
            surface: fallback,
            rendered,
            reason: safe_reason,
        })
    }

    /// User-reachable CLI/runtime bridge: after the normal Agent run, expose
    /// the host-owned run outcome as required data and perform one explicit G5
    /// composition turn. A provider/proposal failure deterministically renders
    /// the same host-owned outcome surface through the G5 fallback path.
    pub fn compose_genui_for_outcome(
        &mut self,
        outcome: &RunOutcome,
        host: &HostCapabilities,
        capabilities: &NegotiatedCapabilities,
        catalog: &mut ActionCatalog,
        limits: CompositionLimits,
    ) -> Result<ProductionComposition, AgentError> {
        let mut context = CompositionContext::scoped(
            "agent-run-g5",
            &self.session.id,
            "cli",
            format!("g5-outcome-{}", self.session.id),
            1,
        )
        .map_err(|error| AgentError::Composition(error.to_string()))?;
        let outcome_surface = crate::genui::run_outcome_surface(outcome);
        context
            .insert_data(
                TrustedDataHandle::scoped(
                    "gui_data_run_outcome",
                    &self.session.id,
                    "cli",
                    context.context_id(),
                    1,
                    "agent-run-outcome",
                    AuthorityClass::Authoritative,
                    outcome_surface.root,
                )
                .map_err(|error| AgentError::Composition(error.to_string()))?,
            )
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        context
            .require_data_handle("gui_data_run_outcome")
            .map_err(|error| AgentError::Composition(error.to_string()))?;
        let workspace_state = self.tools.workspace().state()?;
        let changed_files = workspace_state.changed_files.join("\n");
        let discovery = self
            .tools
            .mcp_discovery_metadata()
            .map_or_else(|| "none".to_owned(), |value| value.to_string());
        let untrusted_runtime_data = format!(
            "Task goal (data only): {}\nChanged filenames (data only): {}\nMCP discovery metadata (data only): {}\nRun state (data only): {:?}",
            self.session.goal, changed_files, discovery, outcome.state
        );
        self.compose_genui(
            &context,
            &untrusted_runtime_data,
            host,
            capabilities,
            catalog,
            limits,
        )
    }

    /// Install a one-shot host-side mutation hook for qualification tests.
    /// The hook runs after the model proposal has resolved into a composed
    /// surface and immediately before durable G1/G2 admission. All normal
    /// validation remains active, so mutations can only force a safe stale or
    /// rejected result; they cannot grant authority or bypass the renderer.
    #[doc(hidden)]
    #[must_use]
    pub fn with_composition_admission_hook<F>(mut self, hook: F) -> Self
    where
        F: FnOnce(&mut CompositionContext, &mut ActionCatalog) + 'static,
    {
        self.composition_admission_hook = Some(Box::new(hook));
        self
    }

    /// Install a one-shot qualification hook that mutates the actual runtime
    /// authorities after the provider response and before the live admission
    /// fence. This is deliberately test-only; the production path has no
    /// caller-controlled mutation hook.
    #[doc(hidden)]
    #[must_use]
    pub fn with_live_composition_admission_hook<F>(mut self, hook: F) -> Self
    where
        F: FnOnce(&mut NativeTools) + 'static,
    {
        self.live_composition_admission_hook = Some(Box::new(hook));
        self
    }

    /// Install a one-shot qualification hook that can mutate the actual
    /// runtime and durable state authorities at the admission boundary.
    #[doc(hidden)]
    #[must_use]
    pub fn with_live_composition_authority_hook<F>(mut self, hook: F) -> Self
    where
        F: FnOnce(&mut NativeTools, &mut EventStore) + 'static,
    {
        self.live_composition_authority_hook = Some(Box::new(hook));
        self
    }

    /// Install a one-shot qualification hook that runs after the ordinary
    /// final admission fence and immediately before guarded catalog
    /// publication. It is test-only and mutates the actual live authority
    /// sources so production `compose_genui` CAS behavior can be exercised.
    #[doc(hidden)]
    #[must_use]
    pub fn with_live_composition_publication_hook<F>(mut self, hook: F) -> Self
    where
        F: FnOnce(&mut ActionCatalog) + 'static,
    {
        self.live_composition_publication_hook = Some(Box::new(hook));
        self
    }

    /// Install a one-shot qualification hook that mutates the real runtime
    /// authorities after `Agent::compose_genui` has completed its ordinary
    /// final fence and immediately before the guarded publication reread.
    /// This is the production-path seam used to prove workspace, MCP, and
    /// durable EventStore races; normal callers never install it.
    #[doc(hidden)]
    #[must_use]
    pub fn with_live_composition_publication_authority_hook<F>(mut self, hook: F) -> Self
    where
        F: FnOnce(&mut NativeTools, &mut EventStore, &mut ActionCatalog) + 'static,
    {
        self.live_composition_publication_authority_hook = Some(Box::new(hook));
        self
    }

    #[allow(clippy::too_many_arguments)]
    fn validate_live_admission_authority(
        tools: &NativeTools,
        composed: &crate::genui_composition::ComposedSurface,
        context: &CompositionContext,
        staged: &ActionCatalog,
        store: &EventStore,
        expected_workspace_identity: &(String, String),
        expected_workspace_generation: u64,
        previous: Option<&LiveAdmissionSnapshot>,
    ) -> Result<LiveAdmissionSnapshot, crate::genui_composition::CompositionError> {
        let (live_workspace_identity, live_workspace_generation) = tools
            .live_workspace_token(context.session_id(), context.principal())
            .map_err(|_| {
                crate::genui_composition::CompositionError::LiveAdmission(
                    CompositionFailureCode::LiveWorkspaceChanged,
                )
            })?;
        if &live_workspace_identity != expected_workspace_identity
            || live_workspace_generation != expected_workspace_generation
        {
            return Err(crate::genui_composition::CompositionError::LiveAdmission(
                CompositionFailureCode::LiveWorkspaceChanged,
            ));
        }

        let mut source_entries = Vec::new();
        let mut durable_states = Vec::new();
        let live_registry_digest = tools.live_mcp_registry_digest();
        let live_registry_generation = tools.live_mcp_registry_generation();
        for expectation in composed.action_authority_expectations() {
            if context.session_id() != expectation.session_id()
                || context.principal() != expectation.principal()
                || context.context_id() != expectation.context_id()
                || context.generation() != expectation.generation()
            {
                return Err(crate::genui_composition::CompositionError::LiveAdmission(
                    CompositionFailureCode::LiveDurableStateChanged,
                ));
            }
            if let Some(binding) = staged.resolve(expectation.action_id())
                && (binding.session_id() != expectation.session_id()
                    || binding.principal() != expectation.principal()
                    || binding.state_digest() != expectation.state_digest())
            {
                return Err(crate::genui_composition::CompositionError::LiveAdmission(
                    CompositionFailureCode::LiveDurableStateChanged,
                ));
            }
            let expected_authorization = format!(
                "agent-session:{}:principal:{}",
                expectation.session_id(),
                expectation.principal()
            );
            let Some((generation, state_digest, authorization_context)) = store
                .genui_current_state(expectation.session_id(), expectation.principal())
                .map_err(|_| {
                    crate::genui_composition::CompositionError::LiveAdmission(
                        CompositionFailureCode::LiveDurableStateChanged,
                    )
                })?
            else {
                return Err(crate::genui_composition::CompositionError::LiveAdmission(
                    CompositionFailureCode::LiveDurableStateChanged,
                ));
            };
            if generation != expectation.generation()
                || state_digest != expectation.state_digest()
                || authorization_context != expected_authorization
            {
                return Err(crate::genui_composition::CompositionError::LiveAdmission(
                    CompositionFailureCode::LiveDurableStateChanged,
                ));
            }
            durable_states.push(serde_json::json!({
                "action_id": expectation.action_id(),
                "session_id": expectation.session_id(),
                "principal": expectation.principal(),
                "generation": generation,
                "state_digest": state_digest,
                "authorization_context": authorization_context,
            }));

            let source = expectation.source();
            source
                .validate_for_action(&crate::genui::Action {
                    id: expectation.action_id().to_owned(),
                    label: String::new(),
                    kind: expectation.action_kind(),
                    state_digest: expectation.state_digest().to_owned(),
                })
                .map_err(|_| {
                    crate::genui_composition::CompositionError::LiveAdmission(
                        CompositionFailureCode::InvalidActionSource,
                    )
                })?;
            let canonical_source_type =
                expectation
                    .resolve_canonical_source_type(false)
                    .map_err(|_| {
                        crate::genui_composition::CompositionError::LiveAdmission(
                            CompositionFailureCode::SourceUnresolved,
                        )
                    })?;
            let mcp_backed = matches!(
                canonical_source_type,
                crate::genui_composition::ActionSourceType::Mcp
            );
            let source_identity = if mcp_backed {
                let Some(live) = tools.live_mcp_tool_identity(source.tool_name()) else {
                    return Err(crate::genui_composition::CompositionError::LiveAdmission(
                        CompositionFailureCode::LiveRouteMissing,
                    ));
                };
                if live.provider_id != source.provider_id()
                    || live.server_id != source.server_id()
                    || live.exposed_tool != source.tool_name()
                    || live.remote_tool_name != source.remote_tool_name()
                {
                    return Err(crate::genui_composition::CompositionError::LiveAdmission(
                        CompositionFailureCode::LiveSourceChanged,
                    ));
                }
                if live.schema_digest != source.schema_digest() {
                    return Err(crate::genui_composition::CompositionError::LiveAdmission(
                        CompositionFailureCode::LiveSourceChanged,
                    ));
                }
                if live.policy_version != source.policy_version()
                    || live.policy_digest != source.policy_digest()
                {
                    return Err(crate::genui_composition::CompositionError::LiveAdmission(
                        CompositionFailureCode::LivePolicyChanged,
                    ));
                }
                if live.requires_confirmation != source.requires_confirmation() {
                    return Err(crate::genui_composition::CompositionError::LiveAdmission(
                        CompositionFailureCode::LivePolicyChanged,
                    ));
                }
                serde_json::json!({
                    "source_type": canonical_source_type,
                    "exposed_tool": live.exposed_tool,
                    "provider_id": live.provider_id,
                    "server_id": live.server_id,
                    "remote_tool_name": live.remote_tool_name,
                    "schema_digest": live.schema_digest,
                    "policy_version": live.policy_version,
                    "policy_digest": live.policy_digest,
                    "requires_confirmation": live.requires_confirmation,
                })
            } else {
                serde_json::json!({
                    "source_type": canonical_source_type,
                    "provider_id": source.provider_id(),
                    "server_id": source.server_id(),
                    "tool_name": source.tool_name(),
                    "remote_tool_name": source.remote_tool_name(),
                    "schema_digest": source.schema_digest(),
                    "policy_version": source.policy_version(),
                    "policy_digest": source.policy_digest(),
                    "requires_confirmation": source.requires_confirmation(),
                })
            };
            source_entries.push(serde_json::json!({
                "action_id": expectation.action_id(),
                "action_kind": expectation.action_kind(),
                "identity": source_identity,
            }));
        }
        let durable_state_digest = crate::genui::mcp_schema_digest(&serde_json::json!({
            "session_id": context.session_id(),
            "principal": context.principal(),
            "states": durable_states,
            "event_store_generation": store
                .authority_generation()
                .map_err(|_| crate::genui_composition::CompositionError::LiveAdmission(
                    CompositionFailureCode::LiveDurableStateChanged,
                ))?,
        }));
        let event_store_generation = store.authority_generation().map_err(|_| {
            crate::genui_composition::CompositionError::LiveAdmission(
                CompositionFailureCode::LiveDurableStateChanged,
            )
        })?;
        let (catalog_generation, _catalog_digest) =
            crate::genui_composition::action_catalog_authority(staged);
        let catalog_base_generation =
            crate::genui_composition::action_catalog_base_generation(staged);
        let snapshot = LiveAdmissionSnapshot::new_with_all_authority_tokens(
            live_workspace_identity,
            live_workspace_generation,
            crate::genui::mcp_schema_digest(&serde_json::json!({
                "registry_digest": live_registry_digest,
                "registry_generation": live_registry_generation,
                "actions": source_entries,
            })),
            live_registry_generation,
            event_store_generation,
            durable_state_digest,
            context.session_id().to_owned(),
            context.principal().to_owned(),
            context.context_id().to_owned(),
            context.generation(),
            staged.digest(),
            catalog_generation,
            catalog_base_generation,
        );
        if let Some(previous) = previous
            && !previous.authority_eq(&snapshot)
        {
            return Err(crate::genui_composition::CompositionError::LiveAdmission(
                classify_live_snapshot_change(previous, &snapshot),
            ));
        }
        Ok(snapshot)
    }

    pub fn present_genui_action(
        &mut self,
        catalog: &ActionCatalog,
        action_id: &str,
    ) -> Result<(), AgentError> {
        catalog
            .present_action(self.store, &self.session.id, action_id)
            .map_err(|error| AgentError::Tool(ToolError::GenUi(error.to_string())))
    }

    pub fn request_genui_confirmation(
        &mut self,
        catalog: &ActionCatalog,
        action_id: &str,
        payload: &Value,
    ) -> Result<HostConfirmation, AgentError> {
        catalog
            .request_confirmation(self.store, &self.session.id, action_id, payload)
            .map_err(|error| AgentError::Tool(ToolError::GenUi(error.to_string())))
    }

    pub fn confirm_genui_action(
        &mut self,
        catalog: &ActionCatalog,
        confirmation: &HostConfirmation,
    ) -> Result<(), AgentError> {
        let host_local = confirmation
            .identity()
            .get("action_id")
            .and_then(Value::as_str)
            .and_then(|action_id| catalog.resolve(action_id))
            .is_some_and(|binding| binding.source_type() == ActionSourceType::HostLocal);
        if host_local {
            return catalog
                .append_confirmed_after_live_validation(self.store, confirmation)
                .map_err(|error| AgentError::Tool(ToolError::GenUi(error.to_string())));
        }
        self.tools
            .confirm_genui_action(self.store, catalog, confirmation)
            .map_err(|error| AgentError::Tool(ToolError::GenUi(error.to_string())))
    }

    /// Advance GenUI authority from the trusted Agent/session boundary. The
    /// state digest and authorization context are derived from host-owned
    /// session and workspace data; callers cannot inject either value.
    pub fn advance_genui_current_state(
        &mut self,
        principal: &str,
        catalog: &mut ActionCatalog,
    ) -> Result<(u64, String, String), AgentError> {
        if principal.is_empty() {
            return Err(AgentError::Tool(ToolError::GenUi(
                "principal must not be empty".to_owned(),
            )));
        }
        let workspace_state = self.tools.workspace().state()?;
        let (digest, authorization_context) =
            derive_host_workspace_state_identity(&self.session.id, principal, &workspace_state);
        let generation = self
            .store
            .advance_genui_current_state(
                &self.session.id,
                principal,
                &digest,
                &authorization_context,
            )
            .map_err(AgentError::Event)?;
        catalog
            .set_current_state(
                &self.session.id,
                principal,
                generation,
                &digest,
                &authorization_context,
            )
            .map_err(|error| AgentError::Tool(ToolError::GenUi(error.to_string())))?;
        Ok((generation, digest, authorization_context))
    }

    #[must_use]
    pub fn with_temperature(mut self, temperature: f32) -> Self {
        self.temperature = temperature;
        self
    }

    /// End this invocation at a persisted, source-fingerprinted turn boundary.
    /// The resulting `Paused` session remains resumable by a later process.
    #[must_use]
    pub const fn with_pause_after_model_turns(mut self, turns: Option<u32>) -> Self {
        self.pause_after_model_turns = turns;
        self
    }

    pub fn run(&mut self) -> Result<RunOutcome, AgentError> {
        if let Some(path) = self.store.path()
            && path.starts_with(self.tools.workspace().root())
        {
            return Err(AgentError::EventStoreInsideWorkspace(
                path.display().to_string(),
            ));
        }
        let replacement = self
            .session
            .validate_replacement_resume(self.store, self.tools.workspace())?;
        if self.session.state.is_terminal() {
            return self.outcome();
        }
        if let Some(replacement) = &replacement {
            self.record_replacement_resume_validation(replacement)?;
            self.verify_preserved_candidate(&replacement.candidate_sha256)?;
            return self.outcome();
        }
        self.validate_resume_fingerprint()?;
        if self.session.state == SessionState::Paused {
            self.session.transition(
                self.store,
                SessionState::Working,
                "resumed_from_safe_turn_boundary",
            )?;
        }
        if replacement.is_none() {
            self.record_initial_checkpoint()?;
        }
        loop {
            if self
                .pause_after_model_turns
                .is_some_and(|turns| self.session.model_turns >= turns)
            {
                self.session.transition(
                    self.store,
                    SessionState::Paused,
                    "requested_safe_turn_boundary",
                )?;
                return self.outcome();
            }
            if let Some(reason) = self.exhausted_reason()? {
                self.session
                    .transition(self.store, SessionState::BudgetExhausted, reason)?;
                return self.outcome();
            }

            let context =
                self.context_builder
                    .build(&self.session, self.store, self.tools.workspace())?;
            let messages = conversation_messages(
                &self.store.events(&self.session.id)?,
                self.context_builder.remaining_input_bytes(&context),
            );
            let history_bytes = serde_json::to_string(&messages)
                .expect("conversation messages are serializable")
                .len();
            let capabilities = self.provider.capabilities();
            self.store.append(
                &self.session.id,
                EventKind::ModelRequest,
                &json!({
                    "turn": self.session.model_turns + 1,
                    "provider": capabilities,
                    "approximate_input_tokens": (context.len() + history_bytes).div_ceil(4),
                    "max_output_tokens": self.context_builder.max_output_tokens()
                }),
            )?;
            self.session.model_turns += 1;
            let request = InferenceRequest {
                context,
                messages,
                max_output_tokens: self.context_builder.max_output_tokens(),
                temperature: self.temperature,
            };
            let response = match self.provider.complete(&request) {
                Ok(response) => response,
                Err(InferenceError::Malformed(message)) => {
                    self.store.append(
                        &self.session.id,
                        EventKind::ModelResponse,
                        &json!({
                            "protocol_error": InferenceError::Malformed(message).audit_metadata(),
                            "retryable": true,
                            "instruction": "return valid structured output on the next turn"
                        }),
                    )?;
                    self.record_turn_boundary_checkpoint()?;
                    continue;
                }
                Err(error) => {
                    self.record_inference_failure(&error)?;
                    self.session.transition(
                        self.store,
                        SessionState::Failed,
                        "inference_failure",
                    )?;
                    return self.outcome();
                }
            };
            self.store.append(
                &self.session.id,
                EventKind::ModelResponse,
                &serde_json::to_value(&response).expect("model response is serializable"),
            )?;
            let action = match parse_action(&response) {
                Ok(action) => action,
                Err(error) => {
                    self.store.append(
                        &self.session.id,
                        EventKind::ModelResponse,
                        &json!({"protocol_error": error.to_string(), "retryable": true}),
                    )?;
                    self.record_turn_boundary_checkpoint()?;
                    continue;
                }
            };
            match action {
                ModelAction::Tool {
                    tool_call_id,
                    tool,
                    arguments,
                } => {
                    if self.session.tool_calls >= self.limits.max_tool_calls {
                        self.session.transition(
                            self.store,
                            SessionState::BudgetExhausted,
                            "max_tool_calls",
                        )?;
                        return self.outcome();
                    }
                    self.execute_tool(ToolCall {
                        id: tool_call_id,
                        name: tool,
                        arguments,
                    })?;
                    self.record_turn_boundary_checkpoint()?;
                }
                ModelAction::ToolBatch { calls } => {
                    let requested = u32::try_from(calls.len()).unwrap_or(u32::MAX);
                    if self.session.tool_calls.saturating_add(requested)
                        > self.limits.max_tool_calls
                    {
                        self.session.transition(
                            self.store,
                            SessionState::BudgetExhausted,
                            "max_tool_calls",
                        )?;
                        return self.outcome();
                    }
                    for call in calls {
                        self.execute_tool(call)?;
                    }
                    self.record_turn_boundary_checkpoint()?;
                }
                ModelAction::CandidateReady { summary } => {
                    if self.verify_candidate(&summary)? {
                        return self.outcome();
                    }
                    self.record_turn_boundary_checkpoint()?;
                }
            }
        }
    }

    fn execute_tool(&mut self, call: ToolCall) -> Result<(), AgentError> {
        self.store.append(
            &self.session.id,
            EventKind::ToolRequest,
            &serde_json::to_value(&call).expect("tool call is serializable"),
        )?;
        self.session.tool_calls += 1;
        self.session
            .transition(self.store, SessionState::WaitingForTool, "tool_requested")?;
        let before_candidate = if self.tools.may_mutate_workspace(&call) {
            let workspace_state = self.tools.workspace().state()?;
            let candidate_sha256 = self.tools.workspace().candidate_sha256()?;
            self.store.append(
                &self.session.id,
                EventKind::Checkpoint,
                &json!({
                    "checkpoint_kind": "before_source_mutation",
                    "head": workspace_state.head,
                    "dirty": workspace_state.dirty,
                    "changed_files": workspace_state.changed_files,
                    "diff": self.tools.workspace().diff()?,
                    "candidate_sha256": candidate_sha256
                }),
            )?;
            Some(candidate_sha256)
        } else {
            None
        };
        let mut result = match self.tools.execute(&call) {
            Ok(result) => result,
            Err(error) => ToolResult::rejected(&call.name, &error.to_string()),
        };
        result.tool_call_id.clone_from(&call.id);
        self.store.append(
            &self.session.id,
            EventKind::ToolResult,
            &serde_json::to_value(&result).expect("tool result is serializable"),
        )?;
        if matches!(call.name.as_str(), "shell" | "search" | "git") {
            self.store.append(
                &self.session.id,
                EventKind::CommandExecution,
                &json!({"request": call, "result": result}),
            )?;
        }
        if result.ok
            && let Some(before_sha256) = before_candidate
        {
            let after_sha256 = self.tools.workspace().candidate_sha256()?;
            if before_sha256 != after_sha256 {
                self.store.append(
                    &self.session.id,
                    EventKind::FileMutation,
                    &json!({
                        "tool": call.name,
                        "before_candidate_sha256": before_sha256,
                        "candidate_sha256": after_sha256
                    }),
                )?;
            }
        }
        self.session
            .transition(self.store, SessionState::Working, "tool_completed")?;
        Ok(())
    }

    fn verify_candidate(&mut self, summary: &str) -> Result<bool, AgentError> {
        self.session.transition(
            self.store,
            SessionState::CandidateReady,
            "model_declared_candidate_ready",
        )?;
        let workspace_state = self.tools.workspace().state()?;
        let candidate_sha256 = self.tools.workspace().candidate_sha256()?;
        self.store.append(
            &self.session.id,
            EventKind::CandidateReady,
            &json!({"summary": summary, "candidate_sha256": candidate_sha256}),
        )?;
        self.store.append(
            &self.session.id,
            EventKind::GitState,
            &serde_json::to_value(workspace_state).expect("workspace state is serializable"),
        )?;
        self.session.transition(
            self.store,
            SessionState::Verifying,
            "independent_verification_started",
        )?;
        self.evaluate_verification(&candidate_sha256, VerificationMode::Ordinary)
    }

    fn verify_preserved_candidate(&mut self, candidate_sha256: &str) -> Result<(), AgentError> {
        self.session.transition(
            self.store,
            SessionState::Verifying,
            "replacement_candidate_verification_started",
        )?;
        if !self.evaluate_verification(candidate_sha256, VerificationMode::ReplacementOnly)? {
            return Err(AgentError::InvalidReplacementState(self.session.state));
        }
        Ok(())
    }

    fn evaluate_verification(
        &mut self,
        candidate_sha256: &str,
        mode: VerificationMode,
    ) -> Result<bool, AgentError> {
        let result = match self
            .verifier
            .verify(self.tools.workspace(), candidate_sha256)
        {
            Ok(result) => result,
            Err(error) => {
                self.record_falsegreen_failure(&error)?;
                self.session.transition(
                    self.store,
                    SessionState::Failed,
                    "falsegreen_infrastructure_failure",
                )?;
                return Ok(true);
            }
        };
        self.store.append(
            &self.session.id,
            EventKind::FalsegreenResult,
            &serde_json::to_value(&result).expect("FalseGreen result is serializable"),
        )?;
        let repairable = result.repairable;
        let permits_completion = result.permits_completion();
        let accepted = result.verification == crate::falsegreen::FalseGreenVerdict::Accepted;
        self.latest_falsegreen = Some(result);
        if accepted {
            if permits_completion {
                self.session.transition(
                    self.store,
                    SessionState::Completed,
                    "falsegreen_accepted_with_completion_authority",
                )?;
            } else {
                self.session.transition(
                    self.store,
                    SessionState::AcceptedAwaitingAuthority,
                    "falsegreen_accepted_awaiting_completion_authority",
                )?;
            }
            return Ok(true);
        }
        if mode == VerificationMode::Ordinary
            && repairable
            && self.session.repair_cycles < self.limits.max_repair_cycles
        {
            let canonical_repair = match self.verifier.prepare_repair(self.tools.workspace()) {
                Ok(repair) => repair,
                Err(error) => {
                    self.record_falsegreen_failure(&error)?;
                    self.session.transition(
                        self.store,
                        SessionState::Failed,
                        "falsegreen_repair_handoff_failure",
                    )?;
                    return Ok(true);
                }
            };
            self.session.transition(
                self.store,
                SessionState::Repairing,
                "falsegreen_rejected_candidate",
            )?;
            self.store.append(
                &self.session.id,
                EventKind::RepairStarted,
                &json!({
                    "repair_cycle": self.session.repair_cycles + 1,
                    "repair_packet": self.latest_falsegreen.as_ref().map(repair_packet),
                    "canonical_repair": canonical_repair
                }),
            )?;
            self.session.repair_cycles += 1;
            self.session.transition(
                self.store,
                SessionState::Working,
                "repair_evidence_returned_to_worker",
            )?;
            return Ok(false);
        }
        let reason = match mode {
            VerificationMode::Ordinary => "falsegreen_not_accepted_and_repair_unavailable",
            VerificationMode::ReplacementOnly => "falsegreen_replacement_not_accepted",
        };
        self.session
            .transition(self.store, SessionState::Failed, reason)?;
        Ok(true)
    }

    fn record_initial_checkpoint(&mut self) -> Result<(), AgentError> {
        if self.session.model_turns > 0 || self.session.tool_calls > 0 {
            return Ok(());
        }
        let workspace = self.tools.workspace();
        let state = workspace.state()?;
        self.store.append(
            &self.session.id,
            EventKind::Checkpoint,
            &json!({
                "checkpoint_kind": "initial_workspace",
                "head": state.head,
                "tree": state.tree,
                "initial_dirty": state.dirty,
                "changed_files": state.changed_files,
                "current_diff": workspace.diff()?,
                "candidate_sha256": workspace.candidate_sha256()?
            }),
        )?;
        Ok(())
    }

    fn record_turn_boundary_checkpoint(&mut self) -> Result<(), AgentError> {
        let workspace = self.tools.workspace();
        let state = workspace.state()?;
        self.store.append(
            &self.session.id,
            EventKind::Checkpoint,
            &json!({
                "checkpoint_kind": "turn_boundary",
                "model_turns": self.session.model_turns,
                "tool_calls": self.session.tool_calls,
                "head": state.head,
                "tree": state.tree,
                "dirty": state.dirty,
                "changed_files": state.changed_files,
                "candidate_sha256": workspace.candidate_sha256()?
            }),
        )?;
        Ok(())
    }

    fn record_replacement_resume_validation(
        &mut self,
        replacement: &crate::event::SessionReplacementRecord,
    ) -> Result<(), AgentError> {
        let actual = self.tools.workspace().candidate_sha256()?;
        if replacement.candidate_sha256 != actual {
            return Err(AgentError::ResumeFingerprintMismatch {
                expected: replacement.candidate_sha256.clone(),
                actual,
            });
        }
        self.store.append(
            &self.session.id,
            EventKind::Checkpoint,
            &json!({
                "checkpoint_kind": "replacement_resume_validation",
                "predecessor_session_id": replacement.predecessor_session_id,
                "expected_candidate_sha256": replacement.candidate_sha256,
                "actual_candidate_sha256": actual,
                "matched": true
            }),
        )?;
        Ok(())
    }

    fn validate_resume_fingerprint(&mut self) -> Result<(), AgentError> {
        if self.session.model_turns == 0 {
            return Ok(());
        }
        let events = self.store.events(&self.session.id)?;
        let expected = events.iter().rev().find_map(|event| {
            (event.kind == EventKind::Checkpoint
                && event.payload["checkpoint_kind"] == "turn_boundary")
                .then(|| {
                    event.payload["candidate_sha256"]
                        .as_str()
                        .map(str::to_owned)
                })
                .flatten()
        });
        let actual = self.tools.workspace().candidate_sha256()?;
        if let Some(expected) = &expected
            && expected != &actual
        {
            return Err(AgentError::ResumeFingerprintMismatch {
                expected: expected.clone(),
                actual,
            });
        }
        self.store.append(
            &self.session.id,
            EventKind::Checkpoint,
            &json!({
                "checkpoint_kind": "resume_validation",
                "turn_boundary_available": expected.is_some(),
                "expected_candidate_sha256": expected,
                "actual_candidate_sha256": actual,
                "matched": true
            }),
        )?;
        Ok(())
    }

    fn record_inference_failure(&mut self, error: &InferenceError) -> Result<(), EventError> {
        self.store.append(
            &self.session.id,
            EventKind::ModelResponse,
            &error.audit_metadata(),
        )?;
        Ok(())
    }

    fn record_falsegreen_failure(&mut self, error: &FalseGreenError) -> Result<(), EventError> {
        self.store.append(
            &self.session.id,
            EventKind::FalsegreenResult,
            &json!({"verdict": "insufficient_evidence", "error": error.to_string()}),
        )?;
        Ok(())
    }

    fn exhausted_reason(&self) -> Result<Option<&'static str>, AgentError> {
        if self.session.model_turns >= self.limits.max_model_turns {
            return Ok(Some("max_model_turns"));
        }
        if self.session.tool_calls >= self.limits.max_tool_calls {
            return Ok(Some("max_tool_calls"));
        }
        let now_ms = SystemTime::now()
            .duration_since(UNIX_EPOCH)
            .map_err(|_| AgentError::InvalidClock)?
            .as_millis();
        let started = u128::from(self.session.started_at_ms);
        let elapsed_ms = now_ms
            .checked_sub(started)
            .ok_or(AgentError::InvalidClock)?;
        if elapsed_ms >= self.limits.max_wall_time.as_millis() {
            return Ok(Some("max_wall_time"));
        }
        Ok(None)
    }

    fn outcome(&self) -> Result<RunOutcome, AgentError> {
        let events = self.store.events(&self.session.id)?;
        let now_ms = current_time_ms()?;
        let persisted_falsegreen = events.iter().rev().find_map(|event| {
            (event.kind == EventKind::FalsegreenResult)
                .then(|| serde_json::from_value(event.payload.clone()).ok())
                .flatten()
        });
        Ok(RunOutcome {
            session_id: self.session.id.clone(),
            state: self.session.state,
            model_turns: self.session.model_turns,
            tool_calls: self.session.tool_calls,
            repair_cycles: self.session.repair_cycles,
            falsegreen_result: self.latest_falsegreen.clone().or(persisted_falsegreen),
            metrics: derive_metrics(&events, now_ms.saturating_sub(self.session.started_at_ms)),
        })
    }
}

fn classify_live_snapshot_change(
    previous: &LiveAdmissionSnapshot,
    current: &LiveAdmissionSnapshot,
) -> CompositionFailureCode {
    if previous.workspace_identity() != current.workspace_identity() {
        CompositionFailureCode::LiveWorkspaceChanged
    } else if previous.source_digest() != current.source_digest() {
        CompositionFailureCode::LiveSourceChanged
    } else {
        CompositionFailureCode::LiveDurableStateChanged
    }
}

fn derive_metrics(events: &[crate::event::Event], total_wall_time_ms: u64) -> RunMetrics {
    let mut metrics = RunMetrics {
        approximate_input_tokens: 0,
        reported_input_tokens: None,
        reported_output_tokens: None,
        peak_context_tokens: 0,
        failed_tool_calls: 0,
        invalid_tool_calls: 0,
        shell_commands: 0,
        test_executions: 0,
        candidate_count: 0,
        falsegreen_attempts: 0,
        patch_attempts: 0,
        rejected_patch_attempts: 0,
        total_wall_time_ms,
    };
    for event in events {
        match event.kind {
            EventKind::ModelRequest => {
                let tokens = event.payload["approximate_input_tokens"]
                    .as_u64()
                    .unwrap_or(0);
                metrics.approximate_input_tokens += tokens;
                metrics.peak_context_tokens = metrics.peak_context_tokens.max(tokens);
            }
            EventKind::ModelResponse => {
                if event.payload.get("protocol_error").is_some() {
                    metrics.invalid_tool_calls += 1;
                }
                if let Some(usage) = event.payload.get("usage") {
                    add_optional(
                        &mut metrics.reported_input_tokens,
                        usage
                            .get("prompt_tokens")
                            .or_else(|| usage.get("input_tokens"))
                            .and_then(Value::as_u64),
                    );
                    add_optional(
                        &mut metrics.reported_output_tokens,
                        usage
                            .get("completion_tokens")
                            .or_else(|| usage.get("output_tokens"))
                            .and_then(Value::as_u64),
                    );
                }
            }
            EventKind::ToolRequest => {
                if event.payload.get("name").and_then(Value::as_str) == Some("apply_patch") {
                    metrics.patch_attempts += 1;
                }
                if event.payload.get("name").and_then(Value::as_str) == Some("shell") {
                    metrics.shell_commands += 1;
                    if is_test_command(&event.payload["arguments"]["argv"]) {
                        metrics.test_executions += 1;
                    }
                }
            }
            EventKind::ToolResult => {
                if event.payload.get("tool").and_then(Value::as_str) == Some("apply_patch")
                    && event.payload.get("ok").and_then(Value::as_bool) == Some(false)
                {
                    metrics.rejected_patch_attempts += 1;
                }
                if event.payload.get("ok").and_then(Value::as_bool) == Some(false) {
                    metrics.failed_tool_calls += 1;
                }
                if event
                    .payload
                    .pointer("/metadata/validation_error")
                    .is_some()
                {
                    metrics.invalid_tool_calls += 1;
                }
            }
            EventKind::CandidateReady => metrics.candidate_count += 1,
            EventKind::FalsegreenResult => metrics.falsegreen_attempts += 1,
            _ => {}
        }
    }
    metrics
}

fn add_optional(total: &mut Option<u64>, value: Option<u64>) {
    if let Some(value) = value {
        *total = Some(total.unwrap_or(0) + value);
    }
}

fn is_test_command(argv: &Value) -> bool {
    let Some(arguments) = argv.as_array() else {
        return false;
    };
    let words: Vec<&str> = arguments.iter().filter_map(Value::as_str).collect();
    matches!(
        words.as_slice(),
        ["pytest" | "cargo-nextest" | "ctest" | "rspec", ..]
            | ["cargo" | "go" | "npm" | "pnpm" | "yarn", "test", ..]
    ) || matches!(
        words.as_slice(),
        ["python" | "python3", "-m", "unittest" | "pytest", ..]
    ) || matches!(words.as_slice(), ["python" | "python3", script, ..] if script.contains("test"))
}

fn current_time_ms() -> Result<u64, AgentError> {
    let millis = SystemTime::now()
        .duration_since(UNIX_EPOCH)
        .map_err(|_| AgentError::InvalidClock)?
        .as_millis();
    u64::try_from(millis).map_err(|_| AgentError::InvalidClock)
}

fn conversation_messages(events: &[crate::event::Event], maximum_bytes: usize) -> Vec<Value> {
    let mut conversational_events: Vec<&crate::event::Event> = events
        .iter()
        .rev()
        .filter(|event| matches!(event.kind, EventKind::ModelResponse | EventKind::ToolResult))
        .take(48)
        .collect();
    conversational_events.reverse();
    let mut messages = Vec::new();
    let mut native_call_ids = std::collections::BTreeSet::new();
    for event in conversational_events {
        match event.kind {
            EventKind::ModelResponse => {
                let Ok(response) = serde_json::from_value::<crate::inference::ModelResponse>(
                    event.payload.clone(),
                ) else {
                    continue;
                };
                if response.tool_calls.is_empty() {
                    if let Some(content) = response.content
                        && !content.is_empty()
                    {
                        messages.push(json!({"role": "assistant", "content": content}));
                    }
                    continue;
                }
                if response.tool_calls.len() == 1
                    && response.tool_calls[0].name == "candidate_ready"
                {
                    messages.push(json!({
                        "role": "assistant",
                        "content": format!(
                            "CANDIDATE_READY: {}",
                            response.tool_calls[0].arguments["summary"]
                                .as_str()
                                .unwrap_or("submitted for independent verification")
                        )
                    }));
                    continue;
                }
                let tool_calls: Vec<Value> = response
                    .tool_calls
                    .iter()
                    .filter_map(|call| {
                        let id = call.id.as_ref()?;
                        native_call_ids.insert(id.clone());
                        Some(json!({
                            "id": id,
                            "type": "function",
                            "function": {
                                "name": call.name,
                                "arguments": serde_json::to_string(&call.arguments)
                                    .expect("tool arguments are serializable")
                            }
                        }))
                    })
                    .collect();
                if !tool_calls.is_empty() {
                    messages.push(json!({
                        "role": "assistant",
                        "content": response.content,
                        "tool_calls": tool_calls
                    }));
                }
            }
            EventKind::ToolResult => {
                let call_id = event.payload.get("tool_call_id").and_then(Value::as_str);
                let content = truncate_utf8(
                    &serde_json::to_string(&event.payload)
                        .expect("persisted tool result is serializable"),
                    16 * 1024,
                );
                if let Some(call_id) = call_id.filter(|id| native_call_ids.contains(*id)) {
                    messages.push(json!({
                        "role": "tool",
                        "tool_call_id": call_id,
                        "content": content
                    }));
                } else {
                    messages.push(json!({
                        "role": "user",
                        "content": format!("TOOL_RESULT: {content}")
                    }));
                }
            }
            _ => {}
        }
    }
    while serde_json::to_vec(&messages)
        .expect("conversation messages are serializable")
        .len()
        > maximum_bytes
        && !messages.is_empty()
    {
        messages.remove(0);
    }
    while messages
        .first()
        .and_then(|message| message.get("role"))
        .and_then(Value::as_str)
        == Some("tool")
    {
        messages.remove(0);
    }
    messages
}

fn truncate_utf8(value: &str, maximum_bytes: usize) -> String {
    if value.len() <= maximum_bytes {
        return value.to_owned();
    }
    let marker = "\n...[tool result truncated]";
    let content_limit = maximum_bytes.saturating_sub(marker.len());
    let boundary = value
        .char_indices()
        .take_while(|(index, _)| *index <= content_limit)
        .map(|(index, _)| index)
        .last()
        .unwrap_or(0);
    format!("{}{}", &value[..boundary], marker)
}

fn repair_packet(result: &FalseGreenResult) -> Value {
    let verification = result
        .evidence
        .get("verification")
        .unwrap_or(&result.evidence);
    json!({
        "candidate_sha256": result.candidate_sha256,
        "authoritative_source_sha256": result.authoritative_source_sha256,
        "verification_status": result.verification_status,
        "failed_release_requirements": verification.get("failed_release_requirements"),
        "failed_regressions": verification.get("failed_regressions"),
        "invalid_commands": verification.get("invalid_commands"),
        "command_results": verification.get("command_results"),
        "canonical_evidence": result.evidence
    })
}

#[cfg(test)]
mod tests {
    use std::collections::VecDeque;
    use std::time::Duration;

    use serde_json::json;

    use crate::context::{ContextBudget, ContextBuilder};
    use crate::event::{EventKind, EventStore};
    use crate::falsegreen::{FalseGreenError, FalseGreenResult, FalseGreenVerifier};
    use crate::inference::{
        InferenceError, InferenceProvider, InferenceRequest, ModelAction, ModelCapabilities,
        ModelResponse, ProviderCapabilities,
    };
    use crate::session::{Session, SessionState};
    use crate::tools::{NativeTools, ToolLimits};
    use crate::workspace::Workspace;
    use crate::workspace::tests::git_fixture;

    use super::{Agent, AgentLimits};

    struct FakeModel {
        actions: VecDeque<ModelAction>,
    }

    impl InferenceProvider for FakeModel {
        fn capabilities(&self) -> ProviderCapabilities {
            ProviderCapabilities {
                provider: "deterministic-fake".to_owned(),
                wire_protocol: "in-process".to_owned(),
                model: ModelCapabilities {
                    identifier: "deterministic-fake".to_owned(),
                    repository: None,
                    artifact: None,
                    artifact_sha256: None,
                    quantization: None,
                    chat_template: None,
                    context_window_tokens: None,
                    native_tools: false,
                    qualification: None,
                },
                streaming: false,
                runtime_provenance: None,
            }
        }

        fn complete(
            &mut self,
            _request: &InferenceRequest,
        ) -> Result<ModelResponse, InferenceError> {
            let action = self.actions.pop_front().expect("fake action available");
            Ok(ModelResponse {
                content: Some(serde_json::to_string(&action).expect("serialize action")),
                tool_calls: Vec::new(),
                usage: None,
            })
        }
    }

    struct FakeVerifier {
        results: VecDeque<FalseGreenResult>,
    }

    impl FalseGreenVerifier for FakeVerifier {
        fn verify(
            &mut self,
            _workspace: &Workspace,
            candidate_sha256: &str,
        ) -> Result<FalseGreenResult, FalseGreenError> {
            let mut result = self.results.pop_front().expect("fake result available");
            result.candidate_sha256 = candidate_sha256.to_owned();
            Ok(result)
        }
    }

    fn action(tool: &str, arguments: serde_json::Value) -> ModelAction {
        ModelAction::Tool {
            tool_call_id: None,
            tool: tool.to_owned(),
            arguments,
        }
    }

    #[test]
    fn deterministic_lifecycle_repairs_until_falsegreen_accepts() {
        let directory = git_fixture();
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let tools = NativeTools::new(workspace, ToolLimits::default());
        let patch_one = "diff --git a/hello.txt b/hello.txt\n--- a/hello.txt\n+++ b/hello.txt\n@@ -1 +1 @@\n-old\n+new\n";
        let patch_two = "diff --git a/hello.txt b/hello.txt\n--- a/hello.txt\n+++ b/hello.txt\n@@ -1 +1 @@\n-new\n+fixed\n";
        let model = FakeModel {
            actions: VecDeque::from(vec![
                action("read_file", json!({"path": "hello.txt"})),
                action("apply_patch", json!({"patch": patch_one})),
                action(
                    "shell",
                    json!({"argv": ["sh", "-c", "test \"$(cat hello.txt)\" = new"]}),
                ),
                ModelAction::CandidateReady {
                    summary: "first candidate".to_owned(),
                },
                action("apply_patch", json!({"patch": patch_two})),
                action(
                    "shell",
                    json!({"argv": ["sh", "-c", "test \"$(cat hello.txt)\" = fixed"]}),
                ),
                ModelAction::CandidateReady {
                    summary: "repaired candidate".to_owned(),
                },
            ]),
        };
        let verifier = FakeVerifier {
            results: VecDeque::from(vec![
                FalseGreenResult::failed(
                    "ignored",
                    json!({
                        "failed_release_requirements": ["AC-1"],
                        "command_results": [{"criterion_id": "AC-1", "passed": false}]
                    }),
                ),
                FalseGreenResult::accepted("ignored"),
            ]),
        };
        let mut store = EventStore::open_memory().expect("store");
        let session = Session::create(&mut store, "make hello fixed").expect("session");
        let session_id = session.id.clone();
        let mut agent = Agent::new(
            &mut store,
            session,
            model,
            verifier,
            tools,
            ContextBuilder::new(ContextBudget::default()),
            AgentLimits::default(),
        );
        let outcome = agent.run().expect("run");
        assert_eq!(outcome.state, SessionState::Completed);
        assert_eq!(outcome.model_turns, 7);
        assert_eq!(outcome.tool_calls, 5);
        assert_eq!(outcome.repair_cycles, 1);
        assert_eq!(outcome.metrics.candidate_count, 2);
        assert_eq!(outcome.metrics.falsegreen_attempts, 2);
        assert_eq!(outcome.metrics.shell_commands, 2);
        assert_eq!(outcome.metrics.test_executions, 0);
        drop(agent);
        let events = store.events(&session_id).expect("events");
        let kinds: Vec<EventKind> = events.iter().map(|event| event.kind).collect();
        assert_eq!(
            kinds
                .iter()
                .filter(|kind| **kind == EventKind::CandidateReady)
                .count(),
            2
        );
        assert_eq!(
            kinds
                .iter()
                .filter(|kind| **kind == EventKind::FalsegreenResult)
                .count(),
            2
        );
        assert_eq!(events.last().expect("last").kind, EventKind::TerminalState);
        assert_eq!(
            events.last().expect("last").payload["state"],
            json!(SessionState::Completed)
        );
    }

    #[test]
    fn model_done_does_not_override_falsegreen_failure() {
        let directory = git_fixture();
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let model = FakeModel {
            actions: VecDeque::from([ModelAction::CandidateReady {
                summary: "done".to_owned(),
            }]),
        };
        let verifier = FakeVerifier {
            results: VecDeque::from([FalseGreenResult::failed(
                "ignored",
                json!({"failed_release_requirements": ["AC-1"]}),
            )]),
        };
        let mut store = EventStore::open_memory().expect("store");
        let session = Session::create(&mut store, "goal").expect("session");
        let mut agent = Agent::new(
            &mut store,
            session,
            model,
            verifier,
            NativeTools::new(workspace, ToolLimits::default()),
            ContextBuilder::new(ContextBudget::default()),
            AgentLimits {
                max_repair_cycles: 0,
                max_wall_time: Duration::from_secs(5),
                ..AgentLimits::default()
            },
        );
        let outcome = agent.run().expect("run");
        assert_eq!(outcome.state, SessionState::Failed);
        assert_ne!(outcome.state, SessionState::Completed);
    }

    #[test]
    fn records_workspace_mutation_caused_by_shell() {
        let directory = git_fixture();
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let model = FakeModel {
            actions: VecDeque::from([
                action(
                    "shell",
                    json!({"argv": ["sh", "-c", "printf changed\\n > hello.txt"]}),
                ),
                ModelAction::CandidateReady {
                    summary: "shell mutation complete".to_owned(),
                },
            ]),
        };
        let verifier = FakeVerifier {
            results: VecDeque::from([FalseGreenResult::accepted("ignored")]),
        };
        let mut store = EventStore::open_memory().expect("store");
        let session = Session::create(&mut store, "change the file").expect("session");
        let session_id = session.id.clone();
        let mut agent = Agent::new(
            &mut store,
            session,
            model,
            verifier,
            NativeTools::new(workspace, ToolLimits::default()),
            ContextBuilder::new(ContextBudget::default()),
            AgentLimits::default(),
        );
        assert_eq!(agent.run().expect("run").state, SessionState::Completed);
        drop(agent);
        let mutations: Vec<_> = store
            .events(&session_id)
            .expect("events")
            .into_iter()
            .filter(|event| event.kind == EventKind::FileMutation)
            .collect();
        assert_eq!(mutations.len(), 1);
        assert_eq!(mutations[0].payload["tool"], json!("shell"));
    }

    #[test]
    fn accepted_verification_without_completion_authority_is_not_completed() {
        let directory = git_fixture();
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let model = FakeModel {
            actions: VecDeque::from([ModelAction::CandidateReady {
                summary: "ready for verification".to_owned(),
            }]),
        };
        let verifier = FakeVerifier {
            results: VecDeque::from([FalseGreenResult::accepted_awaiting_authority("ignored")]),
        };
        let mut store = EventStore::open_memory().expect("store");
        let session = Session::create(&mut store, "goal").expect("session");
        let mut agent = Agent::new(
            &mut store,
            session,
            model,
            verifier,
            NativeTools::new(workspace, ToolLimits::default()),
            ContextBuilder::new(ContextBudget::default()),
            AgentLimits::default(),
        );
        let outcome = agent.run().expect("run");
        assert_eq!(outcome.state, SessionState::AcceptedAwaitingAuthority);
        assert_eq!(
            outcome
                .falsegreen_result
                .expect("verification")
                .verification,
            crate::falsegreen::FalseGreenVerdict::Accepted
        );
    }

    #[test]
    fn persists_safe_pause_and_resumes_without_duplicate_actions() {
        let directory = git_fixture();
        let state_directory = tempfile::tempdir().expect("state tempdir");
        let database = state_directory.path().join("events.db");
        let mut store = EventStore::open(&database).expect("store");
        let session = Session::create(&mut store, "make hello new").expect("session");
        let session_id = session.id.clone();
        let first_model = FakeModel {
            actions: VecDeque::from([action("read_file", json!({"path": "hello.txt"}))]),
        };
        let first_verifier = FakeVerifier {
            results: VecDeque::new(),
        };
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let mut first_agent = Agent::new(
            &mut store,
            session,
            first_model,
            first_verifier,
            NativeTools::new(workspace, ToolLimits::default()),
            ContextBuilder::new(ContextBudget::default()),
            AgentLimits::default(),
        )
        .with_pause_after_model_turns(Some(1));
        let paused = first_agent.run().expect("pause");
        assert_eq!(paused.state, SessionState::Paused);
        drop(first_agent);
        drop(store);

        let patch = "diff --git a/hello.txt b/hello.txt\n--- a/hello.txt\n+++ b/hello.txt\n@@ -1 +1 @@\n-old\n+new\n";
        let second_model = FakeModel {
            actions: VecDeque::from([
                action("apply_patch", json!({"patch": patch})),
                ModelAction::CandidateReady {
                    summary: "resumed candidate".to_owned(),
                },
            ]),
        };
        let second_verifier = FakeVerifier {
            results: VecDeque::from([FalseGreenResult::accepted("ignored")]),
        };
        let mut store = EventStore::open(&database).expect("reopen store");
        let resumed_session = Session::reconstruct(&store, &session_id).expect("reconstruct");
        assert_eq!(resumed_session.state, SessionState::Paused);
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let mut second_agent = Agent::new(
            &mut store,
            resumed_session,
            second_model,
            second_verifier,
            NativeTools::new(workspace, ToolLimits::default()),
            ContextBuilder::new(ContextBudget::default()),
            AgentLimits::default(),
        );
        let outcome = second_agent.run().expect("resume");
        assert_eq!(outcome.state, SessionState::Completed);
        assert_eq!(outcome.model_turns, 3);
        assert_eq!(outcome.tool_calls, 2);
        assert_eq!(outcome.metrics.candidate_count, 1);
        assert_eq!(outcome.metrics.falsegreen_attempts, 1);
        drop(second_agent);
        let events = store.events(&session_id).expect("events");
        assert_eq!(
            events
                .iter()
                .filter(|event| event.kind == EventKind::ToolRequest)
                .count(),
            2
        );
        assert!(events.iter().any(|event| {
            event.kind == EventKind::Checkpoint
                && event.payload["checkpoint_kind"] == "resume_validation"
                && event.payload["matched"] == true
        }));
    }

    #[test]
    fn resume_refuses_a_workspace_that_changed_after_the_turn_checkpoint() {
        let directory = git_fixture();
        let state_directory = tempfile::tempdir().expect("state tempdir");
        let database = state_directory.path().join("events.db");
        let mut store = EventStore::open(&database).expect("store");
        let session = Session::create(&mut store, "inspect hello").expect("session");
        let session_id = session.id.clone();
        let model = FakeModel {
            actions: VecDeque::from([action("read_file", json!({"path": "hello.txt"}))]),
        };
        let verifier = FakeVerifier {
            results: VecDeque::new(),
        };
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let mut agent = Agent::new(
            &mut store,
            session,
            model,
            verifier,
            NativeTools::new(workspace, ToolLimits::default()),
            ContextBuilder::new(ContextBudget::default()),
            AgentLimits::default(),
        )
        .with_pause_after_model_turns(Some(1));
        assert_eq!(agent.run().expect("pause").state, SessionState::Paused);
        drop(agent);
        std::fs::write(
            directory.path().join("hello.txt"),
            "changed outside agent\n",
        )
        .expect("external mutation");

        let resumed = Session::reconstruct(&store, &session_id).expect("reconstruct");
        let model = FakeModel {
            actions: VecDeque::new(),
        };
        let verifier = FakeVerifier {
            results: VecDeque::new(),
        };
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let mut resumed_agent = Agent::new(
            &mut store,
            resumed,
            model,
            verifier,
            NativeTools::new(workspace, ToolLimits::default()),
            ContextBuilder::new(ContextBudget::default()),
            AgentLimits::default(),
        );
        assert!(matches!(
            resumed_agent.run(),
            Err(super::AgentError::ResumeFingerprintMismatch { .. })
        ));
    }
}