Luigit
repositories / smith

smith

There are many coding harnesses - but this one is fast

owned by admin

smith-core/src/tools.rs

Raw
//! Tool registry, validation, built-in file effects, and the durable
//! outcome boundary between successful effects and recorded session frames.
//!
//! (`SMH-SPEC-SPEC0001`, Tools).

mod lifecycle;
use crate::metadata::{ToolMutationMetadata, encode as encode_metadata};
use crate::session::{
    Entry, EntryContentRef, PLUGIN_HTTP_KIND, PLUGIN_LOG_KIND, Session, TOOL_MUTATION_KIND,
};
use crate::store::SessionWriter;
pub use crate::workspace::WorkspaceRoot;
use serde::{Deserialize, Serialize};
use smith::config::Config;
use smith::error::{MutationState, Result, SmithError};
use smith::id::ToolCallId;
#[cfg(test)]
use smith::structured::ToolSchema;
use smith::structured::{Kind, SchemaError, StructuredData, StructuredValue, ToolArguments};
use smith::tool::{CancelHandle, ToolMetadata};
use std::collections::HashMap;
use std::fs;
use std::io::{BufRead, BufReader, Read, Write};
use std::path::{Path, PathBuf};
use std::sync::Arc;
use std::sync::atomic::{AtomicUsize, Ordering};
use std::time::{Duration, Instant};

#[cfg(test)]
mod commit_tests;
#[cfg(test)]
mod nested_tests;

const HARD_OUTPUT_CAP: usize = 256 * 1024;
const DEFAULT_OUTPUT_CAP: usize = 64 * 1024;
const LIST_ENTRIES_MAX: usize = 1000;
const IGNORE_LINES_MAX: usize = 1000;
const IGNORE_LINE_BYTES_MAX: usize = 8 * 1024;
const GREP_MATCHES_MAX: usize = 200;
const GREP_LINE_BYTES_MAX: usize = DEFAULT_OUTPUT_CAP;
const EDIT_FILE_BYTES_MAX: usize = 8 * 1024 * 1024;

/// Read one LF-delimited line without materializing more than `bytes_max` bytes.
fn read_line_bounded(
    reader: &mut impl BufRead,
    line: &mut Vec<u8>,
    bytes_max: usize,
) -> std::io::Result<bool> {
    #[expect(
        clippy::disallowed_methods,
        reason = "Take caps one line before overflow is reported"
    )]
    let bytes_read = reader
        .take((bytes_max + 1) as u64)
        .read_until(b'\n', line)?;
    if bytes_read == 0 {
        return Ok(false);
    }
    let line_ended = line.ends_with(b"\n") || reader.fill_buf()?.is_empty();
    if line.len() > bytes_max || !line_ended {
        return Err(std::io::Error::new(
            std::io::ErrorKind::InvalidData,
            format!("line exceeds {bytes_max} bytes"),
        ));
    }
    Ok(true)
}

/// Registry of available tools.
#[derive(Clone, Debug, Default)]
pub struct ToolRegistry {
    /// Tools by name.
    tools: HashMap<String, ToolMetadata>,
    /// Name-ordered snapshot handed to every provider request; rebuilt on
    /// registration, shared afterwards.
    snapshot: Arc<[ToolMetadata]>,
}

impl ToolRegistry {
    /// An empty registry.
    #[must_use]
    pub fn new() -> Self {
        Self::default()
    }

    /// Register or replace a tool definition.
    pub fn register(&mut self, meta: ToolMetadata) {
        self.tools.insert(meta.name.clone(), meta);
        let mut ordered: Vec<ToolMetadata> = self.tools.values().cloned().collect();
        ordered.sort_by(|left, right| left.name.cmp(&right.name));
        self.snapshot = ordered.into();
    }

    /// The registered tool, when present.
    #[must_use]
    pub fn get(&self, name: &str) -> Option<&ToolMetadata> {
        self.tools.get(name)
    }

    /// The name-ordered tool definitions, for provider requests.
    #[must_use]
    pub fn snapshot(&self) -> Arc<[ToolMetadata]> {
        Arc::clone(&self.snapshot)
    }
}

#[cfg(test)]
pub(crate) fn test_tool_registry() -> ToolRegistry {
    let mut registry = ToolRegistry::new();
    for (name, description, schema) in [
        (
            "read",
            "Read a bounded line window from a file.",
            ToolSchema::object(
                &[
                    ("path", "string"),
                    ("offset", "integer"),
                    ("limit", "integer"),
                    ("max_bytes", "integer"),
                ],
                &["path"],
            ),
        ),
        (
            "write",
            "Atomically replace a file, creating parents.",
            ToolSchema::object(
                &[("path", "string"), ("content", "string")],
                &["path", "content"],
            ),
        ),
        (
            "edit",
            "Apply one exact, unambiguous replacement.",
            ToolSchema::object(
                &[
                    ("path", "string"),
                    ("old_string", "string"),
                    ("new_string", "string"),
                ],
                &["path", "old_string", "new_string"],
            ),
        ),
        (
            "ls",
            "List a directory deterministically.",
            ToolSchema::object(&[("path", "string")], &[]),
        ),
        (
            "find",
            "Find directory entries matching a substring.",
            ToolSchema::object(&[("path", "string"), ("pattern", "string")], &["pattern"]),
        ),
        (
            "grep",
            "Return bounded matching lines from a file.",
            ToolSchema::object(
                &[("path", "string"), ("query", "string")],
                &["path", "query"],
            ),
        ),
        (
            "bash",
            "Run a bounded cancellable shell command with host filesystem and network access.",
            ToolSchema::object(
                &[("command", "string"), ("timeout_ms", "integer")],
                &["command"],
            ),
        ),
    ] {
        registry.register(ToolMetadata::new(name, description).with_schema(schema));
    }
    registry
}

type PersistEntry = dyn FnMut(&Entry, &[u8]) -> Result<()> + Send;
type PersistCompletion = dyn FnMut(crate::frame::Frame) -> Result<()> + Send;

struct CompletionBoundary {
    submission_id: smith::id::EntryId,
    persist: Box<PersistCompletion>,
}

/// Immutable identity of one component that contributed advertised tools.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ToolComponentProvenance {
    /// Stable package or built-in source identity.
    pub source_id: String,
    /// SHA-256 of the exact manifest source.
    pub manifest_sha256: String,
    /// SHA-256 of the exact component artifact.
    pub component_sha256: String,
}

/// Exact tool definition paired with its pinned component generation.
#[derive(Clone, Debug, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ToolLoadoutTool {
    /// Definition advertised to the provider.
    pub definition: ToolMetadata,
    /// Index into [`ToolLoadoutProvenance::components`].
    pub component_index: u16,
}

/// Bounded immutable dispatcher snapshot for one provider request.
#[derive(Clone, Debug, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(deny_unknown_fields)]
pub struct ToolLoadoutProvenance {
    /// Hash-pinned component generations owning this snapshot.
    pub components: Vec<ToolComponentProvenance>,
    /// Exact advertised definitions and their owner generation.
    pub tools: Vec<ToolLoadoutTool>,
}

impl ToolLoadoutProvenance {
    /// Construct an empty snapshot.
    #[must_use]
    pub const fn empty() -> Self {
        Self {
            components: Vec::new(),
            tools: Vec::new(),
        }
    }
}

/// Shared host-owned availability, pinned with one request.
pub use smith::lifecycle::ToolAvailability as ToolPolicyState;

/// Definitions and provenance pinned together for one provider request.
#[derive(Clone, Debug, Default, PartialEq, Eq)]
pub struct ToolDispatcherSnapshot {
    /// Definitions advertised to the provider.
    pub tools: Vec<ToolMetadata>,
    /// Every registered definition eligible for host-owned policy resolution.
    ///
    /// This can include active hidden tools; provider requests receive only `tools`.
    pub registered_tools: Vec<ToolMetadata>,
    /// Host-resolved authority for every registered identity.
    pub policy: Vec<(String, ToolPolicyState)>,
    /// Durable identity paired exactly with `tools`.
    pub provenance: ToolLoadoutProvenance,
}

/// Dispatches a validated tool call through a host-owned extension.
pub trait ToolDispatcher: Send {
    /// Publish one immutable tool-definition snapshot before a provider request.
    ///
    /// Implementations retain the matching handlers until
    /// [`ToolDispatcher::end_provider_round`] so definitions and execution
    /// cannot cross a plugin generation boundary.
    ///
    /// # Errors
    ///
    /// Returns a loading or registration error before the provider request.
    fn begin_provider_round(&mut self) -> Result<ToolDispatcherSnapshot> {
        Ok(ToolDispatcherSnapshot::default())
    }

    /// Release handlers pinned by [`ToolDispatcher::begin_provider_round`].
    fn end_provider_round(&mut self) {}

    /// Whether this dispatcher subscribes to a lifecycle boundary.
    ///
    /// Empty dispatchers default to no subscriptions, avoiding cleanup scopes.
    /// Implementations overriding lifecycle dispatch must declare their membership.
    fn has_lifecycle_handlers(&self, _boundary: smith::lifecycle::Boundary) -> bool {
        false
    }

    /// Invoke sandbox lifecycle handlers without model-tool attribution or effects.
    ///
    /// # Errors
    /// Returns uncatchable host recording or cancellation failure.
    fn lifecycle(
        &mut self,
        _event: &smith::lifecycle::LifecycleEvent,
        _cancel: &CancelHandle,
    ) -> Result<smith::lifecycle::LifecycleBatch> {
        Ok(smith::lifecycle::LifecycleBatch::default())
    }

    /// Dispatch lifecycle handlers through an exclusive durable root context.
    ///
    /// # Errors
    /// Recording uncertainty is terminal, even if a handler catches an import error.
    fn lifecycle_effects(
        &mut self,
        event: &smith::lifecycle::LifecycleEvent,
        effects: &mut ToolEffectContext<'_>,
    ) -> Result<smith::lifecycle::LifecycleBatch> {
        self.lifecycle(event, &effects.cancel_handle())
    }

    /// Validate runtime choices against host authority before any publication.
    ///
    /// # Errors
    /// Rejects unavailable choices or unsupported changes.
    fn validate_lifecycle(
        &self,
        actions: &[smith::lifecycle::LifecycleAction],
        model: &str,
    ) -> Result<()> {
        for action in actions {
            if !matches!(
                action,
                smith::lifecycle::LifecycleAction::Cancel
                    | smith::lifecycle::LifecycleAction::EnsureContinuation
                    | smith::lifecycle::LifecycleAction::EditContext(_)
                    | smith::lifecycle::LifecycleAction::SetPrompt(_)
            ) && !matches!(action, smith::lifecycle::LifecycleAction::SetModel(selected) if selected == model)
            {
                return Err(tool_error(
                    smith::error::ToolCode::Validation,
                    "runtime lifecycle choice unavailable",
                ));
            }
        }
        Ok(())
    }

    /// Publish previously validated runtime choices, without fallible I/O.
    fn commit_lifecycle(&mut self, _actions: &[smith::lifecycle::LifecycleAction]) {}

    /// Dispatch `name` and validated `input` through its single-operation grant.
    ///
    /// # Errors
    ///
    /// Returns the extension or granted-effect failure.
    fn invoke(
        &mut self,
        name: &str,
        input: &ToolArguments,
        effects: &mut ToolEffectContext<'_>,
    ) -> Result<String>;
}

/// Durable origin of one host invocation, without model-message fabrication.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub enum InvocationCause {
    /// Real provider-issued model tool call.
    ModelTool(ToolCallId),
    /// Host-issued lifecycle invocation intent.
    Lifecycle(smith::id::EntryId),
}

/// One dispatcher call's non-escalating primitive-effect grant.
///
/// Host imports validate capability grants before selecting primitives.
/// Hosts may compose synchronous children through exclusive reborrows, never
/// another outer call or concurrent mutable contexts.
pub struct ToolEffectContext<'a> {
    session: &'a mut ToolSession,
    operation: &'a str,
    scope: Option<&'a mut EffectScope<'a>>,
    workspace: Option<WorkspaceRoot>,
    workspace_only: bool,
    next_index: u16,
    active: bool,
    mutation_state: MutationState,
}

#[derive(Clone, Copy)]
struct EffectIdentity {
    id: smith::id::EntryId,
    index: u16,
    causal: Option<crate::metadata::NestedCausality>,
}

struct ChildInvocation {
    identity: EffectIdentity,
    operation: String,
}

/// Terminal host boundary shared by an outer invocation and all its children.
/// These failures are never model-recoverable tool outcomes.
#[derive(Clone, Copy, Debug, Eq, PartialEq, Serialize, Deserialize)]
pub enum InvocationStop {
    /// A host import observed cancellation before parent resumption.
    Cancelled,
    /// The root absolute deadline elapsed.
    Deadline,
    /// Cumulative execution fuel was exhausted.
    Fuel,
    /// Participating linear memory exceeded its ceiling.
    Memory,
    /// Participating table elements exceeded their ceiling.
    Table,
    /// Cumulative host allocations exceeded their ceiling.
    HostAllocation,
    /// A canonical ABI conversion exceeded its allowance.
    Conversion,
    /// Cumulative diagnostic entries or bytes exceeded their ceiling.
    Log,
    /// Cumulative intermediate or terminal output exceeded its ceiling.
    Output,
    /// A sandbox authority boundary was violated.
    Sandbox,
}

/// Actual cumulative allocation observation at a bounded host boundary.
/// This is requested allocation traffic, not live memory or RSS.
#[derive(Clone, Copy, Debug, PartialEq, Eq, Serialize, Deserialize)]
pub struct InvocationAllocationReport {
    /// Soft production threshold in requested bytes.
    pub threshold_bytes: u64,
    /// Actual cumulative bytes at the latest boundary, including bounded cleanup.
    pub actual_bytes: u64,
    /// Requested bytes spent on outer terminal recording after guest settlement.
    pub cleanup_bytes: u64,
    /// Actual requested bytes above the threshold, never clamped into compliance.
    pub excess_bytes: u64,
    /// Successful allocations and reallocations observed.
    pub allocations: u64,
    /// Actual bytes at the first observed crossing, before terminal cleanup.
    pub stopped_bytes: Option<u64>,
}

/// Host-owned allocation observer retained through bounded terminal recording.
/// Core owns only this synchronous interface, never an allocator dependency.
pub trait InvocationAllocationObserver {
    /// Snapshot actual cumulative requested bytes across the owned operation.
    ///
    /// # Errors
    /// Returns an observation failure rather than reporting untrustworthy counters.
    fn report(&self) -> Result<InvocationAllocationReport>;
}

struct EffectScope<'a> {
    cause: Option<InvocationCause>,
    lifecycle_root: Option<smith::id::EntryId>,
    redact: &'a dyn Fn(&str) -> String,
    component: Option<ToolComponentProvenance>,
    pending: Option<EffectIdentity>,
    children: Vec<ChildInvocation>,
    stop: Option<InvocationStop>,
    allocation: Option<InvocationAllocationReport>,
    allocation_observer: Option<Box<dyn InvocationAllocationObserver>>,
}

impl<'a> EffectScope<'a> {
    fn new(call_id: ToolCallId, redact: &'a dyn Fn(&str) -> String) -> Self {
        Self {
            cause: Some(InvocationCause::ModelTool(call_id)),
            lifecycle_root: None,
            redact,
            component: None,
            pending: None,
            children: Vec::new(),
            stop: None,
            allocation: None,
            allocation_observer: None,
        }
    }
}

struct WorkspaceScope<'context, 'session> {
    context: &'context mut ToolEffectContext<'session>,
    previous: Option<WorkspaceRoot>,
    workspace_only: bool,
}

impl Drop for WorkspaceScope<'_, '_> {
    fn drop(&mut self) {
        self.context.workspace = self.previous.take();
        self.context.workspace_only = self.workspace_only;
    }
}

impl<'a> ToolEffectContext<'a> {
    /// Restrict primitive effects to `operation` for one native host call.
    ///
    /// This is for hosts that invoke a component directly rather than through
    /// [`ToolSession::invoke`]. The caller still owns the outer durable record.
    #[must_use]
    pub const fn for_operation(session: &'a mut ToolSession, operation: &'a str) -> Self {
        Self {
            session,
            operation,
            scope: None,
            workspace: None,
            workspace_only: false,
            next_index: 0,
            active: false,
            mutation_state: MutationState::NotApplied,
        }
    }

    /// Whether this invocation requires one atomic completion boundary.
    #[must_use]
    pub const fn requires_atomic_completion(&self) -> bool {
        self.session.completion.is_some()
    }

    /// Confine guest filesystem effects to a held workspace descriptor.
    pub fn set_workspace_root(&mut self, workspace: WorkspaceRoot) {
        self.workspace = Some(workspace);
    }

    /// Hold this invocation's workspace descriptor before entering a granted guest.
    ///
    /// # Errors
    /// Returns the workspace open failure before any guest effect dispatch.
    pub fn confine_workspace(&mut self) -> Result<()> {
        if self.workspace.is_none() {
            self.workspace = Some(WorkspaceRoot::open(self.working_dir())?);
        }
        Ok(())
    }

    /// Run synchronously under a descendant of the currently held descriptor.
    /// Primitive authority is filesystem-only; ambient process authority cannot follow.
    /// Parent authority restores on return, error, or unwinding.
    ///
    /// # Errors
    /// Rejects an absent root or any path that escapes the held directory.
    pub fn with_workspace_subdirectory(
        &mut self,
        path: &str,
        run: impl FnOnce(&mut Self) -> Result<String>,
    ) -> Result<String> {
        let workspace = self
            .workspace
            .as_ref()
            .ok_or_else(|| {
                tool_error(
                    smith::error::ToolCode::Validation,
                    "workspace delegation requires a held root",
                )
            })?
            .narrow(path)?;
        let previous = self.workspace.replace(workspace);
        let workspace_only = std::mem::replace(&mut self.workspace_only, true);
        let scope = WorkspaceScope {
            context: self,
            previous,
            workspace_only,
        };
        run(scope.context)
    }

    /// Cancellation handle inherited from this outer durable effect.
    #[must_use]
    pub fn cancel_handle(&self) -> CancelHandle {
        self.session.cancel_handle()
    }

    /// Latch the first terminal host failure for this entire invocation subtree.
    /// Cancels subsequent effects even if a guest catches an import error.
    pub fn stop(&mut self, reason: InvocationStop) {
        if let Some(scope) = &mut self.scope {
            scope.stop.get_or_insert(reason);
        }
        if !self.is_lifecycle() {
            self.session.cancel.cancel();
        }
    }

    /// First terminal host failure, independent of guest return values.
    #[must_use]
    pub fn stop_reason(&self) -> Option<InvocationStop> {
        self.scope.as_ref().and_then(|scope| scope.stop)
    }

    /// Retain a host observer through outer completion recording.
    /// Unscoped native callers retain the returned observer themselves.
    pub fn hold_allocation_observer(
        &mut self,
        observer: Box<dyn InvocationAllocationObserver>,
    ) -> Option<Box<dyn InvocationAllocationObserver>> {
        if let Some(scope) = &mut self.scope {
            scope.allocation_observer = Some(observer);
            None
        } else {
            Some(observer)
        }
    }

    /// Record actual cumulative allocation traffic without reserving or rejecting malloc.
    pub fn report_allocation(&mut self, threshold_bytes: u64, actual_bytes: u64, allocations: u64) {
        if let Some(scope) = &mut self.scope {
            let stopped_bytes = scope
                .allocation
                .and_then(|report| report.stopped_bytes)
                .or_else(|| (actual_bytes > threshold_bytes).then_some(actual_bytes));
            scope.allocation = Some(InvocationAllocationReport {
                threshold_bytes,
                actual_bytes,
                cleanup_bytes: 0,
                excess_bytes: actual_bytes.saturating_sub(threshold_bytes),
                allocations,
                stopped_bytes,
            });
        }
    }

    /// Latest actual allocation observation for this root invocation.
    #[must_use]
    pub fn allocation_report(&self) -> Option<InvocationAllocationReport> {
        self.scope.as_ref().and_then(|scope| scope.allocation)
    }

    /// Immutable workspace directory associated with this call.
    #[must_use]
    pub fn working_dir(&self) -> &Path {
        self.session.working_dir()
    }

    /// Durable parent tool-call identity, when this context came from a tool dispatch.
    #[must_use]
    pub fn call_id(&self) -> Option<ToolCallId> {
        match self.cause()? {
            InvocationCause::ModelTool(call_id) => Some(call_id),
            InvocationCause::Lifecycle(_) => None,
        }
    }

    /// Pin actual component source and generation before guest entry.
    pub fn set_component_provenance(&mut self, component: ToolComponentProvenance) {
        if let Some(scope) = &mut self.scope {
            scope.component = Some(component);
        }
    }

    /// Current host-issued child invocation, or the outer tool boundary.
    #[must_use]
    pub fn invocation_id(&self) -> Option<smith::id::EntryId> {
        self.scope
            .as_ref()?
            .children
            .last()
            .map(|child| child.identity.id)
    }

    /// Run a host-selected child synchronously with an exclusive reborrow.
    ///
    /// The host validates authority before entry. Guests supply neither caller IDs
    /// nor completion claims. The closure may recursively reborrow this context;
    /// it must not retain it in another store while the parent is suspended.
    /// Invocation records are nonmutating; primitive records own mutation evidence.
    ///
    /// # Errors
    /// Bounds and cancellation reject before intent. Persistence uncertainty is
    /// terminal even if the caller catches the returned error.
    pub fn with_child(
        &mut self,
        operation: &str,
        input: &str,
        component: Option<ToolComponentProvenance>,
        run: impl FnOnce(&mut Self) -> Result<String>,
    ) -> Result<String> {
        let previous_component = self
            .scope
            .as_mut()
            .and_then(|scope| std::mem::replace(&mut scope.component, component));
        let result = self.run_child(operation, input, run);
        if let Some(scope) = &mut self.scope {
            scope.component = previous_component;
        }
        result
    }

    fn run_child(
        &mut self,
        operation: &str,
        input: &str,
        run: impl FnOnce(&mut Self) -> Result<String>,
    ) -> Result<String> {
        self.begin_nested_record(operation, input, true, true)?;
        let scope = self.scope.as_mut().ok_or_else(|| {
            tool_error(
                smith::error::ToolCode::Validation,
                "child requires admitted outer call",
            )
        })?;
        let identity = scope.pending.take().ok_or_else(|| {
            tool_error(smith::error::ToolCode::Validation, "child requires intent")
        })?;
        scope.children.push(ChildInvocation {
            identity,
            operation: operation.to_owned(),
        });
        self.active = false;
        let result = run(self);
        // An incomplete primitive must remain unknown, never be completed as a child.
        if self.active || self.session.recording_failed {
            return self.settle_invocation(result);
        }
        let scope = self.scope.as_mut().ok_or_else(|| {
            tool_error(smith::error::ToolCode::Validation, "child requires scope")
        })?;
        scope.children.pop();
        scope.pending = Some(identity);
        self.active = true;
        let result = self.check_stop(result);
        let output = match &result {
            Ok(output) => output.as_str(),
            Err(error) => &error.to_string(),
        };
        self.finish_nested_record(result.is_ok(), MutationState::NotApplied, output, true)?;
        result
    }

    /// Admit one bounded primitive effect under the current invocation before dispatch.
    ///
    /// # Errors
    /// Rejects unresolved effects, exhausted bounds, cancellation, or persistence failure.
    pub fn begin_nested(&mut self, operation: &str, input: &str) -> Result<()> {
        self.begin_nested_record(operation, input, true, false)
    }

    /// Record canonical evidence already redacted by its host mechanism.
    /// Does not text-redact wire schema, numbers, or binary hex a second time.
    ///
    /// # Errors
    /// Same admission and durability failures as [`Self::begin_nested`].
    pub fn begin_nested_redacted(&mut self, operation: &str, input: &str) -> Result<()> {
        self.begin_nested_record(operation, input, false, false)
    }

    #[expect(
        clippy::too_many_lines,
        reason = "one admission boundary selects typed model or lifecycle ownership before persistence"
    )]
    fn begin_nested_record(
        &mut self,
        operation: &str,
        input: &str,
        redact: bool,
        invocation: bool,
    ) -> Result<()> {
        use crate::metadata::{
            NESTED_EFFECT_BYTES_MAX, NESTED_EFFECTS_MAX, NESTED_PAYLOAD_BYTES_MAX,
            NestedEffectIntent, NestedPayload, NestedPayloadRef,
        };
        if self.is_lifecycle() {
            if invocation {
                return Err(tool_error(
                    smith::error::ToolCode::Validation,
                    "lifecycle composition unavailable",
                ));
            }
            return self.begin_lifecycle_effect(operation, input, redact);
        }
        self.session.ensure_recording()?;
        if self.next_index >= NESTED_EFFECTS_MAX {
            self.stop(InvocationStop::HostAllocation);
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "nested effect count budget exhausted",
            ));
        }
        if operation.is_empty()
            || operation.len() > 128
            || self.active
            || input.len() > NESTED_PAYLOAD_BYTES_MAX
        {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "nested effect count, depth, or input byte bound exceeded",
            ));
        }
        if self.session.cancel.is_cancelled() {
            return Err(SmithError::Cancelled);
        }
        if let Some(scope) = &mut self.scope
            && invocation
            && scope.children.capacity() == 0
        {
            scope
                .children
                .try_reserve_exact(usize::from(crate::metadata::NESTED_EFFECTS_MAX))
                .map_err(|_| {
                    tool_error(
                        smith::error::ToolCode::Validation,
                        "child stack allocation failed",
                    )
                })?;
        }
        let scope = self.scope.as_ref().ok_or_else(|| {
            tool_error(
                smith::error::ToolCode::Validation,
                "nested effect requires an outer call",
            )
        })?;
        let root = self.submission_id()?;
        let input = if redact {
            (scope.redact)(input)
        } else {
            input.to_owned()
        };
        if input.len() > NESTED_PAYLOAD_BYTES_MAX {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "redacted nested input exceeds byte bound",
            ));
        }
        let effect_id = smith::id::EntryId::new();
        let mut identity = EffectIdentity {
            id: effect_id,
            index: self.next_index,
            causal: (invocation || !scope.children.is_empty()).then_some(
                crate::metadata::NestedCausality {
                    effect_id,
                    parent: scope.children.last().map(|child| child.identity.id),
                    invocation,
                },
            ),
        };
        let detail = crate::metadata::encode_nested(
            NestedEffectIntent {
                submission_id: root,
                call_id: match scope.cause {
                    Some(InvocationCause::ModelTool(call_id)) => call_id,
                    Some(InvocationCause::Lifecycle(_)) | None => {
                        return Err(tool_error(
                            smith::error::ToolCode::Validation,
                            "model-only primitive unavailable to lifecycle",
                        ));
                    }
                },
                index: self.next_index,
                operation,
                component: scope.component.as_ref(),
                input: if input.len() <= NESTED_EFFECT_BYTES_MAX {
                    NestedPayload::Inline(&input)
                } else {
                    NestedPayload::Chunks(NestedPayloadRef {
                        payload_bytes: u32::try_from(input.len()).map_err(|_| {
                            tool_error(
                                smith::error::ToolCode::Validation,
                                "nested payload length overflow",
                            )
                        })?,
                    })
                },
            },
            identity.causal.as_ref(),
        )?;
        self.persist_intent(&input, &detail, &mut identity)?;
        if let Some(scope) = &mut self.scope {
            scope.pending = Some(identity);
        }
        self.next_index += 1;
        self.active = true;
        Ok(())
    }

    fn persist_intent(
        &mut self,
        input: &str,
        detail: &StructuredData,
        identity: &mut EffectIdentity,
    ) -> Result<()> {
        use crate::metadata::{NESTED_EFFECT_BYTES_MAX, NESTED_INTENT_KIND};
        if identity.causal.is_none() && input.len() <= NESTED_EFFECT_BYTES_MAX {
            identity.id = self
                .session
                .record(EntryContentRef::Meta {
                    kind: NESTED_INTENT_KIND,
                    detail,
                })?
                .id;
        } else {
            let mut entry = crate::session::EntryFrame::from_content(
                self.session.session.selected_id().as_ref(),
                &EntryContentRef::Meta {
                    kind: NESTED_INTENT_KIND,
                    detail,
                },
            )?;
            entry.id = identity.id;
            let persisted = (|| {
                if input.len() > NESTED_EFFECT_BYTES_MAX {
                    self.persist_payload(input, crate::frame::NestedPayloadPhase::Input, identity)?;
                }
                let boundary = self.session.completion.as_mut().ok_or_else(|| {
                    tool_error(
                        smith::error::ToolCode::Validation,
                        "nested intent requires root",
                    )
                })?;
                self.session
                    .session
                    .append_effect_with(entry, false, &mut boundary.persist)
            })();
            if let Err(error) = persisted {
                self.session.recording_failed = true;
                self.session.cancel.cancel();
                return Err(error);
            }
        }
        Ok(())
    }

    /// Atomically persist nested completion and root progress before guest resumption.
    ///
    /// # Errors
    /// Any uncertainty poisons this session, including when a guest catches the error.
    pub fn finish_nested(&mut self, ok: bool, mutation: MutationState, output: &str) -> Result<()> {
        self.finish_nested_record(ok, mutation, output, true)
    }

    /// Complete with canonical evidence already redacted by its host mechanism.
    /// Binary hex and fixed wire schema remain exact, without text substitution.
    ///
    /// # Errors
    /// Same poisoning and acknowledgement contract as [`Self::finish_nested`].
    pub fn finish_nested_redacted(
        &mut self,
        ok: bool,
        mutation: MutationState,
        output: &str,
    ) -> Result<()> {
        self.finish_nested_record(ok, mutation, output, false)
    }

    #[expect(
        clippy::too_many_lines,
        reason = "one completion boundary preserves model and lifecycle poisoning semantics"
    )]
    fn finish_nested_record(
        &mut self,
        ok: bool,
        mutation: MutationState,
        output: &str,
        redact: bool,
    ) -> Result<()> {
        use crate::metadata::{
            NESTED_COMPLETION_KIND, NESTED_EFFECT_BYTES_MAX, NESTED_PAYLOAD_BYTES_MAX,
            NestedEffectCompletion, NestedPayload, NestedPayloadRef,
        };
        if self.is_lifecycle() {
            return self.finish_lifecycle_effect(ok, mutation, output, redact);
        }
        self.mutation_state = aggregate_mutation(self.mutation_state, mutation);
        let completion = (|| {
            self.session.ensure_recording()?;
            if !self.active || output.len() > NESTED_PAYLOAD_BYTES_MAX {
                return Err(tool_error(
                    smith::error::ToolCode::Validation,
                    "nested completion missing intent or exceeds byte bound",
                ));
            }
            let scope = self.scope.as_ref().ok_or_else(|| {
                tool_error(
                    smith::error::ToolCode::Validation,
                    "nested completion requires outer call",
                )
            })?;
            let identity = scope.pending.ok_or_else(|| {
                tool_error(
                    smith::error::ToolCode::Validation,
                    "completion requires pending identity",
                )
            })?;
            let output = if redact {
                (scope.redact)(output)
            } else {
                output.to_owned()
            };
            if output.len() > NESTED_PAYLOAD_BYTES_MAX {
                return Err(tool_error(
                    smith::error::ToolCode::Validation,
                    "redacted nested output exceeds byte bound",
                ));
            }
            let root = self.submission_id()?;
            let detail = crate::metadata::encode_nested(
                NestedEffectCompletion {
                    submission_id: root,
                    call_id: match scope.cause {
                        Some(InvocationCause::ModelTool(call_id)) => call_id,
                        Some(InvocationCause::Lifecycle(_)) | None => {
                            return Err(tool_error(
                                smith::error::ToolCode::Validation,
                                "model-only primitive unavailable to lifecycle",
                            ));
                        }
                    },
                    index: identity.index,
                    ok,
                    mutation_state: mutation,
                    output: if output.len() <= NESTED_EFFECT_BYTES_MAX {
                        NestedPayload::Inline(&output)
                    } else {
                        NestedPayload::Chunks(NestedPayloadRef {
                            payload_bytes: u32::try_from(output.len()).map_err(|_| {
                                tool_error(
                                    smith::error::ToolCode::Validation,
                                    "nested payload length overflow",
                                )
                            })?,
                        })
                    },
                },
                identity.causal.as_ref(),
            )?;
            if output.len() > NESTED_EFFECT_BYTES_MAX {
                self.persist_payload(&output, crate::frame::NestedPayloadPhase::Output, &identity)?;
            }
            let boundary = self.session.completion.as_mut().ok_or_else(|| {
                tool_error(
                    smith::error::ToolCode::Validation,
                    "nested completion requires root",
                )
            })?;
            let entry = crate::session::EntryFrame::from_content(
                self.session.session.selected_id().as_ref(),
                &EntryContentRef::Meta {
                    kind: NESTED_COMPLETION_KIND,
                    detail: &detail,
                },
            )?;
            self.session
                .session
                .append_nested_with(entry, &mut boundary.persist)
        })();
        if let Err(error) = completion {
            self.session.recording_failed = true;
            self.session.cancel.cancel();
            return Err(SmithError::RecordFailed {
                tool: self.operation.to_string(),
                mutation_state: self.mutation_state,
                message: error.to_string(),
            });
        }
        self.active = false;
        if let Some(scope) = &mut self.scope {
            scope.pending = None;
        }
        Ok(())
    }

    fn submission_id(&self) -> Result<smith::id::EntryId> {
        self.session
            .completion
            .as_ref()
            .map(|boundary| boundary.submission_id)
            .ok_or_else(|| {
                tool_error(
                    smith::error::ToolCode::Validation,
                    "nested effect requires admitted work",
                )
            })
    }

    fn persist_payload(
        &mut self,
        value: &str,
        phase: crate::frame::NestedPayloadPhase,
        identity: &EffectIdentity,
    ) -> Result<()> {
        let call = self.call_id().ok_or_else(|| {
            tool_error(smith::error::ToolCode::Validation, "payload requires call")
        })?;
        let boundary = self.session.completion.as_mut().ok_or_else(|| {
            tool_error(smith::error::ToolCode::Validation, "payload requires root")
        })?;
        for (ordinal, bytes) in value
            .as_bytes()
            .chunks(crate::metadata::NESTED_CHUNK_BYTES_MAX)
            .enumerate()
        {
            let chunk = crate::frame::NestedPayloadChunk {
                submission_id: boundary.submission_id,
                call_id: call,
                effect_id: identity.id,
                index: identity.index,
                phase,
                ordinal: u16::try_from(ordinal).map_err(|_| {
                    tool_error(
                        smith::error::ToolCode::Validation,
                        "payload chunk count overflow",
                    )
                })?,
                bytes: bytes.to_vec(),
            };
            (boundary.persist)(crate::frame::Frame::NestedPayload {
                chunk: Box::new(chunk),
            })?;
        }
        Ok(())
    }

    fn settle_invocation(&mut self, effect: Result<String>) -> Result<String> {
        if (self.active
            || self
                .scope
                .as_ref()
                .is_some_and(|scope| !scope.children.is_empty()))
            && !self.session.recording_failed
        {
            self.session.recording_failed = true;
            self.session.cancel.cancel();
            self.mutation_state = aggregate_mutation(self.mutation_state, MutationState::Unknown);
        }
        if self.session.recording_failed {
            if matches!(&effect, Err(SmithError::RecordFailed { .. })) {
                return effect;
            }
            return Err(SmithError::RecordFailed {
                tool: self.operation.to_string(),
                mutation_state: self.mutation_state,
                message: "nested persistence uncertainty stopped invocation".into(),
            });
        }
        self.check_stop(effect)
    }

    fn check_stop(&self, effect: Result<String>) -> Result<String> {
        if self.stop_reason() == Some(InvocationStop::Cancelled) {
            return Err(SmithError::Cancelled);
        }
        if let Some(reason) = self.stop_reason() {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                format!(
                    "terminal host invocation stop: {reason:?}; allocation={:?}",
                    self.allocation_report()
                ),
            ));
        }
        effect
    }

    /// Persist legacy redacted HTTP metadata through this call's session writer.
    /// Admitted imports use [`Self::begin_nested`] and [`Self::finish_nested`]
    /// with full bounded request and response evidence.
    ///
    /// # Errors
    ///
    /// Returns recording failure before the associated transport may execute.
    pub fn record_plugin_http(
        &mut self,
        record: &smith::http::PluginHttpEffectRecord,
    ) -> Result<()> {
        if self.requires_atomic_completion() || self.is_lifecycle() {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "admitted HTTP requires full nested request and response evidence",
            ));
        }
        if let smith::http::PluginHttpEffectRecord::Outcome { outcome, .. } = record {
            let mutation = if *outcome == smith::http::PluginHttpEffectOutcome::Completed {
                MutationState::Applied
            } else {
                MutationState::Unknown
            };
            self.mutation_state = aggregate_mutation(self.mutation_state, mutation);
        }
        self.record_plugin_metadata(PLUGIN_HTTP_KIND, record)
    }

    /// Persist one redacted plugin diagnostic through this call's session writer.
    ///
    /// # Errors
    ///
    /// Returns the session recording failure.
    pub fn record_plugin_log(&mut self, record: &smith::http::PluginLogRecord) -> Result<()> {
        if self.is_lifecycle() {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "lifecycle log primitive unavailable",
            ));
        }
        if !self.requires_atomic_completion() {
            return self.record_plugin_metadata(PLUGIN_LOG_KIND, record);
        }
        let input = serde_json::to_string(record)
            .map_err(|error| tool_error(smith::error::ToolCode::Validation, error.to_string()))?;
        self.begin_nested("log", &input)?;
        self.finish_nested(true, MutationState::NotApplied, "recorded")
    }

    fn record_plugin_metadata<T: serde::Serialize>(
        &mut self,
        kind: &'static str,
        record: &T,
    ) -> Result<()> {
        let detail = encode_metadata(record)?;
        self.session.record(EntryContentRef::Meta {
            kind,
            detail: &detail,
        })?;
        Ok(())
    }

    /// Execute the granted primitive operation.
    ///
    /// # Errors
    ///
    /// Returns an authorization error before effects when `name` differs from
    /// the operation delegated by the outer call.
    pub fn invoke(&mut self, name: &str, input: &ToolArguments) -> Result<String> {
        let operation = self
            .scope
            .as_ref()
            .and_then(|scope| scope.children.last())
            .map_or(self.operation, |child| child.operation.as_str());
        if name != operation {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                format!(
                    "operation '{name}' exceeds delegated operation '{}'",
                    self.operation
                ),
            ));
        }
        self.invoke_redacted(name, input, str::to_string)
    }

    /// Execute a grant-checked host primitive with scoped registered-secret redaction.
    ///
    /// # Errors
    /// Returns primitive or durability failure; no subsequent effect follows uncertainty.
    pub fn invoke_redacted(
        &mut self,
        name: &str,
        input: &ToolArguments,
        redact: impl Fn(&str) -> String,
    ) -> Result<String> {
        self.session.ensure_recording()?;
        if self.is_lifecycle() {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "model-only primitive unavailable to lifecycle",
            ));
        }
        if self.workspace_only
            && !matches!(name, "read" | "write" | "edit" | "ls" | "find" | "grep")
        {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "non-filesystem primitive exceeds delegated workspace authority",
            ));
        }
        if self.requires_atomic_completion() {
            let text = serde_json::to_string(input).map_err(|error| {
                tool_error(smith::error::ToolCode::Validation, error.to_string())
            })?;
            self.begin_nested(name, &redact(&text))?;
        } else if name != self.operation {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "primitive exceeds delegated operation",
            ));
        }
        let effect = self
            .session
            .invoke_primitive_effect(name, input, self.workspace.as_ref());
        let mutation = mutation_state(name, &effect);
        if self.requires_atomic_completion() {
            let output = match &effect {
                Ok(text) => redact(text),
                Err(error) => redact(&error.to_string()),
            };
            self.finish_nested(effect.is_ok(), mutation, &output)?;
        } else {
            self.mutation_state = aggregate_mutation(self.mutation_state, mutation);
        }
        effect
    }
}

enum Persistence {
    None,
    Direct(SessionWriter),
    Worker(Box<PersistEntry>),
}

/// Bundles the registry, the live session, and durable persistence so a
/// successful mutation cannot be reported while recording failed.
pub struct ToolSession {
    registry: ToolRegistry,
    /// Live session state; entries are appended as they are recorded.
    pub session: Session,
    persistence: Persistence,
    completion: Option<CompletionBoundary>,
    /// All file effects resolve relative to this directory.
    working_dir: PathBuf,
    config: Config,
    cancel: CancelHandle,
    /// What `read` and `write` last observed per file, used to reject edits
    /// whose input describes an older version of the file.
    observed: HashMap<PathBuf, FileVersion>,
    /// Completion persistence failed; no further host effects may begin.
    recording_failed: bool,
    dispatcher: Option<Box<dyn ToolDispatcher>>,
    dynamic_tool_names: Vec<String>,
    advertised_tools: Arc<[ToolMetadata]>,
    request_policy: Option<Box<[(String, ToolPolicyState)]>>,
    loadout_provenance: Option<ToolLoadoutProvenance>,
    #[cfg(test)]
    test_effect_control: TestEffectControl,
}

/// Cheap identity of a file version: size plus modification time.
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
struct FileVersion {
    len: u64,
    modified_ms: i64,
}

impl FileVersion {
    #[cfg(target_os = "linux")]
    const fn from_workspace((len, modified_ms): (u64, i64)) -> Self {
        Self { len, modified_ms }
    }

    fn of(path: &Path) -> Option<Self> {
        let meta = fs::metadata(path).ok()?;
        let modified_ms = meta
            .modified()
            .ok()?
            .duration_since(std::time::UNIX_EPOCH)
            .ok()?
            .as_millis();
        Some(Self {
            len: meta.len(),
            modified_ms: i64::try_from(modified_ms).unwrap_or(i64::MAX),
        })
    }
}

impl ToolSession {
    /// A tool session with no published tools and no persistence.
    pub fn new(working_dir: impl Into<PathBuf>) -> Self {
        Self {
            registry: {
                #[cfg(test)]
                {
                    test_tool_registry()
                }
                #[cfg(not(test))]
                {
                    ToolRegistry::new()
                }
            },
            session: Session::new(),
            persistence: Persistence::None,
            completion: None,
            working_dir: working_dir.into(),
            config: Config::default_valid(),
            cancel: CancelHandle::new(),
            observed: HashMap::new(),
            recording_failed: false,
            dispatcher: None,
            dynamic_tool_names: Vec::new(),
            advertised_tools: Arc::from([]),
            request_policy: None,
            loadout_provenance: None,
            #[cfg(test)]
            test_effect_control: TestEffectControl::default(),
        }
    }

    /// Use `config` for effect timeouts and frame limits.
    #[must_use]
    pub fn with_config(mut self, config: Config) -> Self {
        self.config = config;
        self
    }

    pub(crate) fn ensure_recording(&self) -> Result<()> {
        if self.recording_failed {
            return Err(SmithError::Session {
                code: smith::error::SessionCode::SessionIncompleteContext,
                message: "recording persistence is uncertain; reopen before further effects".into(),
            });
        }
        Ok(())
    }

    pub(crate) const fn poison_recording(&mut self) {
        self.recording_failed = true;
    }

    pub(crate) const fn recording_failed(&self) -> bool {
        self.recording_failed
    }

    /// Every registered definition, including active hidden tools.
    #[must_use]
    pub fn registered_tools(&self) -> Arc<[ToolMetadata]> {
        self.registry.snapshot()
    }

    /// Definitions advertised by the current immutable provider round.
    #[must_use]
    pub fn advertised_tools(&self) -> Arc<[ToolMetadata]> {
        Arc::clone(&self.advertised_tools)
    }

    /// Immutable workspace directory for this session.
    #[must_use]
    pub fn working_dir(&self) -> &Path {
        &self.working_dir
    }

    /// A handle that aborts in-flight and subsequent effects of this session.
    #[must_use]
    pub fn cancel_handle(&self) -> CancelHandle {
        self.cancel.clone()
    }

    pub(crate) fn set_cancel_handle(&mut self, cancel: CancelHandle) {
        self.cancel = cancel;
    }

    #[cfg(test)]
    const fn cancel_at_checkpoint(&mut self, checkpoint: EffectCheckpoint) {
        self.test_effect_control.cancel_at = Some(checkpoint);
    }

    #[cfg(test)]
    const fn timeout_at_checkpoint(&mut self, checkpoint: EffectCheckpoint) {
        self.test_effect_control.timeout_at = Some(checkpoint);
    }

    /// Continue an existing session, appending every recorded entry to its
    /// durable writer.
    pub fn with_session(
        working_dir: impl Into<PathBuf>,
        session: Session,
        writer: SessionWriter,
    ) -> Self {
        Self {
            session,
            persistence: Persistence::Direct(writer),
            ..Self::new(working_dir)
        }
    }

    /// Keep persistence on an external storage worker.
    #[must_use]
    pub fn with_persist(
        working_dir: impl Into<PathBuf>,
        session: Session,
        persist: impl FnMut(&Entry, &[u8]) -> Result<()> + Send + 'static,
    ) -> Self {
        Self {
            session,
            persistence: Persistence::Worker(Box::new(persist)),
            ..Self::new(working_dir)
        }
    }

    /// Register or replace a tool definition.
    pub fn register(&mut self, meta: ToolMetadata) {
        self.registry.register(meta);
    }

    /// Bind admitted work to its session worker's atomic completion command.
    /// No result or conversation message is published before durable acknowledgement.
    #[must_use]
    pub fn with_completion_boundary(
        mut self,
        submission_id: smith::id::EntryId,
        persist: impl FnMut(crate::frame::Frame) -> Result<()> + Send + 'static,
    ) -> Self {
        self.completion = Some(CompletionBoundary {
            submission_id,
            persist: Box::new(persist),
        });
        self
    }

    pub(crate) const fn has_completion_boundary(&self) -> bool {
        self.completion.is_some()
    }

    /// Route validated calls through `dispatcher` instead of native effects.
    pub fn set_dispatcher(&mut self, dispatcher: Box<dyn ToolDispatcher>) {
        self.dispatcher = Some(dispatcher);
    }

    /// Pin extension definitions and handlers for one provider request and its
    /// complete tool-result batch.
    ///
    /// # Errors
    ///
    /// Returns before provider dispatch when extension publication fails.
    pub fn begin_provider_round(&mut self) -> Result<()> {
        let Some(mut dispatcher) = self.dispatcher.take() else {
            return Ok(());
        };
        let tools = dispatcher.begin_provider_round();
        self.dispatcher = Some(dispatcher);
        let mut snapshot = tools?;
        snapshot
            .tools
            .sort_by(|left, right| left.name.cmp(&right.name));
        snapshot
            .provenance
            .tools
            .sort_by(|left, right| left.definition.name.cmp(&right.definition.name));
        if snapshot.tools.len() != snapshot.provenance.tools.len()
            || snapshot
                .tools
                .iter()
                .zip(&snapshot.provenance.tools)
                .any(|(tool, provenance)| tool != &provenance.definition)
        {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "dispatcher tool definitions do not match provenance",
            ));
        }
        self.request_policy = Some(snapshot.policy.into_boxed_slice());
        self.loadout_provenance = Some(snapshot.provenance);
        if !snapshot.tools.is_empty() || !self.advertised_tools.is_empty() {
            self.advertised_tools = Arc::from(snapshot.tools);
        }
        for name in self.dynamic_tool_names.drain(..) {
            self.registry.tools.remove(&name);
        }
        for tool in snapshot.registered_tools {
            self.dynamic_tool_names.push(tool.name.clone());
            self.registry.register(tool);
        }
        Ok(())
    }

    pub(crate) fn lifecycle(
        &mut self,
        event: &smith::lifecycle::LifecycleEvent,
        redact: &dyn Fn(&str) -> String,
    ) -> Result<smith::lifecycle::LifecycleBatch> {
        self.ensure_recording()?;
        let Some(mut dispatcher) = self.dispatcher.take() else {
            return Ok(smith::lifecycle::LifecycleBatch::default());
        };
        if !dispatcher.has_lifecycle_handlers(event.boundary) {
            self.dispatcher = Some(dispatcher);
            return Ok(smith::lifecycle::LifecycleBatch::default());
        }
        // Root cancellation stops provider work, not bounded terminal cleanup.
        // Keep the original handle bound to durable control throughout notification.
        let root_cancel = if event.boundary == smith::lifecycle::Boundary::Settled {
            Some(std::mem::replace(&mut self.cancel, CancelHandle::new()))
        } else {
            None
        };
        if self.completion.is_none() && matches!(self.persistence, Persistence::None) {
            let result = dispatcher.lifecycle(event, &self.cancel);
            self.dispatcher = Some(dispatcher);
            if let Some(root_cancel) = root_cancel {
                self.cancel = root_cancel;
            }
            return result;
        }
        let mut scope = EffectScope {
            cause: None,
            lifecycle_root: Some(event.root_entry_id),
            redact,
            component: None,
            pending: None,
            children: Vec::new(),
            stop: None,
            allocation: None,
            allocation_observer: None,
        };
        let mut effects = ToolEffectContext {
            session: self,
            operation: "lifecycle",
            scope: Some(&mut scope),
            workspace: None,
            workspace_only: false,
            next_index: 0,
            active: false,
            mutation_state: MutationState::NotApplied,
        };
        let result = dispatcher.lifecycle_effects(event, &mut effects);
        let recording = effects.session.ensure_recording();
        effects.session.dispatcher = Some(dispatcher);
        if let Some(root_cancel) = root_cancel {
            effects.session.cancel = root_cancel;
        }
        let batch = result?;
        recording?;
        Ok(batch)
    }

    pub(crate) fn validate_lifecycle(
        &self,
        actions: &[smith::lifecycle::LifecycleAction],
        model: &str,
    ) -> Result<()> {
        if let Some(dispatcher) = &self.dispatcher {
            dispatcher.validate_lifecycle(actions, model)?;
        }
        Ok(())
    }

    pub(crate) fn commit_lifecycle(&mut self, actions: &[smith::lifecycle::LifecycleAction]) {
        if let Some(dispatcher) = &mut self.dispatcher {
            dispatcher.commit_lifecycle(actions);
        }
    }

    /// Persist the exact pinned dispatcher snapshot before an admitted provider request.
    ///
    /// # Errors
    ///
    /// Returns a recording error before provider dispatch.
    pub(crate) fn record_admitted_loadout_provenance(&mut self) -> Result<()> {
        let provenance = self.loadout_provenance.as_ref().ok_or_else(|| {
            tool_error(
                smith::error::ToolCode::Validation,
                "admitted provider request requires a dispatcher loadout snapshot",
            )
        })?;
        let advertised = &self.advertised_tools;
        if advertised.len() != provenance.tools.len()
            || advertised
                .iter()
                .zip(&provenance.tools)
                .any(|(tool, provenance)| tool != &provenance.definition)
        {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "advertised tools do not match dispatcher provenance",
            ));
        }
        let detail = crate::metadata::encode(provenance)?;
        self.record(EntryContentRef::Meta {
            kind: crate::session::TOOL_LOADOUT_PROVENANCE_KIND,
            detail: &detail,
        })
        .map(|_| ())
    }

    /// Release handlers pinned for the completed provider request and tool batch.
    pub fn end_provider_round(&mut self) {
        self.request_policy = None;
        if !self.advertised_tools.is_empty() {
            self.advertised_tools = Arc::from([]);
        }
        if let Some(dispatcher) = &mut self.dispatcher {
            dispatcher.end_provider_round();
        }
    }

    /// Validate arguments against the registered schema (required fields and
    /// declared property types) before any effect can run.
    ///
    /// # Errors
    ///
    /// Returns [`SmithError::Tool`] for unknown tools, non-object input,
    /// missing required fields, or mismatched field types.
    pub fn validate<'a, Input: StructuredValue<'a>>(&self, name: &str, input: Input) -> Result<()> {
        let meta = self
            .advertised_tools
            .iter()
            .find(|tool| tool.name == name)
            .or_else(|| self.registry.get(name))
            .ok_or_else(|| {
                tool_error(
                    smith::error::ToolCode::ToolNotRegistered,
                    format!("tool '{name}' not registered"),
                )
            })?;
        meta.input_schema.validate(input).map_err(|error| {
            let (code, message) = match error {
                SchemaError::InputNotObject => (
                    smith::error::ToolCode::InvalidInput,
                    format!("input for tool '{name}' must be a JSON object"),
                ),
                SchemaError::MissingField(field) => (
                    smith::error::ToolCode::Validation,
                    format!("missing required field '{field}' for tool '{name}'"),
                ),
                SchemaError::FieldType { field, expected } => (
                    smith::error::ToolCode::Validation,
                    format!("field '{field}' for tool '{name}' must be of type {expected}"),
                ),
                SchemaError::Access(error) => {
                    (smith::error::ToolCode::Validation, error.to_string())
                }
            };
            tool_error(code, message)
        })
    }

    /// Validate, execute, and durably record one trusted host tool call.
    /// Hidden tools remain active here; model calls use the request-pinned path.
    ///
    /// Recording order is call entry, effect, result entry, so a recorded
    /// call always precedes the effect it describes. A cancelled session
    /// refuses to start an effect. If the effect runs but its result cannot
    /// be recorded, the error states whether host state was already mutated,
    /// instead of presenting an unrecorded success.
    ///
    /// # Errors
    ///
    /// Returns [`SmithError::Cancelled`] when the session was cancelled,
    /// [`SmithError::RecordFailed`] when a completed effect could not be
    /// recorded, or the effect's own error.
    pub fn invoke(&mut self, name: &str, input: &ToolArguments) -> Result<ToolOutcome> {
        self.invoke_recorded(
            ToolCallId::new(),
            name,
            input,
            input,
            str::to_string,
            EffectFailure::ReturnError,
        )
    }

    /// Execute a model call under its originating request pin while recording
    /// only its redacted representation.
    ///
    /// `recorded_input` crosses persistence and provider boundaries;
    /// `effect_input` exists only for the duration of the authorized local
    /// effect. `redact_output` is applied before either the outcome or its
    /// durable result can escape that boundary. Executed tool failures become
    /// recorded outcomes so the model can observe and recover from them.
    pub(crate) fn invoke_local(
        &mut self,
        call_id: ToolCallId,
        name: &str,
        recorded_input: &ToolArguments,
        effect_input: &ToolArguments,
        redact_output: impl Fn(&str) -> String,
    ) -> Result<ToolOutcome> {
        self.authorize_model_call(name)?;
        self.invoke_recorded(
            call_id,
            name,
            recorded_input,
            effect_input,
            redact_output,
            EffectFailure::ReturnOutcome,
        )
    }

    fn authorize_model_call(&self, name: &str) -> Result<()> {
        if self.dispatcher.is_none() {
            return Ok(());
        }
        if self.request_policy.is_none() {
            return Err(tool_error(
                smith::error::ToolCode::ToolNotAdvertised,
                format!("tool '{name}' has no originating request pin; start a new provider round"),
            ));
        }
        self.authorize_active_call(name)?;
        if !self.advertised_tools.iter().any(|tool| tool.name == name) {
            return Err(tool_error(
                smith::error::ToolCode::ToolNotAdvertised,
                format!(
                    "tool '{name}' was not advertised by the originating request; request its qualified definition in a later round"
                ),
            ));
        }
        Ok(())
    }

    fn authorize_active_call(&self, name: &str) -> Result<()> {
        if self.dispatcher.is_none() {
            return Ok(());
        }
        let Some(policy) = &self.request_policy else {
            return Ok(());
        };
        let state = policy
            .iter()
            .find(|(identity, _)| identity == name)
            .map(|(_, state)| *state);
        match state {
            Some(ToolPolicyState::Advertised | ToolPolicyState::Hidden) => Ok(()),
            Some(ToolPolicyState::Disabled) => Err(tool_error(
                smith::error::ToolCode::ToolDisabled,
                format!(
                    "tool '{name}' is disabled by host policy; enable its qualified identity before retrying"
                ),
            )),
            None => Err(tool_error(
                smith::error::ToolCode::ToolNotRegistered,
                format!(
                    "tool '{name}' has no pinned registered identity; select an exact qualified tool advertised by this request"
                ),
            )),
        }
    }

    fn validate_admitted_call(&self, call_id: ToolCallId) -> Result<()> {
        use crate::session::EntryKind;
        let Some(boundary) = &self.completion else {
            return Ok(());
        };
        let entries = self.session.active_branch().entries();
        if call_id.as_u128() == 0
            || boundary.submission_id.as_u128() == 0
            || !entries.iter().any(|entry| {
                entry.id == boundary.submission_id
                    && matches!(
                        entry.kind,
                        EntryKind::Message {
                            role: smith::message::Role::User,
                            ..
                        }
                    )
            })
            || entries.iter().any(|entry| {
                matches!(entry.kind,
                EntryKind::ToolCall { call_id: prior } if prior == call_id)
            })
        {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "admitted tool call requires its root and a fresh nonzero effect identity",
            ));
        }
        Ok(())
    }

    #[expect(
        clippy::too_many_lines,
        reason = "one outer completion retains the allocation observer through dispatch, durable recording and terminal reporting"
    )]
    fn invoke_recorded(
        &mut self,
        call_id: ToolCallId,
        name: &str,
        recorded_input: &ToolArguments,
        effect_input: &ToolArguments,
        redact_output: impl Fn(&str) -> String,
        failure: EffectFailure,
    ) -> Result<ToolOutcome> {
        self.authorize_active_call(name)?;
        self.validate_admitted_call(call_id)?;
        if self.completion.is_some() && self.dispatcher.is_none() {
            return Err(tool_error(
                smith::error::ToolCode::Validation,
                "admitted tool call requires a component dispatcher",
            ));
        }
        self.validate(name, recorded_input.view())?;
        if self.recording_failed {
            return Err(SmithError::RecordFailed {
                tool: name.to_string(),
                mutation_state: MutationState::Unknown,
                message: "a prior completion recording failure stopped further effects".to_string(),
            });
        }
        if self.cancel.is_cancelled() && failure == EffectFailure::ReturnError {
            return Err(SmithError::Cancelled);
        }
        self.record(EntryContentRef::ToolCall {
            name,
            input: recorded_input,
            call_id,
        })?;
        let mut primitive_evidence = None;
        let mut allocation_observer = None;
        let mut allocation_report = None;
        let mut invocation_stop = None;
        let effect = if self.cancel.is_cancelled() {
            Err(SmithError::Cancelled)
        } else if let Some(mut dispatcher) = self.dispatcher.take() {
            let mut scope = EffectScope::new(call_id, &redact_output);
            let mut effects = ToolEffectContext {
                session: self,
                operation: name,
                scope: Some(&mut scope),
                workspace: None,
                workspace_only: false,
                next_index: 0,
                active: false,
                mutation_state: MutationState::NotApplied,
            };
            let effect = dispatcher.invoke(name, effect_input, &mut effects);
            let effect = effects.settle_invocation(effect);
            primitive_evidence = Some((effects.mutation_state, effects.stop_reason().is_some()));
            effects.session.dispatcher = Some(dispatcher);
            allocation_report = effects.allocation_report();
            invocation_stop = effects.stop_reason();
            if let Some(scope) = &mut effects.scope {
                allocation_observer = scope.allocation_observer.take();
            }
            effect
        } else {
            self.invoke_primitive_effect(name, effect_input, None)
        };
        let mut terminal = primitive_evidence.is_some_and(|(_, stopped)| stopped)
            || matches!(&effect, Err(SmithError::RecordFailed { .. }));
        let mut effect = effect;
        let mut ok = effect.is_ok();
        let mutation_state = primitive_evidence
            .map_or_else(|| mutation_state(name, &effect), |(mutation, _)| mutation);
        let mut output = match &effect {
            Ok(text) => redact_output(text),
            Err(error) => redact_output(&error.to_string()),
        };
        let detail = mutation_detail(call_id, mutation_state)?;
        // A known exhausted observation must not publish a successful completion.
        // Later recording allocations may still cross the soft threshold.
        if let Some(observer) = &allocation_observer
            && !self.recording_failed
        {
            let total = observer.report()?;
            if total.actual_bytes > total.threshold_bytes && invocation_stop.is_none() {
                invocation_stop = Some(InvocationStop::HostAllocation);
                self.cancel.cancel();
                terminal = true;
                ok = false;
                let error = tool_error(
                    smith::error::ToolCode::Validation,
                    format!("terminal host invocation stop: HostAllocation; allocation={total:?}"),
                );
                output = redact_output(&error.to_string());
                effect = Err(error);
            }
        }
        let mut completion = || -> Result<()> {
            self.ensure_recording()?;
            if self.completion.is_some() {
                return self.record_completion(call_id, ok, &output, &detail);
            }
            self.record(EntryContentRef::ToolResult {
                ok,
                output: &output,
                call_id,
            })?;
            self.record(EntryContentRef::Meta {
                kind: TOOL_MUTATION_KIND,
                detail: &detail,
            })?;
            Ok(())
        };
        if let Err(error) = completion() {
            self.recording_failed = true;
            self.cancel.cancel();
            let primary = match &effect {
                Err(primary @ SmithError::RecordFailed { .. }) => primary,
                _ => &error,
            };
            return Err(SmithError::RecordFailed {
                tool: name.to_string(),
                mutation_state,
                message: format!(
                    "{primary}; allocation={:?}",
                    allocation_observer
                        .as_ref()
                        .and_then(|observer| observer.report().ok())
                        .or(allocation_report)
                ),
            });
        }
        let mut outcome = ToolOutcome {
            call_id,
            name: name.to_string(),
            ok,
            output,
            timestamp_ms: now_ms(),
            mutation_state,
            allocation: None,
        };
        if let Some(observer) = &allocation_observer {
            let mut total = observer.report()?;
            total.stopped_bytes = allocation_report
                .and_then(|report| report.stopped_bytes)
                .or_else(|| {
                    (total.actual_bytes > total.threshold_bytes).then_some(total.actual_bytes)
                });
            total.cleanup_bytes = total
                .actual_bytes
                .saturating_sub(allocation_report.map_or(0, |report| report.actual_bytes));
            allocation_report = Some(total);
            if total.actual_bytes > total.threshold_bytes
                && invocation_stop.is_none_or(|reason| reason == InvocationStop::HostAllocation)
            {
                self.cancel.cancel();
                let stop = crate::metadata::InvocationTerminalStop {
                    submission_id: self
                        .completion
                        .as_ref()
                        .map(|boundary| boundary.submission_id),
                    call_id,
                    reason: InvocationStop::HostAllocation,
                    allocation: total,
                };
                // No exact self-measuring fixpoint: the report precedes its own
                // bounded encoding and acknowledgement, without erasing success.
                let recorded = crate::metadata::encode(&stop).and_then(|detail| {
                    self.record(EntryContentRef::Meta {
                        kind: crate::metadata::INVOCATION_TERMINAL_STOP_KIND,
                        detail: &detail,
                    })
                    .map(|_| ())
                });
                if let Err(error) = recorded {
                    self.recording_failed = true;
                    return Err(SmithError::RecordFailed {
                        tool: name.to_string(),
                        mutation_state,
                        message: format!("{error}; allocation={total:?}"),
                    });
                }
                return Err(tool_error(
                    smith::error::ToolCode::Validation,
                    format!("terminal host invocation stop: HostAllocation; allocation={total:?}"),
                ));
            }
        }
        outcome.allocation = allocation_report;
        match effect {
            Ok(_) => Ok(outcome),
            Err(_) if failure == EffectFailure::ReturnOutcome && !terminal => Ok(outcome),
            Err(error) => Err(error),
        }
    }

    fn record_completion(
        &mut self,
        call_id: ToolCallId,
        ok: bool,
        output: &str,
        detail: &StructuredData,
    ) -> Result<()> {
        use crate::session::EntryFrame;
        let result = EntryFrame::from_content(
            self.session.selected_id().as_ref(),
            &EntryContentRef::ToolResult {
                call_id,
                ok,
                output,
            },
        )?;
        let evidence = EntryFrame::from_content(
            Some(&result.id),
            &EntryContentRef::Meta {
                kind: TOOL_MUTATION_KIND,
                detail,
            },
        )?;
        let mut message = smith::message::Message::new(smith::message::Role::Tool);
        message.add_block(smith::message::ContentBlock::tool_result(
            call_id, ok, output,
        ));
        let conversation =
            EntryFrame::from_content(Some(&evidence.id), &EntryContentRef::Message(&message))?;
        let boundary = self.completion.as_mut().ok_or_else(|| {
            tool_error(
                smith::error::ToolCode::Validation,
                "missing atomic completion boundary",
            )
        })?;
        let frame = crate::frame::Frame::Commit {
            checkpoint: crate::frame::ToolCompletionCheckpoint {
                submission_id: boundary.submission_id,
                call_id,
            },
            entries: Box::new([result, evidence, conversation]),
        };
        self.session
            .append_commit_with(frame, &mut boundary.persist)
    }

    /// Execute a primitive effect while an outer dispatcher call owns its
    /// durable call/result lifecycle.
    ///
    /// The caller must hold a [`ToolEffectContext`], which restricts it to the
    /// outer call's operation and prevents recursive dispatch.
    fn invoke_primitive_effect(
        &mut self,
        name: &str,
        input: &ToolArguments,
        workspace: Option<&WorkspaceRoot>,
    ) -> std::result::Result<String, SmithError> {
        execute_effect(
            name,
            input,
            &self.working_dir,
            &self.config,
            &self.cancel,
            &mut self.observed,
            workspace,
            #[cfg(test)]
            self.test_effect_control,
        )
    }

    /// Append an atomic model-visible edit through this session's durable writer.
    /// Validation happens before persistence; failure never publishes projection.
    ///
    /// # Errors
    /// Rejects read-only/unpersisted sessions, invalid batches or uncertain recording.
    pub fn edit_context(
        &mut self,
        edits: &[crate::context::ContextEdit],
    ) -> Result<smith::id::EntryId> {
        self.ensure_recording()?;
        if matches!(self.persistence, Persistence::None) {
            return Err(crate::context::invalid(
                "context edits require writable durable session authority",
            ));
        }
        let persistence = &mut self.persistence;
        let frame_bytes_max = self.config.frame_bytes_max;
        let mut persistence_started = false;
        let result = self.session.edit_context_with(edits, |entry, content| {
            crate::frame::validate_entry_size(content, frame_bytes_max)?;
            persistence_started = true;
            match persistence {
                Persistence::None => Err(crate::context::invalid(
                    "context edits require writable durable session authority",
                )),
                Persistence::Direct(writer) => writer.append_entry(entry, content),
                Persistence::Worker(persist) => persist(entry, content),
            }
        });
        if persistence_started && result.is_err() {
            self.recording_failed = true;
        }
        result
    }

    /// Append `content` after the selected entry and durably record it
    /// first; a failed write leaves the session unchanged.
    pub(crate) fn record<'a>(&mut self, content: impl Into<EntryContentRef<'a>>) -> Result<Entry> {
        self.ensure_recording()?;
        let frame_bytes_max = self.config.frame_bytes_max;
        let persistence = &mut self.persistence;
        let mut persistence_started = false;
        let entry = self
            .session
            .append_with(content, |entry, bytes| {
                crate::frame::validate_entry_size(bytes, frame_bytes_max)?;
                persistence_started = true;
                match persistence {
                    Persistence::None => Ok(()),
                    Persistence::Direct(writer) => writer.append_entry(entry, bytes),
                    Persistence::Worker(persist) => persist(entry, bytes),
                }
            })
            .copied();
        let entry = match entry {
            Ok(entry) => entry,
            Err(error) => {
                if persistence_started {
                    self.recording_failed = true;
                }
                return Err(error);
            }
        };
        if entry.is_compaction() {
            self.session.retain_compacted_context()?;
        }
        Ok(entry)
    }
}

#[derive(Clone, Copy, PartialEq, Eq)]
enum EffectFailure {
    ReturnError,
    ReturnOutcome,
}

/// A recorded tool outcome returned to the caller.
#[derive(Clone, PartialEq, Eq, Debug, serde::Serialize, serde::Deserialize)]
pub struct ToolOutcome {
    /// Actual composition allocation traffic, including terminal recording.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub allocation: Option<InvocationAllocationReport>,
    /// Tool call ID.
    pub call_id: ToolCallId,
    /// Tool name.
    pub name: String,
    /// Whether the effect succeeded.
    pub ok: bool,
    /// Recorded output or error message.
    pub output: String,
    /// Timestamp of outcome.
    pub timestamp_ms: i64,
    /// Durable best-known host mutation outcome.
    pub mutation_state: MutationState,
}

const fn aggregate_mutation(prior: MutationState, next: MutationState) -> MutationState {
    match (prior, next) {
        (MutationState::Applied, _) | (_, MutationState::Applied) => MutationState::Applied,
        (MutationState::Unknown, _) | (_, MutationState::Unknown) => MutationState::Unknown,
        _ => MutationState::NotApplied,
    }
}

fn mutation_detail(call_id: ToolCallId, mutation_state: MutationState) -> Result<StructuredData> {
    encode_metadata(&ToolMutationMetadata::new(call_id, mutation_state))
}

fn tool_error(code: smith::error::ToolCode, message: impl Into<String>) -> SmithError {
    SmithError::Tool {
        code,
        message: message.into(),
    }
}

fn io_tool_error(code: smith::error::ToolCode) -> impl Fn(std::io::Error) -> SmithError {
    move |e| tool_error(code, e.to_string())
}

fn input_string<'a>(input: &'a ToolArguments, key: &str) -> Result<Option<&'a str>> {
    let Some(value) = input.view().field(key).map_err(structured_tool_error)? else {
        return Ok(None);
    };
    match value.kind().map_err(structured_tool_error)? {
        Kind::String(value) => Ok(Some(value)),
        _ => Ok(None),
    }
}

fn input_unsigned(input: &ToolArguments, key: &str) -> Result<Option<u64>> {
    let Some(value) = input.view().field(key).map_err(structured_tool_error)? else {
        return Ok(None);
    };
    match value.kind().map_err(structured_tool_error)? {
        Kind::Unsigned(value) => Ok(Some(value)),
        _ => Ok(None),
    }
}

fn structured_tool_error(error: smith::structured::AccessError) -> SmithError {
    tool_error(smith::error::ToolCode::Validation, error.to_string())
}

fn resolve_path(input_path: &str, working_dir: &Path) -> PathBuf {
    let p = Path::new(input_path);
    if p.is_absolute() {
        p.to_path_buf()
    } else {
        working_dir.join(p)
    }
}

/// Execute a built-in file effect. All outputs are bounded and deterministic;
/// filesystem errors are surfaced, never converted to empty success.
/// Infer only what effect-boundary evidence proves.
///
/// A shell's exit status says nothing about arbitrary commands it may have
/// executed, so every spawned shell is `Unknown`; only spawn failure proves
/// `NotApplied`. File publication and parent creation provide direct evidence.
fn mutation_state(name: &str, effect: &std::result::Result<String, SmithError>) -> MutationState {
    match name {
        "bash" => match effect {
            Err(
                SmithError::Cancelled
                | SmithError::Tool {
                    code: smith::error::ToolCode::BashSpawn,
                    ..
                },
            ) => MutationState::NotApplied,
            _ => MutationState::Unknown,
        },
        "write" | "edit" => match effect {
            Ok(_) => MutationState::Applied,
            Err(SmithError::Tool { code, .. })
                if matches!(code.as_str(), "CANCELLED_APPLIED" | "TOOL_TIMEOUT_APPLIED") =>
            {
                MutationState::Applied
            }
            Err(SmithError::Cancelled) => MutationState::NotApplied,
            Err(_) => MutationState::Unknown,
        },
        _ => MutationState::NotApplied,
    }
}

/// Cooperative checkpoints placed at bounded filesystem work boundaries.
#[derive(Clone, Copy, PartialEq, Eq)]
enum EffectCheckpoint {
    Start,
    TraversalEntry,
    ReadChunk,
    GrepLine,
    EditReadChunk,
    WriteChunk,
    ParentCreated,
    BeforePublish,
    AfterPublish,
}

#[cfg(test)]
#[derive(Clone, Copy, Default)]
struct TestEffectControl {
    cancel_at: Option<EffectCheckpoint>,
    timeout_at: Option<EffectCheckpoint>,
}

/// Cooperative cancellation and deadline checks around filesystem chunks.
///
/// Standard filesystem calls can block without a portable interruption API.
/// Smith therefore checks before and after bounded reads and writes, and
/// immediately before publication. A cancellation observed after `rename`
/// reports that the mutation was already applied; it never claims rollback.
struct EffectControl<'a> {
    cancel: &'a CancelHandle,
    deadline: Instant,
    #[cfg(test)]
    test_control: TestEffectControl,
}

impl<'a> EffectControl<'a> {
    fn new(
        cancel: &'a CancelHandle,
        timeout_ms: u64,
        #[cfg(test)] test_control: TestEffectControl,
    ) -> Self {
        Self {
            cancel,
            deadline: Instant::now() + Duration::from_millis(timeout_ms),
            #[cfg(test)]
            test_control,
        }
    }

    fn checkpoint(&self, _checkpoint: EffectCheckpoint, mutation_applied: bool) -> Result<()> {
        #[cfg(test)]
        if self.test_control.cancel_at == Some(_checkpoint) {
            self.cancel.cancel();
        }
        #[cfg(test)]
        if self.test_control.timeout_at == Some(_checkpoint) {
            return Err(Self::timeout_error(mutation_applied));
        }
        if self.cancel.is_cancelled() {
            return Err(if mutation_applied {
                tool_error(
                    smith::error::ToolCode::CancelledApplied,
                    "cancellation arrived after the file mutation was applied",
                )
            } else {
                SmithError::Cancelled
            });
        }
        if Instant::now() >= self.deadline {
            return Err(Self::timeout_error(mutation_applied));
        }
        Ok(())
    }

    fn timeout_error(mutation_applied: bool) -> SmithError {
        tool_error(
            if mutation_applied {
                smith::error::ToolCode::BashTimeoutApplied
            } else {
                smith::error::ToolCode::ToolTimeout
            },
            if mutation_applied {
                "tool deadline elapsed after the file mutation was applied"
            } else {
                "tool deadline elapsed before the effect completed"
            },
        )
    }
}

#[cfg_attr(
    test,
    expect(
        clippy::too_many_arguments,
        reason = "the shared primitive boundary receives test-only fault injection"
    )
)]
fn execute_effect(
    name: &str,
    input: &ToolArguments,
    working_dir: &Path,
    config: &Config,
    cancel: &CancelHandle,
    observed: &mut HashMap<PathBuf, FileVersion>,
    workspace: Option<&WorkspaceRoot>,
    #[cfg(test)] test_effect_control: TestEffectControl,
) -> std::result::Result<String, SmithError> {
    let control = EffectControl::new(
        cancel,
        config.tool_timeout_ms,
        #[cfg(test)]
        test_effect_control,
    );
    control.checkpoint(EffectCheckpoint::Start, false)?;
    let path_str = input_string(input, "path")?.unwrap_or_default();
    if let Some(workspace) = workspace
        && matches!(name, "read" | "write" | "edit" | "ls" | "find" | "grep")
    {
        return execute_workspace_effect(
            name, input, path_str, observed, config, &control, workspace,
        );
    }
    match name {
        "bash" => run_bash(input, working_dir, config.tool_timeout_ms, cancel),
        "read" => read_effect(
            input,
            resolve_path(path_str, working_dir),
            observed,
            &control,
        ),
        "write" => write_effect(
            input,
            resolve_path(path_str, working_dir),
            observed,
            &control,
        ),
        "edit" => edit_effect(
            input,
            resolve_path(path_str, working_dir),
            observed,
            &control,
        ),
        "ls" => {
            let dir = directory_or(path_str, working_dir);
            if !dir.is_dir() {
                return Err(tool_error(
                    smith::error::ToolCode::LsError,
                    format!("{} is not a directory", dir.display()),
                ));
            }
            let names = walk_relative(
                &dir,
                Some(1),
                config,
                &control,
                smith::error::ToolCode::LsError,
            )?;
            Ok(bounded_join(names, LIST_ENTRIES_MAX))
        }
        "find" => {
            let pattern = input_string(input, "pattern")?.unwrap_or_default();
            let root = directory_or(path_str, working_dir);
            if !root.is_dir() {
                return Err(tool_error(
                    smith::error::ToolCode::FindError,
                    format!("{} is not a directory", root.display()),
                ));
            }
            let names = walk_relative(
                &root,
                None,
                config,
                &control,
                smith::error::ToolCode::FindError,
            )?
            .into_iter()
            .filter(|name| pattern.is_empty() || name.contains(pattern))
            .collect();
            Ok(bounded_join(names, LIST_ENTRIES_MAX))
        }
        "grep" => {
            let query = input_string(input, "query")?.unwrap_or_default();
            let target = directory_or(path_str, working_dir);
            if target.is_dir() {
                grep_tree(&target, query, config, &control)
            } else {
                grep_bounded(&target, query, &control)
            }
        }
        _ => Err(tool_error(
            smith::error::ToolCode::ToolNotImplemented,
            format!("tool '{name}' has no built-in effect"),
        )),
    }
}

/// Execute a guest filesystem effect through a held workspace descriptor.
#[cfg(target_os = "linux")]
fn execute_workspace_effect(
    name: &str,
    input: &ToolArguments,
    path: &str,
    observed: &mut HashMap<PathBuf, FileVersion>,
    config: &Config,
    control: &EffectControl<'_>,
    workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
    match name {
        "read" => workspace_read(input, path, observed, control, workspace),
        "write" => workspace_write(input, path, observed, control, workspace),
        "edit" => workspace_edit(input, path, observed, control, workspace),
        "ls" => {
            let entries = workspace_walk(
                workspace,
                path,
                Some(1),
                config,
                control,
                smith::error::ToolCode::LsError,
            )?;
            Ok(bounded_join(entries, LIST_ENTRIES_MAX))
        }
        "find" => {
            let pattern = input_string(input, "pattern")?.unwrap_or_default();
            let entries = workspace_walk(
                workspace,
                path,
                None,
                config,
                control,
                smith::error::ToolCode::FindError,
            )?
            .into_iter()
            .filter(|entry| pattern.is_empty() || entry.contains(pattern))
            .collect();
            Ok(bounded_join(entries, LIST_ENTRIES_MAX))
        }
        "grep" => {
            let query = input_string(input, "query")?.unwrap_or_default();
            if workspace.is_directory(path) {
                workspace_grep_tree(workspace, path, query, config, control)
            } else {
                workspace_grep_file(workspace, path, query, control)
            }
        }
        _ => unreachable!("workspace dispatch includes only filesystem tools"),
    }
}

#[cfg(not(target_os = "linux"))]
fn execute_workspace_effect(
    _name: &str,
    _input: &ToolArguments,
    _path: &str,
    _observed: &mut HashMap<PathBuf, FileVersion>,
    _config: &Config,
    _control: &EffectControl<'_>,
    _workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
    Err(tool_error(
        smith::error::ToolCode::Validation,
        "workspace filesystem effects require Linux descriptor confinement",
    ))
}

#[cfg(target_os = "linux")]
fn workspace_read(
    input: &ToolArguments,
    path: &str,
    observed: &mut HashMap<PathBuf, FileVersion>,
    control: &EffectControl<'_>,
    workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
    let count = |key| {
        input_unsigned(input, key)
            .map(|value| value.map(|value| usize::try_from(value).unwrap_or(usize::MAX)))
    };
    let file = workspace
        .open_file(path)
        .map_err(io_tool_error(smith::error::ToolCode::ReadError))?;
    let text = read_bounded_file(
        file,
        count("offset")?.unwrap_or(0),
        count("limit")?.unwrap_or(usize::MAX),
        count("max_bytes")?.map_or(DEFAULT_OUTPUT_CAP, |bytes| bytes.min(HARD_OUTPUT_CAP)),
        control,
    )?;
    workspace_remember(path, observed, workspace);
    Ok(text)
}

#[cfg(target_os = "linux")]
fn workspace_write(
    input: &ToolArguments,
    path: &str,
    observed: &mut HashMap<PathBuf, FileVersion>,
    control: &EffectControl<'_>,
    workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
    let content = input_string(input, "content")?.ok_or_else(|| {
        tool_error(
            smith::error::ToolCode::Validation,
            "write requires string 'content'",
        )
    })?;
    workspace_write_atomic(workspace, path, content.as_bytes(), control)?;
    workspace_remember(path, observed, workspace);
    Ok(format!("written {} bytes", content.len()))
}

#[cfg(target_os = "linux")]
fn workspace_edit(
    input: &ToolArguments,
    path: &str,
    observed: &mut HashMap<PathBuf, FileVersion>,
    control: &EffectControl<'_>,
    workspace: &WorkspaceRoot,
) -> std::result::Result<String, SmithError> {
    let observed_path = PathBuf::from(path);
    if let Some(seen) = observed.get(&observed_path)
        && workspace
            .version(path)
            .ok()
            .map(FileVersion::from_workspace)
            != Some(*seen)
    {
        return Err(tool_error(
            smith::error::ToolCode::StaleInput,
            format!("{path} changed since it was last read; read it again before editing"),
        ));
    }
    let old = input_string(input, "old_string")?.unwrap_or_default();
    let new = input_string(input, "new_string")?.unwrap_or_default();
    let file = workspace
        .open_file(path)
        .map_err(io_tool_error(smith::error::ToolCode::EditReadError))?;
    let bytes = read_edit_input_file(file, control)?;
    let content = String::from_utf8(bytes).map_err(|_| {
        tool_error(
            smith::error::ToolCode::EditNotUtf8,
            "edit supports UTF-8 files only",
        )
    })?;
    let count = content.matches(old).count();
    if count == 0 {
        return Err(tool_error(
            smith::error::ToolCode::EditNotFound,
            "old_string not found; file unchanged",
        ));
    }
    if count > 1 {
        return Err(tool_error(
            smith::error::ToolCode::EditAmbiguous,
            format!("old_string matches {count} locations; file unchanged"),
        ));
    }
    let updated = content.replacen(old, new, 1);
    workspace_write_atomic(workspace, path, updated.as_bytes(), control)?;
    workspace_remember(path, observed, workspace);
    Ok("edited".to_string())
}

#[cfg(target_os = "linux")]
fn workspace_remember(
    path: &str,
    observed: &mut HashMap<PathBuf, FileVersion>,
    workspace: &WorkspaceRoot,
) {
    if let Ok(version) = workspace.version(path) {
        observed.insert(PathBuf::from(path), FileVersion::from_workspace(version));
    }
}

#[cfg(target_os = "linux")]
fn workspace_write_atomic(
    workspace: &WorkspaceRoot,
    path: &str,
    content: &[u8],
    control: &EffectControl<'_>,
) -> std::result::Result<(), SmithError> {
    control.checkpoint(EffectCheckpoint::WriteChunk, false)?;
    workspace
        .write_atomic(
            path,
            |parent_created| control.checkpoint(EffectCheckpoint::ParentCreated, parent_created),
            |file| {
                for chunk in content.chunks(64 * 1024) {
                    control
                        .checkpoint(EffectCheckpoint::WriteChunk, false)
                        .map_err(std::io::Error::other)?;
                    file.write_all(chunk)?;
                    control
                        .checkpoint(EffectCheckpoint::WriteChunk, false)
                        .map_err(std::io::Error::other)?;
                }
                control
                    .checkpoint(EffectCheckpoint::BeforePublish, false)
                    .map_err(std::io::Error::other)
            },
        )
        .map_err(|error| match error {
            crate::workspace::AtomicWriteError::Checkpoint(error) => error,
            crate::workspace::AtomicWriteError::Io(error) => {
                io_tool_error(smith::error::ToolCode::WriteError)(error)
            }
        })?;
    control.checkpoint(EffectCheckpoint::AfterPublish, true)
}

#[cfg(target_os = "linux")]
fn workspace_walk(
    workspace: &WorkspaceRoot,
    root: &str,
    depth_max: Option<usize>,
    config: &Config,
    control: &EffectControl<'_>,
    code: smith::error::ToolCode,
) -> std::result::Result<Vec<String>, SmithError> {
    if !workspace.is_directory(root) {
        return Err(tool_error(code, format!("{root} is not a directory")));
    }
    let mut entries = Vec::with_capacity(LIST_ENTRIES_MAX);
    let mut ignores = Vec::new();
    workspace_walk_directory(
        workspace,
        root,
        "",
        depth_max,
        config,
        control,
        code,
        &mut ignores,
        &mut entries,
    )?;
    Ok(entries)
}

#[cfg(target_os = "linux")]
#[expect(
    clippy::too_many_arguments,
    reason = "recursive traversal carries its bounded caller state without allocation"
)]
fn workspace_walk_directory(
    workspace: &WorkspaceRoot,
    root: &str,
    relative: &str,
    depth_max: Option<usize>,
    config: &Config,
    control: &EffectControl<'_>,
    code: smith::error::ToolCode,
    ignores: &mut Vec<crate::filters::DirectoryIgnore>,
    entries: &mut Vec<String>,
) -> std::result::Result<(), SmithError> {
    let path = workspace_path(root, relative);
    if config.respect_ignore_files {
        ignores.push(workspace_ignore_directory(
            workspace, root, relative, control, code,
        )?);
    }
    let result = (|| {
        for name in workspace
            .list_directory(&path, LIST_ENTRIES_MAX, || {
                control.checkpoint(EffectCheckpoint::TraversalEntry, false)
            })
            .map_err(|error| match error {
                crate::workspace::DirectoryReadError::Checkpoint(error) => error,
                crate::workspace::DirectoryReadError::Io(error) => io_tool_error(code)(error),
                crate::workspace::DirectoryReadError::Limit => {
                    tool_error(code, format!("directory entries exceed {LIST_ENTRIES_MAX}"))
                }
            })?
        {
            if !config.include_hidden && name.starts_with('.') {
                continue;
            }
            let child = if relative.is_empty() {
                name
            } else {
                format!("{relative}/{name}")
            };
            let child_path = workspace_path(root, &child);
            let directory = workspace.is_directory(&child_path);
            if config.respect_ignore_files && workspace_ignored(ignores, root, &child, directory) {
                continue;
            }
            if entries.len() == LIST_ENTRIES_MAX {
                return Err(tool_error(
                    code,
                    format!("directory entries exceed {LIST_ENTRIES_MAX}"),
                ));
            }
            entries.push(child.clone());
            let depth = child.matches('/').count() + 1;
            if directory && depth_max.is_none_or(|maximum| depth < maximum) {
                workspace_walk_directory(
                    workspace, root, &child, depth_max, config, control, code, ignores, entries,
                )?;
            }
        }
        Ok(())
    })();
    if config.respect_ignore_files {
        let _ignore = ignores.pop();
    }
    result
}

#[cfg(target_os = "linux")]
fn workspace_path(root: &str, relative: &str) -> String {
    if relative.is_empty() {
        root.to_string()
    } else if root.is_empty() {
        relative.to_string()
    } else {
        format!("{root}/{relative}")
    }
}

#[cfg(target_os = "linux")]
fn workspace_ignore_directory(
    workspace: &WorkspaceRoot,
    root: &str,
    relative: &str,
    control: &EffectControl<'_>,
    code: smith::error::ToolCode,
) -> std::result::Result<crate::filters::DirectoryIgnore, SmithError> {
    let directory = workspace_path(root, relative);
    let virtual_directory = PathBuf::from(&directory);
    let mut rules = Vec::with_capacity(3 * IGNORE_LINES_MAX);
    for name in [".git/info/exclude", ".gitignore", ".ignore"] {
        let path = workspace_path(&directory, name);
        let file = match workspace.open_file(&path) {
            Ok(file) => file,
            Err(error) if error.kind() == std::io::ErrorKind::NotFound => continue,
            Err(error) => return Err(io_tool_error(code)(error)),
        };
        let mut reader = BufReader::with_capacity(IGNORE_LINE_BYTES_MAX, file);
        let mut line = Vec::new();
        for _ in 0..IGNORE_LINES_MAX {
            control.checkpoint(EffectCheckpoint::TraversalEntry, false)?;
            line.clear();
            if !read_line_bounded(&mut reader, &mut line, IGNORE_LINE_BYTES_MAX)
                .map_err(io_tool_error(code))?
            {
                break;
            }
            rules.push((
                virtual_directory.join(".gitignore"),
                String::from_utf8_lossy(&line).into_owned(),
            ));
        }
        line.clear();
        if read_line_bounded(&mut reader, &mut line, IGNORE_LINE_BYTES_MAX)
            .map_err(io_tool_error(code))?
        {
            return Err(tool_error(
                code,
                format!("ignore file {path} exceeds {IGNORE_LINES_MAX} lines"),
            ));
        }
    }
    crate::filters::DirectoryIgnore::compile(&virtual_directory, rules)
        .map_err(|error| tool_error(code, format!("invalid ignore rule: {error}")))
}

#[cfg(target_os = "linux")]
fn workspace_ignored(
    ignores: &[crate::filters::DirectoryIgnore],
    root: &str,
    relative: &str,
    directory: bool,
) -> bool {
    let path = PathBuf::from(workspace_path(root, relative));
    for ignore in ignores.iter().rev() {
        match ignore.matches(&path, directory) {
            crate::filters::IgnoreMatch::Ignore => return true,
            crate::filters::IgnoreMatch::Whitelist => return false,
            crate::filters::IgnoreMatch::None => {}
        }
    }
    false
}

#[cfg(target_os = "linux")]
fn workspace_grep_tree(
    workspace: &WorkspaceRoot,
    root: &str,
    query: &str,
    config: &Config,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    let entries = workspace_walk(
        workspace,
        root,
        None,
        config,
        control,
        smith::error::ToolCode::GrepError,
    )?;
    let mut matches = Vec::new();
    let mut total_bytes = 0usize;
    for relative in entries {
        let path = if root.is_empty() {
            relative.clone()
        } else {
            format!("{root}/{relative}")
        };
        if workspace.is_directory(&path) {
            continue;
        }
        let Ok(lines) = workspace_grep_lines(workspace, &path, query, control) else {
            continue;
        };
        for (line_number, text) in lines {
            if matches.len() >= GREP_MATCHES_MAX
                || total_bytes + relative.len() + text.len() + 32 > DEFAULT_OUTPUT_CAP
            {
                matches.push("<truncated>".to_string());
                return Ok(matches.join("\n"));
            }
            let rendered = format!("{relative}:{line_number}:{text}");
            total_bytes += rendered.len();
            matches.push(rendered);
        }
    }
    Ok(matches.join("\n"))
}

#[cfg(target_os = "linux")]
fn workspace_grep_file(
    workspace: &WorkspaceRoot,
    path: &str,
    query: &str,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    Ok(bounded_join(
        workspace_grep_lines(workspace, path, query, control)?
            .into_iter()
            .map(|(_, text)| text)
            .collect(),
        GREP_MATCHES_MAX,
    ))
}

#[cfg(target_os = "linux")]
fn workspace_grep_lines(
    workspace: &WorkspaceRoot,
    path: &str,
    query: &str,
    control: &EffectControl<'_>,
) -> std::result::Result<Vec<(usize, String)>, SmithError> {
    let file = workspace
        .open_file(path)
        .map_err(io_tool_error(smith::error::ToolCode::GrepReadError))?;
    let mut reader = BufReader::with_capacity(64 * 1024, file);
    let mut lines = Vec::new();
    let mut line = Vec::new();
    let mut line_number = 0usize;
    let mut output_bytes = 0usize;
    loop {
        control.checkpoint(EffectCheckpoint::GrepLine, false)?;
        line.clear();
        if !read_line_bounded(&mut reader, &mut line, GREP_LINE_BYTES_MAX)
            .map_err(io_tool_error(smith::error::ToolCode::GrepReadError))?
        {
            break;
        }
        line_number += 1;
        if line.contains(&0) {
            break;
        }
        let text = String::from_utf8_lossy(&line).trim_end().to_string();
        if text.contains(query) {
            if output_bytes + text.len() > DEFAULT_OUTPUT_CAP {
                break;
            }
            output_bytes += text.len();
            lines.push((line_number, text));
            if lines.len() >= GREP_MATCHES_MAX {
                break;
            }
        }
    }
    Ok(lines)
}

/// Read a bounded window and remember the version that was shown.
fn read_effect(
    input: &ToolArguments,
    path: PathBuf,
    observed: &mut HashMap<PathBuf, FileVersion>,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    let count = |key: &str| {
        input_unsigned(input, key)
            .map(|value| value.map(|value| usize::try_from(value).unwrap_or(usize::MAX)))
    };
    let text = read_bounded(
        &path,
        count("offset")?.unwrap_or(0),
        count("limit")?.unwrap_or(usize::MAX),
        count("max_bytes")?.map_or(DEFAULT_OUTPUT_CAP, |bytes| bytes.min(HARD_OUTPUT_CAP)),
        control,
    )?;
    remember(path, observed);
    Ok(text)
}

/// Replace a file atomically and remember the version just written.
fn write_effect(
    input: &ToolArguments,
    path: PathBuf,
    observed: &mut HashMap<PathBuf, FileVersion>,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    let content = input_string(input, "content")?.ok_or_else(|| {
        tool_error(
            smith::error::ToolCode::Validation,
            "write requires string 'content'",
        )
    })?;
    write_atomic(&path, content.as_bytes(), control)?;
    remember(path, observed);
    Ok(format!("written {} bytes", content.len()))
}

/// Apply an exact replacement, refusing input that describes an older
/// version of the file.
///
/// An edit describes a file the caller has seen. If the file moved on since
/// then, applying the replacement would silently discard the newer content.
fn edit_effect(
    input: &ToolArguments,
    path: PathBuf,
    observed: &mut HashMap<PathBuf, FileVersion>,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    let old = input_string(input, "old_string")?.unwrap_or_default();
    let new = input_string(input, "new_string")?.unwrap_or_default();
    if let Some(seen) = observed.get(&path)
        && FileVersion::of(&path) != Some(*seen)
    {
        return Err(tool_error(
            smith::error::ToolCode::StaleInput,
            format!(
                "{} changed since it was last read; read it again before editing",
                path.display()
            ),
        ));
    }
    let result = edit_exact(&path, old, new, control)?;
    remember(path, observed);
    Ok(result)
}

/// Record the current version of `path` as the one the caller has seen.
fn remember(path: PathBuf, observed: &mut HashMap<PathBuf, FileVersion>) {
    if let Some(version) = FileVersion::of(&path) {
        observed.insert(path, version);
    }
}

/// The requested path, or the invocation directory when none was given.
fn directory_or(path_str: &str, working_dir: &Path) -> PathBuf {
    if path_str.is_empty() {
        working_dir.to_path_buf()
    } else {
        resolve_path(path_str, working_dir)
    }
}

/// Ignore-aware, deterministic walk of `root`.
///
/// Traversal order is sorted by path, and configured ignore files and hidden
/// entries are honored, so identical trees always produce identical results.
fn walker(root: &Path, depth_max: Option<usize>, config: &Config) -> crate::filters::Walker {
    crate::filters::Walker::new(
        root,
        depth_max,
        config.include_hidden,
        config.respect_ignore_files,
    )
}

/// Paths under `root`, relative to it, bounded and cancellable.
fn walk_relative(
    root: &Path,
    depth_max: Option<usize>,
    config: &Config,
    control: &EffectControl<'_>,
    code: smith::error::ToolCode,
) -> std::result::Result<Vec<String>, SmithError> {
    let mut names = Vec::new();
    for found in walker(root, depth_max, config) {
        control.checkpoint(EffectCheckpoint::TraversalEntry, false)?;
        let found = found.map_err(|error| tool_error(code, error))?;
        if found.depth() == 0 {
            continue;
        }
        names.push(
            found
                .path()
                .strip_prefix(root)
                .unwrap_or_else(|_| found.path())
                .to_string_lossy()
                .into_owned(),
        );
        if names.len() >= LIST_ENTRIES_MAX {
            break;
        }
    }
    Ok(names)
}

/// Search every non-ignored file under `root` for `query`.
///
/// Matches are reported as `relative/path:line:text`, bounded by match count
/// and total output, and unreadable or binary files are skipped rather than
/// failing the whole search.
fn grep_tree(
    root: &Path,
    query: &str,
    config: &Config,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    let mut matches: Vec<String> = Vec::new();
    let mut total_bytes = 0usize;
    for found in walker(root, None, config) {
        control.checkpoint(EffectCheckpoint::TraversalEntry, false)?;
        let found = found.map_err(|error| tool_error(smith::error::ToolCode::GrepError, error))?;
        if !found.is_file() {
            continue;
        }
        let relative = found
            .path()
            .strip_prefix(root)
            .unwrap_or_else(|_| found.path())
            .to_string_lossy()
            .into_owned();
        let Ok(file) = fs::File::open(found.path()) else {
            continue;
        };
        let mut reader = BufReader::with_capacity(64 * 1024, file);
        let mut line = Vec::new();
        let mut line_no = 0usize;
        loop {
            control.checkpoint(EffectCheckpoint::GrepLine, false)?;
            line.clear();
            if !matches!(
                read_line_bounded(&mut reader, &mut line, GREP_LINE_BYTES_MAX),
                Ok(true)
            ) {
                break;
            }
            control.checkpoint(EffectCheckpoint::GrepLine, false)?;
            if line.contains(&0) {
                break; // binary content
            }
            line_no += 1;
            let text = String::from_utf8_lossy(&line).trim_end().to_string();
            if !text.contains(query) {
                continue;
            }
            let rendered = format!("{relative}:{line_no}:{text}");
            if matches.len() >= GREP_MATCHES_MAX
                || total_bytes + rendered.len() > DEFAULT_OUTPUT_CAP
            {
                matches.push("<truncated>".to_string());
                return Ok(matches.join("\n"));
            }
            total_bytes += rendered.len();
            matches.push(rendered);
        }
    }
    Ok(matches.join("\n"))
}

/// Run one bounded, cancellable shell command in the invocation directory.
fn run_bash(
    input: &ToolArguments,
    working_dir: &Path,
    timeout_ms: u64,
    cancel: &CancelHandle,
) -> std::result::Result<String, SmithError> {
    let command = input_string(input, "command")?.ok_or_else(|| {
        tool_error(
            smith::error::ToolCode::Validation,
            "bash requires string 'command'",
        )
    })?;
    let requested = input_unsigned(input, "timeout_ms")?.unwrap_or(timeout_ms);
    let result = crate::bash::execute(
        command,
        working_dir.to_str(),
        requested.min(timeout_ms),
        DEFAULT_OUTPUT_CAP,
        cancel,
    )?;
    if result.cancelled {
        return Err(tool_error(
            smith::error::ToolCode::CancelledUnknown,
            "shell was cancelled after spawning; mutation state is unknown",
        ));
    }
    let mut output = result.stdout;
    if !result.stderr.is_empty() {
        if !output.is_empty() {
            output.push('\n');
        }
        output.push_str("[stderr] ");
        output.push_str(&result.stderr);
    }
    if result.timed_out {
        return Err(tool_error(
            smith::error::ToolCode::BashTimeout,
            format!("timed out after {requested} ms: {output}"),
        ));
    }
    match result.exit_code {
        Some(0) => Ok(output),
        Some(code) => Err(tool_error(
            smith::error::ToolCode::BashExit,
            format!("exit {code}: {output}"),
        )),
        None => Err(tool_error(
            smith::error::ToolCode::BashKilled,
            format!("terminated without exit status: {output}"),
        )),
    }
}

/// Read a bounded line window without materializing the whole file.
fn read_bounded(
    path: &Path,
    offset: usize,
    limit: usize,
    bytes_max: usize,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    control.checkpoint(EffectCheckpoint::ReadChunk, false)?;
    let file = fs::File::open(path).map_err(io_tool_error(smith::error::ToolCode::ReadError))?;
    read_bounded_file(file, offset, limit, bytes_max, control)
}

/// Read one bounded file descriptor window without reopening its path.
fn read_bounded_file(
    file: fs::File,
    offset: usize,
    limit: usize,
    bytes_max: usize,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    control.checkpoint(EffectCheckpoint::ReadChunk, false)?;
    let mut reader = BufReader::with_capacity(64 * 1024, file);
    // Binary sniff on the first bytes.
    let sniff = reader
        .fill_buf()
        .map_err(io_tool_error(smith::error::ToolCode::ReadError))?;
    control.checkpoint(EffectCheckpoint::ReadChunk, false)?;
    if sniff[..sniff.len().min(8192)].contains(&0) {
        return Err(tool_error(
            smith::error::ToolCode::BinaryContent,
            "file contains NUL bytes; binary content is unsupported",
        ));
    }
    let mut out = String::new();
    let mut buffer: Vec<u8> = Vec::with_capacity(8 * 1024);
    let mut line_no = 0usize;
    let mut bytes_out = 0usize;
    loop {
        control.checkpoint(EffectCheckpoint::ReadChunk, false)?;
        buffer.clear();
        #[expect(
            clippy::disallowed_methods,
            reason = "Take caps one read-tool line before truncation is reported"
        )]
        let bytes_read = (&mut reader)
            .take((DEFAULT_OUTPUT_CAP + 1) as u64)
            .read_until(b'\n', &mut buffer)
            .map_err(io_tool_error(smith::error::ToolCode::ReadError))?;
        let line_ended = buffer.ends_with(b"\n")
            || reader
                .fill_buf()
                .map_err(io_tool_error(smith::error::ToolCode::ReadError))?
                .is_empty();
        if bytes_read == 0 || buffer.len() > DEFAULT_OUTPUT_CAP || !line_ended {
            break;
        }
        control.checkpoint(EffectCheckpoint::ReadChunk, false)?;
        line_no += 1;
        if line_no <= offset {
            continue;
        }
        let emit = if limit == usize::MAX {
            true
        } else {
            (line_no - offset) <= limit
        };
        if !emit {
            break;
        }
        if bytes_out + buffer.len() > bytes_max {
            break; // keep fitting prefix only
        }
        bytes_out += buffer.len();
        out.push_str(&String::from_utf8_lossy(&buffer));
        if bytes_out >= bytes_max {
            break;
        }
    }
    Ok(out)
}

/// Atomically replace `path` with `content`: temp file in the same
/// directory, synced, then renamed over the destination.
fn write_atomic(
    path: &Path,
    content: &[u8],
    control: &EffectControl<'_>,
) -> std::result::Result<(), SmithError> {
    control.checkpoint(EffectCheckpoint::WriteChunk, false)?;
    let parent = path.parent().filter(|p| !p.as_os_str().is_empty());
    if let Some(parent) = parent {
        let parent_existed = parent.is_dir();
        fs::create_dir_all(parent).map_err(io_tool_error(smith::error::ToolCode::WriteMkdir))?;
        control.checkpoint(EffectCheckpoint::ParentCreated, !parent_existed)?;
        control.checkpoint(EffectCheckpoint::WriteChunk, !parent_existed)?;
    }
    let temporary = temp_sibling(path);
    let write = || -> std::result::Result<(), SmithError> {
        let mut file = fs::File::create(&temporary)
            .map_err(io_tool_error(smith::error::ToolCode::WriteError))?;
        control.checkpoint(EffectCheckpoint::WriteChunk, false)?;
        for chunk in content.chunks(64 * 1024) {
            control.checkpoint(EffectCheckpoint::WriteChunk, false)?;
            file.write_all(chunk)
                .map_err(io_tool_error(smith::error::ToolCode::WriteError))?;
            control.checkpoint(EffectCheckpoint::WriteChunk, false)?;
        }
        control.checkpoint(EffectCheckpoint::WriteChunk, false)?;
        file.sync_all()
            .map_err(io_tool_error(smith::error::ToolCode::WriteError))?;
        control.checkpoint(EffectCheckpoint::BeforePublish, false)
    };
    if let Err(error) = write() {
        // Preserve the write failure; temporary-file removal is best-effort cleanup.
        let _cleanup_result: std::io::Result<()> = fs::remove_file(&temporary);
        return Err(error);
    }
    control.checkpoint(EffectCheckpoint::BeforePublish, false)?;
    fs::rename(&temporary, path).map_err(|error| {
        // Preserve the publish failure; temporary-file removal is best-effort cleanup.
        let _cleanup_result: std::io::Result<()> = fs::remove_file(&temporary);
        io_tool_error(smith::error::ToolCode::WritePublish)(error)
    })?;
    control.checkpoint(EffectCheckpoint::AfterPublish, true)
}

/// A hidden sibling path used for atomic publication.
fn temp_sibling(path: &Path) -> PathBuf {
    static COUNTER: AtomicUsize = AtomicUsize::new(0);
    let n = COUNTER.fetch_add(1, Ordering::Relaxed);
    let name = path.file_name().map_or_else(
        || "file".to_string(),
        |name| name.to_string_lossy().into_owned(),
    );
    path.with_file_name(format!(".{name}.tmp-{}-{n}", std::process::id()))
}

/// Apply exactly one unambiguous replacement, publishing atomically.
fn edit_exact(
    path: &Path,
    old: &str,
    new: &str,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    let meta = fs::metadata(path).map_err(io_tool_error(smith::error::ToolCode::EditReadError))?;
    if meta.len() > u64::try_from(EDIT_FILE_BYTES_MAX).unwrap_or(u64::MAX) {
        return Err(tool_error(
            smith::error::ToolCode::FileTooLarge,
            "edit input exceeds the file size limit",
        ));
    }
    let bytes = read_edit_input(path, meta.len(), control)?;
    let content = String::from_utf8(bytes).map_err(|_| {
        tool_error(
            smith::error::ToolCode::EditNotUtf8,
            "edit supports UTF-8 files only",
        )
    })?;
    let count = content.matches(old).count();
    if count == 0 {
        return Err(tool_error(
            smith::error::ToolCode::EditNotFound,
            "old_string not found; file unchanged",
        ));
    }
    if count > 1 {
        return Err(tool_error(
            smith::error::ToolCode::EditAmbiguous,
            format!("old_string matches {count} locations; file unchanged"),
        ));
    }
    let updated = content.replacen(old, new, 1);
    write_atomic(path, updated.as_bytes(), control)?;
    Ok("edited".to_string())
}

/// Read edit input in bounded chunks so cancellation stays live between reads.
fn read_edit_input(
    path: &Path,
    expected_len: u64,
    control: &EffectControl<'_>,
) -> std::result::Result<Vec<u8>, SmithError> {
    let file =
        fs::File::open(path).map_err(io_tool_error(smith::error::ToolCode::EditReadError))?;
    let capacity = usize::try_from(expected_len).unwrap_or(EDIT_FILE_BYTES_MAX);
    read_edit_input_file_with_capacity(file, capacity, control)
}

/// Read one edit target without reopening its descriptor-confined path.
fn read_edit_input_file(
    file: fs::File,
    control: &EffectControl<'_>,
) -> std::result::Result<Vec<u8>, SmithError> {
    read_edit_input_file_with_capacity(file, EDIT_FILE_BYTES_MAX, control)
}

fn read_edit_input_file_with_capacity(
    mut file: fs::File,
    capacity: usize,
    control: &EffectControl<'_>,
) -> std::result::Result<Vec<u8>, SmithError> {
    control.checkpoint(EffectCheckpoint::EditReadChunk, false)?;
    let mut bytes = Vec::with_capacity(capacity);
    let mut chunk = [0_u8; 16 * 1024];
    loop {
        control.checkpoint(EffectCheckpoint::EditReadChunk, false)?;
        let read = file
            .read(&mut chunk)
            .map_err(io_tool_error(smith::error::ToolCode::EditReadError))?;
        control.checkpoint(EffectCheckpoint::EditReadChunk, false)?;
        if read == 0 {
            break;
        }
        if bytes.len() + read > EDIT_FILE_BYTES_MAX {
            return Err(tool_error(
                smith::error::ToolCode::FileTooLarge,
                "edit input exceeds the file size limit",
            ));
        }
        bytes.extend_from_slice(&chunk[..read]);
    }
    Ok(bytes)
}

/// Deterministic, bounded listing output.
fn bounded_join(mut names: Vec<String>, cap: usize) -> String {
    names.truncate(cap);
    let mut out = names.join("\n");
    let max = DEFAULT_OUTPUT_CAP;
    if out.len() > max {
        out.truncate(max);
        out.push_str("\n<truncated>");
    }
    out
}

/// Stream matching lines with bounded memory and result count.
fn grep_bounded(
    path: &Path,
    query: &str,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    let file =
        fs::File::open(path).map_err(io_tool_error(smith::error::ToolCode::GrepReadError))?;
    grep_bounded_file(file, query, control)
}

/// Search one already-open file descriptor.
fn grep_bounded_file(
    file: fs::File,
    query: &str,
    control: &EffectControl<'_>,
) -> std::result::Result<String, SmithError> {
    control.checkpoint(EffectCheckpoint::GrepLine, false)?;
    let mut reader = BufReader::with_capacity(64 * 1024, file);
    let mut matches: Vec<String> = Vec::new();
    let mut total_bytes = 0usize;
    loop {
        control.checkpoint(EffectCheckpoint::GrepLine, false)?;
        let mut line = Vec::new();
        #[expect(
            clippy::disallowed_methods,
            reason = "Take caps one grep line before overflow is reported"
        )]
        let bytes_read = (&mut reader)
            .take((GREP_LINE_BYTES_MAX + 1) as u64)
            .read_until(b'\n', &mut line)
            .map_err(io_tool_error(smith::error::ToolCode::GrepReadError))?;
        if bytes_read == 0 {
            break;
        }
        let line_ended = line.ends_with(b"\n")
            || reader
                .fill_buf()
                .map_err(io_tool_error(smith::error::ToolCode::GrepReadError))?
                .is_empty();
        if line.len() > GREP_LINE_BYTES_MAX || !line_ended {
            matches.push("<truncated>".to_string());
            break;
        }
        if line.ends_with(b"\n") {
            line.pop();
        }
        if line.last() == Some(&b'\r') {
            line.pop();
        }
        control.checkpoint(EffectCheckpoint::GrepLine, false)?;
        let line = String::from_utf8(line).map_err(|error| {
            io_tool_error(smith::error::ToolCode::GrepReadError)(std::io::Error::new(
                std::io::ErrorKind::InvalidData,
                error,
            ))
        })?;
        if line.contains(query) {
            if matches.len() >= GREP_MATCHES_MAX || total_bytes + line.len() > DEFAULT_OUTPUT_CAP {
                matches.push("<truncated>".to_string());
                break;
            }
            total_bytes += line.len();
            matches.push(line);
        }
    }
    Ok(matches.join("\n"))
}

/// Wall-clock milliseconds since the Unix epoch, saturating on overflow.
fn now_ms() -> i64 {
    std::time::SystemTime::now()
        .duration_since(std::time::UNIX_EPOCH)
        .map_or(0, |elapsed| {
            i64::try_from(elapsed.as_millis()).unwrap_or(i64::MAX)
        })
}

#[cfg(test)]
pub(crate) fn test_tool_snapshot() -> Result<crate::tools::ToolDispatcherSnapshot> {
    let tools = crate::tools::test_tool_registry().snapshot().to_vec();
    let components = vec![crate::tools::ToolComponentProvenance {
        source_id: "test-component".into(),
        manifest_sha256: "0".repeat(64),
        component_sha256: "1".repeat(64),
    }];
    let provenance = crate::tools::ToolLoadoutProvenance {
        components,
        tools: tools
            .iter()
            .cloned()
            .map(|definition| crate::tools::ToolLoadoutTool {
                definition,
                component_index: 0,
            })
            .collect(),
    };
    Ok(crate::tools::ToolDispatcherSnapshot {
        policy: tools
            .iter()
            .map(|tool| (tool.name.clone(), crate::tools::ToolPolicyState::Advertised))
            .collect(),
        registered_tools: tools.clone(),
        tools,
        provenance,
    })
}

#[cfg(test)]
#[expect(
    clippy::unwrap_used,
    clippy::panic,
    reason = "tests may panic on invariant violations"
)]
mod tests {
    #[test]
    fn empty_lifecycle_dispatcher_adds_no_boundary_allocations() {
        struct Empty;
        impl super::ToolDispatcher for Empty {
            fn invoke(
                &mut self,
                _: &str,
                _: &smith::ToolArguments,
                _: &mut super::ToolEffectContext<'_>,
            ) -> smith::Result<String> {
                unreachable!()
            }
        }
        let mut tools = super::ToolSession::new(std::env::temp_dir());
        tools.set_dispatcher(Box::new(Empty));
        let event = smith::lifecycle::LifecycleEvent {
            root_entry_id: smith::id::EntryId::new(),
            boundary: smith::lifecycle::Boundary::Settled,
            round_index: 0,
            last_stop: smith::stream::StopReason::EndTurn,
            continuation_eligible: false,
        };
        let (result, cost) = smith_alloc::measure(smith_alloc::Scope::Session, || {
            tools.lifecycle(&event, &str::to_owned)
        });
        result.unwrap();
        assert_eq!(cost.allocations, 0);
    }

    use super::*;

    macro_rules! test_args {
        ($($value:tt)*) => {
            ToolArguments::from_serializable(&serde_json::json!($($value)*)).unwrap()
        };
    }
    use crate::process_signal::{ProcessSignal, closed};
    use crate::session::EntryContent;
    use crate::session::EntryKind;
    use std::path::PathBuf;
    use std::sync::mpsc;
    use std::thread;

    fn workdir(tag: &str) -> PathBuf {
        let dir = std::env::temp_dir().join(format!("smith_tools_{}_{}", tag, std::process::id()));
        let _ = std::fs::remove_dir_all(&dir);
        std::fs::create_dir_all(&dir).unwrap();
        dir
    }

    #[cfg(target_os = "linux")]
    struct ConfinedDispatcher {
        workspace: WorkspaceRoot,
    }

    #[cfg(target_os = "linux")]
    impl ToolDispatcher for ConfinedDispatcher {
        fn invoke(
            &mut self,
            name: &str,
            input: &ToolArguments,
            effects: &mut ToolEffectContext<'_>,
        ) -> Result<String> {
            effects.set_workspace_root(self.workspace.clone());
            effects.invoke(name, input)
        }
    }

    #[cfg(target_os = "linux")]
    fn confined_session(dir: &Path) -> ToolSession {
        let mut session = ToolSession::new(dir);
        session.set_dispatcher(Box::new(ConfinedDispatcher {
            workspace: WorkspaceRoot::open(dir).unwrap(),
        }));
        session
    }

    struct SequentialWrites;

    impl ToolDispatcher for SequentialWrites {
        fn invoke(
            &mut self,
            _: &str,
            input: &ToolArguments,
            effects: &mut ToolEffectContext<'_>,
        ) -> Result<String> {
            effects.invoke("write", input)?;
            effects.invoke(
                "write",
                &test_args!({"path":"second.txt","content":"second"}),
            )
        }
    }

    struct PolicyDispatcher(ToolPolicyState);

    impl ToolDispatcher for PolicyDispatcher {
        fn begin_provider_round(&mut self) -> Result<ToolDispatcherSnapshot> {
            let mut snapshot = test_tool_snapshot()?;
            snapshot
                .policy
                .iter_mut()
                .for_each(|(_, state)| *state = self.0);
            if self.0 != ToolPolicyState::Advertised {
                snapshot.tools.clear();
                snapshot.provenance.tools.clear();
            }
            Ok(snapshot)
        }

        fn invoke(
            &mut self,
            _: &str,
            _: &ToolArguments,
            _: &mut ToolEffectContext<'_>,
        ) -> Result<String> {
            Ok("host-called".into())
        }
    }

    #[test]
    fn admitted_hidden_inventory_does_not_invalidate_advertised_provenance() {
        let mut tools = ToolSession::new(std::env::temp_dir());
        tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Hidden)));
        tools.begin_provider_round().unwrap();
        tools.record_admitted_loadout_provenance().unwrap();
        assert!(tools.advertised_tools().is_empty());
        assert!(!tools.registered_tools().is_empty());
    }

    #[test]
    fn model_cannot_invoke_registered_but_unadvertised_tool() {
        let mut tools = ToolSession::new(std::env::temp_dir());
        tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Hidden)));
        tools.begin_provider_round().unwrap();
        let input = ToolArguments::from_json(r#"{"path":"never-open"}"#).unwrap();
        let error = tools
            .invoke_local(ToolCallId::new(), "read", &input, &input, str::to_string)
            .unwrap_err();
        assert!(
            matches!(
                error,
                SmithError::Tool {
                    code: smith::error::ToolCode::ToolNotAdvertised,
                    ..
                }
            ),
            "{error}"
        );
        assert!(tools.session.active_branch().entries().is_empty());
    }

    #[test]
    fn hidden_active_tool_remains_available_to_trusted_host_invocation() {
        let mut tools = ToolSession::new(std::env::temp_dir());
        tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Hidden)));
        tools.begin_provider_round().unwrap();
        let input = ToolArguments::from_json(r#"{"path":"never-open"}"#).unwrap();
        let outcome = tools.invoke("read", &input).unwrap();
        assert_eq!(outcome.output, "host-called");
        assert!(outcome.ok);
        assert!(tools.advertised_tools().is_empty());
    }

    #[test]
    fn disabled_tool_rejects_every_caller_before_handler_or_ledger() {
        let mut tools = ToolSession::new(std::env::temp_dir());
        tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Disabled)));
        tools.begin_provider_round().unwrap();
        let input = ToolArguments::from_json(r#"{"path":"never-open"}"#).unwrap();
        for error in [
            tools.invoke("read", &input).unwrap_err(),
            tools
                .invoke_local(ToolCallId::new(), "read", &input, &input, str::to_string)
                .unwrap_err(),
        ] {
            assert!(
                matches!(
                    error,
                    SmithError::Tool {
                        code: smith::error::ToolCode::ToolDisabled,
                        ..
                    }
                ),
                "{error}"
            );
        }
        assert!(tools.session.active_branch().entries().is_empty());
    }

    #[test]
    fn model_cannot_reuse_a_released_request_pin() {
        let mut tools = ToolSession::new(std::env::temp_dir());
        tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Advertised)));
        tools.begin_provider_round().unwrap();
        tools.end_provider_round();
        let input = ToolArguments::from_json(r#"{"path":"never-open"}"#).unwrap();
        let error = tools
            .invoke_local(ToolCallId::new(), "read", &input, &input, str::to_string)
            .unwrap_err();
        assert!(
            matches!(
                error,
                SmithError::Tool {
                    code: smith::error::ToolCode::ToolNotAdvertised,
                    ..
                }
            ),
            "{error}"
        );
        assert!(tools.session.active_branch().entries().is_empty());
    }

    #[test]
    fn model_arguments_use_originating_schema_not_later_registration() {
        let mut tools = ToolSession::new(std::env::temp_dir());
        tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Advertised)));
        tools.begin_provider_round().unwrap();
        let mut replacement = tools.registry.get("read").unwrap().clone();
        replacement.input_schema = smith::structured::ToolSchema::empty_object();
        tools.register(replacement);
        let input = ToolArguments::from_json("{}").unwrap();
        let error = tools
            .invoke_local(ToolCallId::new(), "read", &input, &input, str::to_string)
            .unwrap_err();
        assert!(
            matches!(
                error,
                SmithError::Tool {
                    code: smith::error::ToolCode::Validation,
                    ..
                }
            ),
            "{error}"
        );
        assert!(tools.session.active_branch().entries().is_empty());
    }

    #[test]
    fn advertised_authorization_allocates_nothing() {
        let mut tools = ToolSession::new(std::env::temp_dir());
        tools.set_dispatcher(Box::new(PolicyDispatcher(ToolPolicyState::Advertised)));
        tools.begin_provider_round().unwrap();
        let (result, cost) = smith_alloc::measure(smith_alloc::Scope::KernelCall, || {
            tools.authorize_model_call("read")
        });
        result.unwrap();
        assert_eq!(cost.allocations, 0);
        assert_eq!(std::mem::size_of::<ToolPolicyState>(), 1);
        #[cfg(target_pointer_width = "64")]
        assert_eq!(std::mem::size_of::<(String, ToolPolicyState)>(), 32);
    }

    #[test]
    fn admitted_sequential_writes_have_independent_durable_intents() {
        let dir = workdir("nested_writes");
        let mut tools = ToolSession::new(&dir);
        let root = tools
            .session
            .append(&EntryContent::Message(smith::message::Message::with_text(
                smith::message::Role::User,
                "write twice",
            )))
            .unwrap()
            .id;
        tools.set_dispatcher(Box::new(SequentialWrites));
        let mut tools = tools.with_completion_boundary(root, |_| Ok(()));
        let outcome = tools
            .invoke("write", &test_args!({"path":"first.txt","content":"first"}))
            .unwrap();
        assert!(outcome.ok, "{}", outcome.output);
        assert_eq!(
            std::fs::read_to_string(dir.join("second.txt")).unwrap(),
            "second"
        );
        let intents = tools.session.active_branch().entries().iter().filter(|entry| {
            matches!(tools.session.content(entry).unwrap(), EntryContent::Meta { kind, .. } if kind == "nested-effect-intent")
        }).count();
        assert_eq!(intents, 2);
        std::fs::remove_dir_all(dir).unwrap();
    }

    #[test]
    fn listing_and_searching_respect_ignore_rules_and_hidden_entries() {
        let dir = workdir("ignore_rules");
        std::fs::write(dir.join(".gitignore"), "ignored.txt\n").unwrap();
        std::fs::write(dir.join("keep.txt"), "needle here\n").unwrap();
        std::fs::write(dir.join("ignored.txt"), "needle here\n").unwrap();
        std::fs::write(dir.join(".hidden.txt"), "needle here\n").unwrap();
        std::fs::create_dir_all(dir.join("nested")).unwrap();
        std::fs::write(dir.join("nested/deep.txt"), "needle deep\n").unwrap();

        let mut ts = ToolSession::new(&dir);
        // find walks recursively and drops ignored and hidden paths.
        let found = ts
            .invoke("find", &test_args!({"pattern": ""}))
            .unwrap()
            .output;
        assert_eq!(found, "keep.txt\nnested\nnested/deep.txt");
        // ls stays one level deep, with the same filtering.
        let listed = ts.invoke("ls", &test_args!({})).unwrap().output;
        assert_eq!(listed, "keep.txt\nnested");
        // grep searches the tree and locates each match.
        let hits = ts
            .invoke("grep", &test_args!({"path": "", "query": "needle"}))
            .unwrap()
            .output;
        assert_eq!(
            hits,
            "keep.txt:1:needle here\nnested/deep.txt:1:needle deep"
        );

        // Configuration decides: without ignore rules, everything shows up.
        let mut config = Config::default_valid();
        config.respect_ignore_files = false;
        config.include_hidden = true;
        let mut permissive = ToolSession::new(&dir).with_config(config);
        let found = permissive
            .invoke("find", &test_args!({"pattern": ".txt"}))
            .unwrap()
            .output;
        assert_eq!(found, ".hidden.txt\nignored.txt\nkeep.txt\nnested/deep.txt");
        let hits = permissive
            .invoke("grep", &test_args!({"path": "", "query": "needle here"}))
            .unwrap()
            .output;
        assert_eq!(
            hits,
            ".hidden.txt:1:needle here\nignored.txt:1:needle here\nkeep.txt:1:needle here"
        );
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn confined_walk_preserves_gitignore_ignore_negation_and_grep() {
        let dir = workdir("confined_ignore");
        std::fs::write(dir.join(".gitignore"), "*.log\n/only-root.txt\n").unwrap();
        std::fs::create_dir_all(dir.join(".git/info")).unwrap();
        std::fs::write(dir.join(".git/info/exclude"), "excluded.txt\n").unwrap();
        std::fs::create_dir_all(dir.join("nested")).unwrap();
        std::fs::write(dir.join("nested/.ignore"), "!keep.log\n").unwrap();
        std::fs::write(dir.join("drop.log"), "needle root\n").unwrap();
        std::fs::write(dir.join("excluded.txt"), "needle excluded\n").unwrap();
        std::fs::write(dir.join("only-root.txt"), "needle root-only\n").unwrap();
        std::fs::write(dir.join("nested/drop.log"), "needle drop\n").unwrap();
        std::fs::write(dir.join("nested/keep.log"), "needle keep\n").unwrap();
        std::fs::write(dir.join("nested/only-root.txt"), "needle nested-only\n").unwrap();

        let mut session = confined_session(&dir);
        assert_eq!(
            session
                .invoke("find", &test_args!({"pattern": ".log"}))
                .unwrap()
                .output,
            "nested/keep.log"
        );
        assert_eq!(
            session
                .invoke("find", &test_args!({"pattern": "only-root.txt"}))
                .unwrap()
                .output,
            "nested/only-root.txt"
        );
        assert_eq!(
            session
                .invoke("grep", &test_args!({"path": "", "query": "needle"}))
                .unwrap()
                .output,
            "nested/keep.log:1:needle keep\nnested/only-root.txt:1:needle nested-only"
        );
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn confined_grep_output_cap_preserves_rendered_matches_and_truncation() {
        let dir = workdir("confined_grep_cap");
        let text = format!("needle-{}", "x".repeat(400));
        let input = (1..=GREP_MATCHES_MAX)
            .map(|_| format!("{text}\n"))
            .collect::<String>();
        std::fs::write(dir.join("matches.txt"), input).unwrap();

        let output = confined_session(&dir)
            .invoke("grep", &test_args!({"path": "", "query": "needle"}))
            .unwrap()
            .output;
        let expected = (1..=155)
            .map(|line_number| format!("matches.txt:{line_number}:{text}"))
            .chain(std::iter::once("<truncated>".to_string()))
            .collect::<Vec<_>>()
            .join("\n");
        assert_eq!(output, expected);
        std::fs::remove_dir_all(dir).unwrap();
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn confined_directory_limit_is_exact_and_cancellable_during_read() {
        let dir = workdir("confined_directory_limit");
        for index in 0..LIST_ENTRIES_MAX {
            std::fs::write(dir.join(format!("{index:04}")), "").unwrap();
        }
        let mut session = confined_session(&dir);
        assert_eq!(
            session
                .invoke("ls", &test_args!({}))
                .unwrap()
                .output
                .lines()
                .count(),
            LIST_ENTRIES_MAX
        );
        std::fs::write(dir.join("1000"), "").unwrap();
        let error = confined_session(&dir)
            .invoke("ls", &test_args!({}))
            .unwrap_err();
        assert_eq!(error.code(), "LS_ERROR");
        assert!(error.to_string().contains("directory entries exceed 1000"));

        let mut session = confined_session(&dir);
        session.cancel_at_checkpoint(EffectCheckpoint::TraversalEntry);
        let error = session.invoke("ls", &test_args!({})).unwrap_err();
        assert_eq!(error.code(), "CANCELLED");
    }

    #[cfg(target_os = "linux")]
    #[test]
    fn confined_parent_creation_cancellation_and_timeout_record_applied() {
        for (tag, code, configure) in [
            (
                "confined_parent_cancellation",
                "CANCELLED_APPLIED",
                ToolSession::cancel_at_checkpoint as fn(&mut ToolSession, EffectCheckpoint),
            ),
            (
                "confined_parent_timeout",
                "TOOL_TIMEOUT_APPLIED",
                ToolSession::timeout_at_checkpoint as fn(&mut ToolSession, EffectCheckpoint),
            ),
        ] {
            let dir = workdir(tag);
            let mut session = confined_session(&dir);
            configure(&mut session, EffectCheckpoint::ParentCreated);
            let error = session
                .invoke(
                    "write",
                    &test_args!({"path": "a/b/target.txt", "content": "new"}),
                )
                .unwrap_err();
            assert_eq!(error.code(), code);
            assert!(dir.join("a/b").is_dir());
            assert!(!dir.join("a/b/target.txt").exists());
            let entry = session.session.active_branch().entries().last().unwrap();
            assert!(matches!(
                session.session.content(entry).unwrap(),
                EntryContent::Meta { detail, .. }
                    if serde_json::to_value(&detail).unwrap()["mutation_state"] == "applied"
            ));
        }
    }

    #[test]
    fn edit_rejects_input_that_describes_an_older_version_of_the_file() {
        let dir = workdir("stale_edit");
        let target = dir.join("doc.txt");
        std::fs::write(&target, "alpha one\n").unwrap();
        let mut ts = ToolSession::new(&dir);
        ts.invoke("read", &test_args!({"path": "doc.txt"})).unwrap();

        // Somebody else rewrites the file after the read; same length, so only the mtime tells.
        std::fs::write(&target, "alpha two\n").unwrap();
        // inject: pin the rewrite's mtime past the read instead of sleeping for a clock tick.
        let later = std::fs::metadata(&target).unwrap().modified().unwrap()
            + std::time::Duration::from_secs(60);
        std::fs::File::options()
            .write(true)
            .open(&target)
            .unwrap()
            .set_modified(later)
            .unwrap();

        let error = ts
            .invoke(
                "edit",
                &test_args!({"path": "doc.txt", "old_string": "alpha", "new_string": "beta"}),
            )
            .unwrap_err();
        assert_eq!(error.code(), "STALE_INPUT");
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "alpha two\n");

        // Re-reading refreshes the observed version and unblocks the edit.
        ts.invoke("read", &test_args!({"path": "doc.txt"})).unwrap();
        ts.invoke(
            "edit",
            &test_args!({"path": "doc.txt", "old_string": "alpha", "new_string": "beta"}),
        )
        .unwrap();
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "beta two\n");
    }

    #[test]
    fn bash_effect_runs_in_the_workdir_and_is_recorded() {
        let dir = workdir("bash_effect");
        let mut ts = ToolSession::new(&dir);
        let outcome = ts
            .invoke(
                "bash",
                &test_args!({"command": "printf hi > made.txt; printf done"}),
            )
            .unwrap();
        assert!(outcome.ok);
        assert_eq!(outcome.mutation_state, MutationState::Unknown);
        assert_eq!(outcome.output, "done");
        assert_eq!(std::fs::read_to_string(dir.join("made.txt")).unwrap(), "hi");
        // A recorded call always precedes its result.
        let kinds: Vec<&str> = ts
            .session
            .active_branch()
            .entries()
            .iter()
            .map(|e| match e.kind {
                EntryKind::ToolCall { .. } => "call",
                EntryKind::ToolResult { .. } => "result",
                _ => "other",
            })
            .collect();
        assert_eq!(kinds, vec!["call", "result", "other"]);
        assert_eq!(
            ts.session.mutation_state(outcome.call_id).unwrap(),
            MutationState::Unknown
        );
    }

    #[test]
    fn cancelled_shell_after_write_records_unknown_mutation_state() {
        let dir = workdir("bash_cancelled_mutation");
        let signal = ProcessSignal::new();
        let command = format!("printf made > made.txt; {}; sleep 30", signal.raise());
        let mut ts = ToolSession::new(&dir);
        let cancel = ts.cancel_handle();
        let (done, finished) = mpsc::channel();
        thread::spawn(move || {
            let error = ts
                .invoke(
                    "bash",
                    &test_args!({"command": command, "timeout_ms": 30_000}),
                )
                .unwrap_err();
            done.send((error, ts)).unwrap();
        });
        let mut socket = signal.wait();
        cancel.cancel();
        assert!(closed(&mut socket), "cancelled shell kept running");
        let (error, ts) = finished.recv_timeout(Duration::from_secs(10)).unwrap();
        assert_eq!(error.code(), "CANCELLED_UNKNOWN");
        assert_eq!(
            std::fs::read_to_string(dir.join("made.txt")).unwrap(),
            "made"
        );
        let entry = ts.session.active_branch().entries().last().unwrap();
        let EntryContent::Meta { detail, .. } = ts.session.content(entry).unwrap() else {
            unreachable!()
        };
        let call_id =
            serde_json::from_value(serde_json::to_value(&detail).unwrap()["call_id"].clone())
                .unwrap();
        assert_eq!(
            ts.session.mutation_state(call_id).unwrap(),
            MutationState::Unknown
        );
    }

    #[test]
    fn failing_and_timing_out_commands_report_explicitly() {
        let dir = workdir("bash_failures");
        let mut ts = ToolSession::new(&dir);
        let error = ts
            .invoke("bash", &test_args!({"command": "exit 3"}))
            .unwrap_err();
        assert_eq!(error.code(), "BASH_EXIT");
        let error = ts
            .invoke(
                "bash",
                &test_args!({"command": "sleep 5", "timeout_ms": 150}),
            )
            .unwrap_err();
        assert_eq!(error.code(), "BASH_TIMEOUT");
        // Both failures stay durable evidence, recorded as failed results.
        let failed = ts
            .session
            .active_branch()
            .entries()
            .iter()
            .filter(|e| matches!(e.kind, EntryKind::ToolResult { ok: false, .. }))
            .count();
        assert_eq!(failed, 2);
    }

    #[test]
    fn cancellation_stops_effects_before_they_start() {
        let dir = workdir("cancel_effects");
        let mut ts = ToolSession::new(&dir);
        let cancel = ts.cancel_handle();
        cancel.cancel();
        let error = ts
            .invoke("write", &test_args!({"path": "never.txt", "content": "x"}))
            .unwrap_err();
        assert_eq!(error.code(), "CANCELLED");
        assert!(!dir.join("never.txt").exists());
        // A refused call records nothing.
        assert!(ts.session.active_branch().entries().is_empty());
    }

    #[test]
    fn cancelling_a_running_command_aborts_it() {
        let dir = workdir("cancel_running");
        let mut ts = ToolSession::new(&dir);
        let cancel = ts.cancel_handle();
        let signal = crate::process_signal::ProcessSignal::new();
        let command = format!("{}; sleep 30", signal.raise());
        let running = std::thread::spawn(move || {
            ts.invoke(
                "bash",
                &test_args!({"command": command, "timeout_ms": 30_000}),
            )
        });
        // synchronize: cancel once the command reports it runs, never after a guessed delay.
        let mut socket = signal.wait();
        cancel.cancel();
        // Before the join: a survivor would hold the pipes and stall it.
        assert!(
            crate::process_signal::closed(&mut socket),
            "command kept running"
        );
        let error = running.join().unwrap().unwrap_err();
        assert_eq!(error.code(), "CANCELLED_UNKNOWN");
    }

    #[test]
    fn unrecordable_result_after_a_mutation_reports_the_mutation() {
        let dir = workdir("record_failed");
        let session_path = dir.join("session.smh");
        let mut cfg = Config::default_valid();
        cfg.frame_bytes_max = 1024;
        let opened = crate::store::open_session(&session_path, cfg.clone()).unwrap();
        let mut ts =
            ToolSession::with_session(&dir, opened.session, opened.writer).with_config(cfg);
        // The call entry fits, the 5 KiB result does not: a shell may have
        // mutated, but successful exit alone cannot prove it.
        let error = ts
            .invoke(
                "bash",
                &test_args!({"command": "printf made > actual.txt; printf 'x%.0s' $(seq 5000)"}),
            )
            .unwrap_err();
        assert_eq!(error.code(), "RECORD_FAILED");
        assert!(matches!(
            error,
            SmithError::RecordFailed {
                mutation_state: MutationState::Unknown,
                ..
            }
        ));
        assert_eq!(
            std::fs::read_to_string(dir.join("actual.txt")).unwrap(),
            "made"
        );
        let later = ts
            .invoke(
                "write",
                &test_args!({"path": "must-not-run.txt", "content": "x"}),
            )
            .unwrap_err();
        assert!(matches!(
            later,
            SmithError::RecordFailed {
                mutation_state: MutationState::Unknown,
                ..
            }
        ));
        assert!(!dir.join("must-not-run.txt").exists());
        // Only the durably recorded call is part of the live session.
        let kinds: Vec<EntryKind> = ts
            .session
            .active_branch()
            .entries()
            .iter()
            .map(|e| e.kind)
            .collect();
        assert!(matches!(kinds.as_slice(), [EntryKind::ToolCall { .. }]));
    }

    #[test]
    fn write_requires_string_content_and_leaves_existing_file_untouched() {
        let dir = workdir("write_schema");
        let target = dir.join("data.txt");
        std::fs::write(&target, "original").unwrap();
        let mut ts = ToolSession::new(&dir);
        let error = ts
            .invoke("write", &test_args!({"path": "data.txt"}))
            .unwrap_err();
        assert_eq!(error.code(), "VALIDATION");
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "original");
        let error = ts
            .invoke("write", &test_args!({"path": "data.txt", "content": 42}))
            .unwrap_err();
        assert_eq!(error.code(), "VALIDATION");
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "original");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn write_creates_missing_parents_and_leaves_no_temp_files() {
        let dir = workdir("write_parents");
        let mut ts = ToolSession::new(&dir);
        ts.invoke(
            "write",
            &test_args!({"path": "a/b/c.txt", "content": "deep"}),
        )
        .unwrap();
        assert_eq!(
            std::fs::read_to_string(dir.join("a/b/c.txt")).unwrap(),
            "deep"
        );
        let leftovers: Vec<_> = std::fs::read_dir(&dir)
            .unwrap()
            .filter_map(std::result::Result::ok)
            .flat_map(|e| {
                std::fs::read_dir(e.path())
                    .unwrap()
                    .filter_map(std::result::Result::ok)
                    .map(|x| x.file_name().to_string_lossy().into_owned())
                    .collect::<Vec<_>>()
            })
            .filter(|n| n.contains(".tmp-"))
            .collect();
        assert!(
            leftovers.is_empty(),
            "temp files left behind: {leftovers:?}"
        );
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn edit_rejects_ambiguous_and_missing_matches_without_changes() {
        let dir = workdir("edit_amb");
        let target = dir.join("f.txt");
        std::fs::write(&target, "a a").unwrap();
        let mut ts = ToolSession::new(&dir);
        let error = ts
            .invoke(
                "edit",
                &test_args!({"path": "f.txt", "old_string": "a", "new_string": "b"}),
            )
            .unwrap_err();
        assert_eq!(error.code(), "EDIT_AMBIGUOUS");
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "a a");
        let error = ts
            .invoke(
                "edit",
                &test_args!({"path": "f.txt", "old_string": "NOT_PRESENT", "new_string": "b"}),
            )
            .unwrap_err();
        assert_eq!(error.code(), "EDIT_NOT_FOUND");
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "a a");
        // Unambiguous edit succeeds.
        ts.invoke(
            "edit",
            &test_args!({"path": "f.txt", "old_string": "a a", "new_string": "b"}),
        )
        .unwrap();
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "b");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn read_supports_line_windows_byte_caps_and_binary_detection() {
        let dir = workdir("read_caps");
        let mut body = String::new();
        for i in 0..100 {
            use std::fmt::Write as _;
            let _ = writeln!(body, "line-{i}");
        }
        std::fs::write(dir.join("lines.txt"), &body).unwrap();
        let mut ts = ToolSession::new(&dir);
        let out = ts
            .invoke(
                "read",
                &test_args!({"path": "lines.txt", "offset": 2, "limit": 3}),
            )
            .unwrap();
        assert_eq!(out.output, "line-2\nline-3\nline-4\n");
        let capped = ts
            .invoke("read", &test_args!({"path": "lines.txt", "max_bytes": 20}))
            .unwrap();
        assert!(capped.output.len() <= 20);
        std::fs::write(dir.join("bin.dat"), [0x62, 0x00, 0x62]).unwrap();
        let error = ts
            .invoke("read", &test_args!({"path": "bin.dat"}))
            .unwrap_err();
        assert_eq!(error.code(), "BINARY_CONTENT");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn ls_and_find_are_sorted_and_surface_errors() {
        let dir = workdir("ls_find");
        for name in ["zeta", "alpha", "mid"] {
            std::fs::write(dir.join(name), "").unwrap();
        }
        let mut ts = ToolSession::new(&dir);
        let out = ts.invoke("ls", &test_args!({})).unwrap();
        assert_eq!(out.output, "alpha\nmid\nzeta");
        let found = ts.invoke("find", &test_args!({"pattern": "a"})).unwrap();
        assert_eq!(found.output, "alpha\nzeta");
        let error = ts
            .invoke("find", &test_args!({"path": "missing-dir", "pattern": "x"}))
            .unwrap_err();
        assert_eq!(error.code(), "FIND_ERROR");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn grep_returns_bounded_matches() {
        let dir = workdir("grep");
        std::fs::write(
            dir.join("log.txt"),
            "hit one\nmiss\nhit two\nmiss\nhit three\n",
        )
        .unwrap();
        let mut ts = ToolSession::new(&dir);
        let out = ts
            .invoke("grep", &test_args!({"path": "log.txt", "query": "hit"}))
            .unwrap();
        assert_eq!(out.output, "hit one\nhit two\nhit three");
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn unregistered_tools_and_non_object_input_are_rejected() {
        let dir = workdir("registry");
        let mut ts = ToolSession::new(&dir);
        let error = ts.invoke("rm", &test_args!({})).unwrap_err();
        assert_eq!(error.code(), "TOOL_NOT_REGISTERED");
        let error = ts.invoke("read", &test_args!("not-an-object")).unwrap_err();
        assert_eq!(error.code(), "INVALID_INPUT");
        let _ = std::fs::remove_dir_all(&dir);
    }

    fn assert_recorded_failure(ts: &ToolSession) {
        let entries = ts.session.active_branch().entries();
        assert!(matches!(
            entries.iter().rev().nth(1).map(|entry| entry.kind),
            Some(EntryKind::ToolResult { ok: false, .. })
        ));
        assert!(matches!(
            entries.last().map(|entry| entry.kind),
            Some(EntryKind::Meta { .. })
        ));
    }

    fn cancel_at(
        dir: &Path,
        checkpoint: EffectCheckpoint,
        name: &str,
        input: serde_json::Value,
    ) -> (SmithError, ToolSession) {
        let mut ts = ToolSession::new(dir);
        ts.cancel_at_checkpoint(checkpoint);
        let error = ts
            .invoke(name, &ToolArguments::from_serializable(&input).unwrap())
            .unwrap_err();
        (error, ts)
    }

    fn timeout_at(
        dir: &Path,
        checkpoint: EffectCheckpoint,
        name: &str,
        input: serde_json::Value,
    ) -> (SmithError, ToolSession) {
        let mut ts = ToolSession::new(dir);
        ts.timeout_at_checkpoint(checkpoint);
        let error = ts
            .invoke(name, &ToolArguments::from_serializable(&input).unwrap())
            .unwrap_err();
        (error, ts)
    }

    #[test]
    fn cancellation_stops_file_effects_at_cooperative_boundaries() {
        let dir = workdir("file_cancellation");
        std::fs::write(dir.join("source.txt"), "needle\nold\n").unwrap();
        std::fs::create_dir_all(dir.join("nested")).unwrap();
        std::fs::write(dir.join("nested/child.txt"), "needle\n").unwrap();

        for (checkpoint, name, input) in [
            (
                EffectCheckpoint::ReadChunk,
                "read",
                serde_json::json!({"path": "source.txt"}),
            ),
            (
                EffectCheckpoint::GrepLine,
                "grep",
                serde_json::json!({"path": "source.txt", "query": "needle"}),
            ),
            (
                EffectCheckpoint::EditReadChunk,
                "edit",
                serde_json::json!({"path": "source.txt", "old_string": "old", "new_string": "new"}),
            ),
            (
                EffectCheckpoint::TraversalEntry,
                "find",
                serde_json::json!({"pattern": "child"}),
            ),
            (
                EffectCheckpoint::TraversalEntry,
                "grep",
                serde_json::json!({"path": "", "query": "needle"}),
            ),
        ] {
            let (error, ts) = cancel_at(&dir, checkpoint, name, input);
            assert_eq!(error.code(), "CANCELLED");
            assert_recorded_failure(&ts);
        }
        assert_eq!(
            std::fs::read_to_string(dir.join("source.txt")).unwrap(),
            "needle\nold\n"
        );
    }

    #[test]
    fn configured_timeout_stops_file_effects_at_cooperative_boundaries() {
        let dir = workdir("file_timeout_boundaries");
        std::fs::write(dir.join("source.txt"), "needle\nold\n").unwrap();
        std::fs::create_dir_all(dir.join("nested")).unwrap();
        std::fs::write(dir.join("nested/child.txt"), "needle\n").unwrap();

        for (checkpoint, name, input) in [
            (
                EffectCheckpoint::ReadChunk,
                "read",
                serde_json::json!({"path": "source.txt"}),
            ),
            (
                EffectCheckpoint::GrepLine,
                "grep",
                serde_json::json!({"path": "source.txt", "query": "needle"}),
            ),
            (
                EffectCheckpoint::EditReadChunk,
                "edit",
                serde_json::json!({"path": "source.txt", "old_string": "old", "new_string": "new"}),
            ),
            (
                EffectCheckpoint::WriteChunk,
                "write",
                serde_json::json!({"path": "new.txt", "content": "new"}),
            ),
            (
                EffectCheckpoint::TraversalEntry,
                "ls",
                serde_json::json!({}),
            ),
        ] {
            let (error, ts) = timeout_at(&dir, checkpoint, name, input);
            assert_eq!(error.code(), "TOOL_TIMEOUT");
            assert_recorded_failure(&ts);
        }
        assert_eq!(
            std::fs::read_to_string(dir.join("source.txt")).unwrap(),
            "needle\nold\n"
        );
    }

    #[test]
    fn cancellation_after_parent_creation_records_applied_directory_mutation() {
        let dir = workdir("write_parent_cancellation");
        let (error, ts) = cancel_at(
            &dir,
            EffectCheckpoint::ParentCreated,
            "write",
            serde_json::json!({"path": "a/b/target.txt", "content": "new"}),
        );
        assert_eq!(error.code(), "CANCELLED_APPLIED");
        assert!(dir.join("a/b").is_dir());
        assert!(!dir.join("a/b/target.txt").exists());
        assert!(matches!(
            ts.session.content(ts.session.active_branch().entries().last().unwrap()).unwrap(),
            EntryContent::Meta { kind, detail }
                if kind == "tool-mutation"
                    && serde_json::to_value(&detail).unwrap()["mutation_state"] == "applied"
        ));
    }

    #[test]
    fn deadline_after_parent_creation_records_applied_directory_mutation() {
        let dir = workdir("write_parent_deadline");
        let (error, ts) = timeout_at(
            &dir,
            EffectCheckpoint::ParentCreated,
            "write",
            serde_json::json!({"path": "a/b/target.txt", "content": "new"}),
        );
        assert_eq!(error.code(), "TOOL_TIMEOUT_APPLIED");
        assert!(dir.join("a/b").is_dir());
        assert!(!dir.join("a/b/target.txt").exists());
        let entry = ts.session.active_branch().entries().last().unwrap();
        assert!(matches!(
            ts.session.content(entry).unwrap(),
            EntryContent::Meta { detail, .. } if serde_json::to_value(&detail).unwrap()["mutation_state"] == "applied"
        ));
    }

    #[test]
    fn cancellation_before_or_after_atomic_publication_reports_truthfully() {
        let dir = workdir("write_commit_cancellation");
        let target = dir.join("target.txt");
        std::fs::write(&target, "old").unwrap();

        let (error, ts) = cancel_at(
            &dir,
            EffectCheckpoint::BeforePublish,
            "write",
            serde_json::json!({"path": "target.txt", "content": "new"}),
        );
        assert_eq!(error.code(), "CANCELLED");
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "old");
        assert_recorded_failure(&ts);

        let (error, ts) = cancel_at(
            &dir,
            EffectCheckpoint::AfterPublish,
            "write",
            serde_json::json!({"path": "target.txt", "content": "new"}),
        );
        assert_eq!(error.code(), "CANCELLED_APPLIED");
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "new");
        assert_recorded_failure(&ts);
    }

    #[test]
    fn unrecordable_post_publication_cancellation_reports_applied_mutation() {
        let dir = workdir("record_applied_cancellation");
        let target = dir.join("target.txt");
        std::fs::write(&target, "old").unwrap();
        let mut writes = 0usize;
        let mut ts = ToolSession::with_persist(&dir, Session::new(), move |_, _| {
            writes += 1;
            if writes == 1 {
                Ok(())
            } else {
                Err(tool_error(
                    smith::error::ToolCode::TestRecord,
                    "result persistence rejected",
                ))
            }
        });
        ts.cancel_at_checkpoint(EffectCheckpoint::AfterPublish);

        let error = ts
            .invoke(
                "write",
                &test_args!({"path": "target.txt", "content": "new"}),
            )
            .unwrap_err();
        assert!(matches!(
            error,
            SmithError::RecordFailed {
                mutation_state: MutationState::Applied,
                ..
            }
        ));
        assert_eq!(std::fs::read_to_string(&target).unwrap(), "new");
    }

    #[test]
    fn configured_deadline_stops_every_file_effect_before_it_starts() {
        let dir = workdir("file_deadline");
        std::fs::write(dir.join("source.txt"), "needle\nold\n").unwrap();
        std::fs::create_dir_all(dir.join("nested")).unwrap();
        std::fs::write(dir.join("nested/child.txt"), "needle\n").unwrap();
        let mut config = Config::default_valid();
        // Inject an already elapsed effect budget; no wall-clock wait.
        config.tool_timeout_ms = 0;
        let mut ts = ToolSession::new(&dir).with_config(config);

        for (name, input) in [
            ("read", serde_json::json!({"path": "source.txt"})),
            (
                "grep",
                serde_json::json!({"path": "source.txt", "query": "needle"}),
            ),
            ("grep", serde_json::json!({"path": "", "query": "needle"})),
            ("ls", serde_json::json!({})),
            ("find", serde_json::json!({"pattern": "child"})),
            (
                "write",
                serde_json::json!({"path": "source.txt", "content": "new"}),
            ),
            (
                "edit",
                serde_json::json!({"path": "source.txt", "old_string": "old", "new_string": "new"}),
            ),
        ] {
            let error = ts
                .invoke(name, &ToolArguments::from_serializable(&input).unwrap())
                .unwrap_err();
            assert_eq!(error.code(), "TOOL_TIMEOUT");
        }
        assert_eq!(
            std::fs::read_to_string(dir.join("source.txt")).unwrap(),
            "needle\nold\n"
        );
        assert_eq!(
            ts.session
                .active_branch()
                .entries()
                .iter()
                .filter(|entry| matches!(entry.kind, EntryKind::ToolResult { ok: false, .. }))
                .count(),
            7
        );
    }

    #[test]
    fn plugin_http_intent_uses_the_active_tool_session_writer() {
        let dir = workdir("plugin_http_record");
        let mut tools = ToolSession::new(&dir);
        let mut effects = ToolEffectContext::for_operation(&mut tools, "fixture");
        effects
            .record_plugin_http(&smith::http::PluginHttpEffectRecord::Intent {
                plugin_id: "example:fixture".to_string(),
                call_id: ToolCallId::from_u128(7),
                origin: "https://api.example.test".to_string(),
                method: smith::http::HttpMethod::Post,
                headers: vec![smith::http::HttpHeader {
                    name: "Authorization".to_string(),
                    value: "<redacted>".to_string(),
                }]
                .into(),
                request_bytes: 0,
                timeout_ms: 1,
                response_bytes_max: 1,
            })
            .unwrap();
        let entry = &tools.session.active_branch().entries()[0];
        match tools.session.content(entry).unwrap() {
            EntryContent::Meta { kind, .. } => assert_eq!(kind, PLUGIN_HTTP_KIND),
            other => panic!("unexpected {other:?}"),
        }
        let _ = std::fs::remove_dir_all(&dir);
    }

    #[test]
    fn failed_effects_are_recorded_as_failures() {
        let dir = workdir("record_fail");
        let mut ts = ToolSession::new(&dir);
        let res = ts.invoke("read", &test_args!({"path": "nope.txt"}));
        assert!(res.is_err());
        // Call, failed result, and typed mutation completion are recorded.
        assert_eq!(ts.session.active_branch().entries().len(), 3);
        let last = &ts.session.active_branch().entries()[1];
        match ts.session.content(last).unwrap() {
            EntryContent::ToolResult { ok, output, .. } => {
                assert!(!ok);
                assert!(output.contains("READ_ERROR"));
            }
            other => panic!("unexpected {other:?}"),
        }
        let _ = std::fs::remove_dir_all(&dir);
    }
}