feat: Complete LLMX v0.1.0 - Rebrand from Codex with LiteLLM Integration

This release represents a comprehensive transformation of the codebase from Codex to LLMX,
enhanced with LiteLLM integration to support 100+ LLM providers through a unified API.

## Major Changes

### Phase 1: Repository & Infrastructure Setup
- Established new repository structure and branching strategy
- Created comprehensive project documentation (CLAUDE.md, LITELLM-SETUP.md)
- Set up development environment and tooling configuration

### Phase 2: Rust Workspace Transformation
- Renamed all Rust crates from `codex-*` to `llmx-*` (30+ crates)
- Updated package names, binary names, and workspace members
- Renamed core modules: codex.rs → llmx.rs, codex_delegate.rs → llmx_delegate.rs
- Updated all internal references, imports, and type names
- Renamed directories: codex-rs/ → llmx-rs/, codex-backend-openapi-models/ → llmx-backend-openapi-models/
- Fixed all Rust compilation errors after mass rename

### Phase 3: LiteLLM Integration
- Integrated LiteLLM for multi-provider LLM support (Anthropic, OpenAI, Azure, Google AI, AWS Bedrock, etc.)
- Implemented OpenAI-compatible Chat Completions API support
- Added model family detection and provider-specific handling
- Updated authentication to support LiteLLM API keys
- Renamed environment variables: OPENAI_BASE_URL → LLMX_BASE_URL
- Added LLMX_API_KEY for unified authentication
- Enhanced error handling for Chat Completions API responses
- Implemented fallback mechanisms between Responses API and Chat Completions API

### Phase 4: TypeScript/Node.js Components
- Renamed npm package: @codex/codex-cli → @valknar/llmx
- Updated TypeScript SDK to use new LLMX APIs and endpoints
- Fixed all TypeScript compilation and linting errors
- Updated SDK tests to support both API backends
- Enhanced mock server to handle multiple API formats
- Updated build scripts for cross-platform packaging

### Phase 5: Configuration & Documentation
- Updated all configuration files to use LLMX naming
- Rewrote README and documentation for LLMX branding
- Updated config paths: ~/.codex/ → ~/.llmx/
- Added comprehensive LiteLLM setup guide
- Updated all user-facing strings and help text
- Created release plan and migration documentation

### Phase 6: Testing & Validation
- Fixed all Rust tests for new naming scheme
- Updated snapshot tests in TUI (36 frame files)
- Fixed authentication storage tests
- Updated Chat Completions payload and SSE tests
- Fixed SDK tests for new API endpoints
- Ensured compatibility with Claude Sonnet 4.5 model
- Fixed test environment variables (LLMX_API_KEY, LLMX_BASE_URL)

### Phase 7: Build & Release Pipeline
- Updated GitHub Actions workflows for LLMX binary names
- Fixed rust-release.yml to reference llmx-rs/ instead of codex-rs/
- Updated CI/CD pipelines for new package names
- Made Apple code signing optional in release workflow
- Enhanced npm packaging resilience for partial platform builds
- Added Windows sandbox support to workspace
- Updated dotslash configuration for new binary names

### Phase 8: Final Polish
- Renamed all assets (.github images, labels, templates)
- Updated VSCode and DevContainer configurations
- Fixed all clippy warnings and formatting issues
- Applied cargo fmt and prettier formatting across codebase
- Updated issue templates and pull request templates
- Fixed all remaining UI text references

## Technical Details

**Breaking Changes:**
- Binary name changed from `codex` to `llmx`
- Config directory changed from `~/.codex/` to `~/.llmx/`
- Environment variables renamed (CODEX_* → LLMX_*)
- npm package renamed to `@valknar/llmx`

**New Features:**
- Support for 100+ LLM providers via LiteLLM
- Unified authentication with LLMX_API_KEY
- Enhanced model provider detection and handling
- Improved error handling and fallback mechanisms

**Files Changed:**
- 578 files modified across Rust, TypeScript, and documentation
- 30+ Rust crates renamed and updated
- Complete rebrand of UI, CLI, and documentation
- All tests updated and passing

**Dependencies:**
- Updated Cargo.lock with new package names
- Updated npm dependencies in llmx-cli
- Enhanced OpenAPI models for LLMX backend

This release establishes LLMX as a standalone project with comprehensive LiteLLM
integration, maintaining full backward compatibility with existing functionality
while opening support for a wide ecosystem of LLM providers.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude <noreply@anthropic.com>
Co-Authored-By: Sebastian Krüger <support@pivoine.art>

llmx-rs/core/src/tools/context.rs

@@ -0,0 +1,268 @@
+use crate::llmx::Session;
+use crate::llmx::TurnContext;
+use crate::tools::TELEMETRY_PREVIEW_MAX_BYTES;
+use crate::tools::TELEMETRY_PREVIEW_MAX_LINES;
+use crate::tools::TELEMETRY_PREVIEW_TRUNCATION_NOTICE;
+use crate::turn_diff_tracker::TurnDiffTracker;
+use llmx_otel::otel_event_manager::OtelEventManager;
+use llmx_protocol::models::FunctionCallOutputContentItem;
+use llmx_protocol::models::FunctionCallOutputPayload;
+use llmx_protocol::models::ResponseInputItem;
+use llmx_protocol::models::ShellToolCallParams;
+use llmx_protocol::protocol::FileChange;
+use llmx_utils_string::take_bytes_at_char_boundary;
+use mcp_types::CallToolResult;
+use std::borrow::Cow;
+use std::collections::HashMap;
+use std::path::PathBuf;
+use std::sync::Arc;
+use tokio::sync::Mutex;
+
+pub type SharedTurnDiffTracker = Arc<Mutex<TurnDiffTracker>>;
+
+#[derive(Clone)]
+pub struct ToolInvocation {
+    pub session: Arc<Session>,
+    pub turn: Arc<TurnContext>,
+    pub tracker: SharedTurnDiffTracker,
+    pub call_id: String,
+    pub tool_name: String,
+    pub payload: ToolPayload,
+}
+
+#[derive(Clone)]
+pub enum ToolPayload {
+    Function {
+        arguments: String,
+    },
+    Custom {
+        input: String,
+    },
+    LocalShell {
+        params: ShellToolCallParams,
+    },
+    UnifiedExec {
+        arguments: String,
+    },
+    Mcp {
+        server: String,
+        tool: String,
+        raw_arguments: String,
+    },
+}
+
+impl ToolPayload {
+    pub fn log_payload(&self) -> Cow<'_, str> {
+        match self {
+            ToolPayload::Function { arguments } => Cow::Borrowed(arguments),
+            ToolPayload::Custom { input } => Cow::Borrowed(input),
+            ToolPayload::LocalShell { params } => Cow::Owned(params.command.join(" ")),
+            ToolPayload::UnifiedExec { arguments } => Cow::Borrowed(arguments),
+            ToolPayload::Mcp { raw_arguments, .. } => Cow::Borrowed(raw_arguments),
+        }
+    }
+}
+
+#[derive(Clone)]
+pub enum ToolOutput {
+    Function {
+        // Plain text representation of the tool output.
+        content: String,
+        // Some tool calls such as MCP calls may return structured content that can get parsed into an array of polymorphic content items.
+        content_items: Option<Vec<FunctionCallOutputContentItem>>,
+        success: Option<bool>,
+    },
+    Mcp {
+        result: Result<CallToolResult, String>,
+    },
+}
+
+impl ToolOutput {
+    pub fn log_preview(&self) -> String {
+        match self {
+            ToolOutput::Function { content, .. } => telemetry_preview(content),
+            ToolOutput::Mcp { result } => format!("{result:?}"),
+        }
+    }
+
+    pub fn success_for_logging(&self) -> bool {
+        match self {
+            ToolOutput::Function { success, .. } => success.unwrap_or(true),
+            ToolOutput::Mcp { result } => result.is_ok(),
+        }
+    }
+
+    pub fn into_response(self, call_id: &str, payload: &ToolPayload) -> ResponseInputItem {
+        match self {
+            ToolOutput::Function {
+                content,
+                content_items,
+                success,
+            } => {
+                if matches!(payload, ToolPayload::Custom { .. }) {
+                    ResponseInputItem::CustomToolCallOutput {
+                        call_id: call_id.to_string(),
+                        output: content,
+                    }
+                } else {
+                    ResponseInputItem::FunctionCallOutput {
+                        call_id: call_id.to_string(),
+                        output: FunctionCallOutputPayload {
+                            content,
+                            content_items,
+                            success,
+                        },
+                    }
+                }
+            }
+            ToolOutput::Mcp { result } => ResponseInputItem::McpToolCallOutput {
+                call_id: call_id.to_string(),
+                result,
+            },
+        }
+    }
+}
+
+fn telemetry_preview(content: &str) -> String {
+    let truncated_slice = take_bytes_at_char_boundary(content, TELEMETRY_PREVIEW_MAX_BYTES);
+    let truncated_by_bytes = truncated_slice.len() < content.len();
+
+    let mut preview = String::new();
+    let mut lines_iter = truncated_slice.lines();
+    for idx in 0..TELEMETRY_PREVIEW_MAX_LINES {
+        match lines_iter.next() {
+            Some(line) => {
+                if idx > 0 {
+                    preview.push('\n');
+                }
+                preview.push_str(line);
+            }
+            None => break,
+        }
+    }
+    let truncated_by_lines = lines_iter.next().is_some();
+
+    if !truncated_by_bytes && !truncated_by_lines {
+        return content.to_string();
+    }
+
+    if preview.len() < truncated_slice.len()
+        && truncated_slice
+            .as_bytes()
+            .get(preview.len())
+            .is_some_and(|byte| *byte == b'\n')
+    {
+        preview.push('\n');
+    }
+
+    if !preview.is_empty() && !preview.ends_with('\n') {
+        preview.push('\n');
+    }
+    preview.push_str(TELEMETRY_PREVIEW_TRUNCATION_NOTICE);
+
+    preview
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use pretty_assertions::assert_eq;
+
+    #[test]
+    fn custom_tool_calls_should_roundtrip_as_custom_outputs() {
+        let payload = ToolPayload::Custom {
+            input: "patch".to_string(),
+        };
+        let response = ToolOutput::Function {
+            content: "patched".to_string(),
+            content_items: None,
+            success: Some(true),
+        }
+        .into_response("call-42", &payload);
+
+        match response {
+            ResponseInputItem::CustomToolCallOutput { call_id, output } => {
+                assert_eq!(call_id, "call-42");
+                assert_eq!(output, "patched");
+            }
+            other => panic!("expected CustomToolCallOutput, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn function_payloads_remain_function_outputs() {
+        let payload = ToolPayload::Function {
+            arguments: "{}".to_string(),
+        };
+        let response = ToolOutput::Function {
+            content: "ok".to_string(),
+            content_items: None,
+            success: Some(true),
+        }
+        .into_response("fn-1", &payload);
+
+        match response {
+            ResponseInputItem::FunctionCallOutput { call_id, output } => {
+                assert_eq!(call_id, "fn-1");
+                assert_eq!(output.content, "ok");
+                assert!(output.content_items.is_none());
+                assert_eq!(output.success, Some(true));
+            }
+            other => panic!("expected FunctionCallOutput, got {other:?}"),
+        }
+    }
+
+    #[test]
+    fn telemetry_preview_returns_original_within_limits() {
+        let content = "short output";
+        assert_eq!(telemetry_preview(content), content);
+    }
+
+    #[test]
+    fn telemetry_preview_truncates_by_bytes() {
+        let content = "x".repeat(TELEMETRY_PREVIEW_MAX_BYTES + 8);
+        let preview = telemetry_preview(&content);
+
+        assert!(preview.contains(TELEMETRY_PREVIEW_TRUNCATION_NOTICE));
+        assert!(
+            preview.len()
+                <= TELEMETRY_PREVIEW_MAX_BYTES + TELEMETRY_PREVIEW_TRUNCATION_NOTICE.len() + 1
+        );
+    }
+
+    #[test]
+    fn telemetry_preview_truncates_by_lines() {
+        let content = (0..(TELEMETRY_PREVIEW_MAX_LINES + 5))
+            .map(|idx| format!("line {idx}"))
+            .collect::<Vec<_>>()
+            .join("\n");
+
+        let preview = telemetry_preview(&content);
+        let lines: Vec<&str> = preview.lines().collect();
+
+        assert!(lines.len() <= TELEMETRY_PREVIEW_MAX_LINES + 1);
+        assert_eq!(lines.last(), Some(&TELEMETRY_PREVIEW_TRUNCATION_NOTICE));
+    }
+}
+
+#[derive(Clone, Debug)]
+#[allow(dead_code)]
+pub(crate) struct ExecCommandContext {
+    pub(crate) turn: Arc<TurnContext>,
+    pub(crate) call_id: String,
+    pub(crate) command_for_display: Vec<String>,
+    pub(crate) cwd: PathBuf,
+    pub(crate) apply_patch: Option<ApplyPatchCommandContext>,
+    pub(crate) tool_name: String,
+    pub(crate) otel_event_manager: OtelEventManager,
+    // TODO(abhisek-oai): Find a better way to track this.
+    // https://github.com/valknar/llmx/pull/2471/files#r2470352242
+    pub(crate) is_user_shell_command: bool,
+}
+
+#[derive(Clone, Debug)]
+#[allow(dead_code)]
+pub(crate) struct ApplyPatchCommandContext {
+    pub(crate) user_explicitly_approved_this_action: bool,
+    pub(crate) changes: HashMap<PathBuf, FileChange>,
+}

llmx-rs/core/src/tools/events.rs

@@ -0,0 +1,369 @@
+use crate::error::LlmxErr;
+use crate::error::SandboxErr;
+use crate::exec::ExecToolCallOutput;
+use crate::function_tool::FunctionCallError;
+use crate::llmx::Session;
+use crate::llmx::TurnContext;
+use crate::parse_command::parse_command;
+use crate::protocol::EventMsg;
+use crate::protocol::ExecCommandBeginEvent;
+use crate::protocol::ExecCommandEndEvent;
+use crate::protocol::FileChange;
+use crate::protocol::PatchApplyBeginEvent;
+use crate::protocol::PatchApplyEndEvent;
+use crate::protocol::TurnDiffEvent;
+use crate::tools::context::SharedTurnDiffTracker;
+use crate::tools::sandboxing::ToolError;
+use std::collections::HashMap;
+use std::path::Path;
+use std::path::PathBuf;
+use std::time::Duration;
+
+use super::format_exec_output_str;
+
+#[derive(Clone, Copy)]
+pub(crate) struct ToolEventCtx<'a> {
+    pub session: &'a Session,
+    pub turn: &'a TurnContext,
+    pub call_id: &'a str,
+    pub turn_diff_tracker: Option<&'a SharedTurnDiffTracker>,
+}
+
+impl<'a> ToolEventCtx<'a> {
+    pub fn new(
+        session: &'a Session,
+        turn: &'a TurnContext,
+        call_id: &'a str,
+        turn_diff_tracker: Option<&'a SharedTurnDiffTracker>,
+    ) -> Self {
+        Self {
+            session,
+            turn,
+            call_id,
+            turn_diff_tracker,
+        }
+    }
+}
+
+pub(crate) enum ToolEventStage {
+    Begin,
+    Success(ExecToolCallOutput),
+    Failure(ToolEventFailure),
+}
+
+pub(crate) enum ToolEventFailure {
+    Output(ExecToolCallOutput),
+    Message(String),
+}
+
+pub(crate) async fn emit_exec_command_begin(
+    ctx: ToolEventCtx<'_>,
+    command: &[String],
+    cwd: &Path,
+    is_user_shell_command: bool,
+) {
+    ctx.session
+        .send_event(
+            ctx.turn,
+            EventMsg::ExecCommandBegin(ExecCommandBeginEvent {
+                call_id: ctx.call_id.to_string(),
+                command: command.to_vec(),
+                cwd: cwd.to_path_buf(),
+                parsed_cmd: parse_command(command),
+                is_user_shell_command,
+            }),
+        )
+        .await;
+}
+// Concrete, allocation-free emitter: avoid trait objects and boxed futures.
+pub(crate) enum ToolEmitter {
+    Shell {
+        command: Vec<String>,
+        cwd: PathBuf,
+        is_user_shell_command: bool,
+    },
+    ApplyPatch {
+        changes: HashMap<PathBuf, FileChange>,
+        auto_approved: bool,
+    },
+    UnifiedExec {
+        command: String,
+        cwd: PathBuf,
+        // True for `exec_command` and false for `write_stdin`.
+        #[allow(dead_code)]
+        is_startup_command: bool,
+    },
+}
+
+impl ToolEmitter {
+    pub fn shell(command: Vec<String>, cwd: PathBuf, is_user_shell_command: bool) -> Self {
+        Self::Shell {
+            command,
+            cwd,
+            is_user_shell_command,
+        }
+    }
+
+    pub fn apply_patch(changes: HashMap<PathBuf, FileChange>, auto_approved: bool) -> Self {
+        Self::ApplyPatch {
+            changes,
+            auto_approved,
+        }
+    }
+
+    pub fn unified_exec(command: String, cwd: PathBuf, is_startup_command: bool) -> Self {
+        Self::UnifiedExec {
+            command,
+            cwd,
+            is_startup_command,
+        }
+    }
+
+    pub async fn emit(&self, ctx: ToolEventCtx<'_>, stage: ToolEventStage) {
+        match (self, stage) {
+            (
+                Self::Shell {
+                    command,
+                    cwd,
+                    is_user_shell_command,
+                },
+                ToolEventStage::Begin,
+            ) => {
+                emit_exec_command_begin(ctx, command, cwd.as_path(), *is_user_shell_command).await;
+            }
+            (Self::Shell { .. }, ToolEventStage::Success(output)) => {
+                emit_exec_end(
+                    ctx,
+                    output.stdout.text.clone(),
+                    output.stderr.text.clone(),
+                    output.aggregated_output.text.clone(),
+                    output.exit_code,
+                    output.duration,
+                    format_exec_output_str(&output),
+                )
+                .await;
+            }
+            (Self::Shell { .. }, ToolEventStage::Failure(ToolEventFailure::Output(output))) => {
+                emit_exec_end(
+                    ctx,
+                    output.stdout.text.clone(),
+                    output.stderr.text.clone(),
+                    output.aggregated_output.text.clone(),
+                    output.exit_code,
+                    output.duration,
+                    format_exec_output_str(&output),
+                )
+                .await;
+            }
+            (Self::Shell { .. }, ToolEventStage::Failure(ToolEventFailure::Message(message))) => {
+                emit_exec_end(
+                    ctx,
+                    String::new(),
+                    (*message).to_string(),
+                    (*message).to_string(),
+                    -1,
+                    Duration::ZERO,
+                    message.clone(),
+                )
+                .await;
+            }
+
+            (
+                Self::ApplyPatch {
+                    changes,
+                    auto_approved,
+                },
+                ToolEventStage::Begin,
+            ) => {
+                if let Some(tracker) = ctx.turn_diff_tracker {
+                    let mut guard = tracker.lock().await;
+                    guard.on_patch_begin(changes);
+                }
+                ctx.session
+                    .send_event(
+                        ctx.turn,
+                        EventMsg::PatchApplyBegin(PatchApplyBeginEvent {
+                            call_id: ctx.call_id.to_string(),
+                            auto_approved: *auto_approved,
+                            changes: changes.clone(),
+                        }),
+                    )
+                    .await;
+            }
+            (Self::ApplyPatch { .. }, ToolEventStage::Success(output)) => {
+                emit_patch_end(
+                    ctx,
+                    output.stdout.text.clone(),
+                    output.stderr.text.clone(),
+                    output.exit_code == 0,
+                )
+                .await;
+            }
+            (
+                Self::ApplyPatch { .. },
+                ToolEventStage::Failure(ToolEventFailure::Output(output)),
+            ) => {
+                emit_patch_end(
+                    ctx,
+                    output.stdout.text.clone(),
+                    output.stderr.text.clone(),
+                    output.exit_code == 0,
+                )
+                .await;
+            }
+            (
+                Self::ApplyPatch { .. },
+                ToolEventStage::Failure(ToolEventFailure::Message(message)),
+            ) => {
+                emit_patch_end(ctx, String::new(), (*message).to_string(), false).await;
+            }
+            (Self::UnifiedExec { command, cwd, .. }, ToolEventStage::Begin) => {
+                emit_exec_command_begin(ctx, &[command.to_string()], cwd.as_path(), false).await;
+            }
+            (Self::UnifiedExec { .. }, ToolEventStage::Success(output)) => {
+                emit_exec_end(
+                    ctx,
+                    output.stdout.text.clone(),
+                    output.stderr.text.clone(),
+                    output.aggregated_output.text.clone(),
+                    output.exit_code,
+                    output.duration,
+                    format_exec_output_str(&output),
+                )
+                .await;
+            }
+            (
+                Self::UnifiedExec { .. },
+                ToolEventStage::Failure(ToolEventFailure::Output(output)),
+            ) => {
+                emit_exec_end(
+                    ctx,
+                    output.stdout.text.clone(),
+                    output.stderr.text.clone(),
+                    output.aggregated_output.text.clone(),
+                    output.exit_code,
+                    output.duration,
+                    format_exec_output_str(&output),
+                )
+                .await;
+            }
+            (
+                Self::UnifiedExec { .. },
+                ToolEventStage::Failure(ToolEventFailure::Message(message)),
+            ) => {
+                emit_exec_end(
+                    ctx,
+                    String::new(),
+                    (*message).to_string(),
+                    (*message).to_string(),
+                    -1,
+                    Duration::ZERO,
+                    message.clone(),
+                )
+                .await;
+            }
+        }
+    }
+
+    pub async fn begin(&self, ctx: ToolEventCtx<'_>) {
+        self.emit(ctx, ToolEventStage::Begin).await;
+    }
+
+    pub async fn finish(
+        &self,
+        ctx: ToolEventCtx<'_>,
+        out: Result<ExecToolCallOutput, ToolError>,
+    ) -> Result<String, FunctionCallError> {
+        let (event, result) = match out {
+            Ok(output) => {
+                let content = super::format_exec_output_for_model(&output);
+                let exit_code = output.exit_code;
+                let event = ToolEventStage::Success(output);
+                let result = if exit_code == 0 {
+                    Ok(content)
+                } else {
+                    Err(FunctionCallError::RespondToModel(content))
+                };
+                (event, result)
+            }
+            Err(ToolError::Llmx(LlmxErr::Sandbox(SandboxErr::Timeout { output })))
+            | Err(ToolError::Llmx(LlmxErr::Sandbox(SandboxErr::Denied { output }))) => {
+                let response = super::format_exec_output_for_model(&output);
+                let event = ToolEventStage::Failure(ToolEventFailure::Output(*output));
+                let result = Err(FunctionCallError::RespondToModel(response));
+                (event, result)
+            }
+            Err(ToolError::Llmx(err)) => {
+                let message = format!("execution error: {err:?}");
+                let event = ToolEventStage::Failure(ToolEventFailure::Message(message.clone()));
+                let result = Err(FunctionCallError::RespondToModel(message));
+                (event, result)
+            }
+            Err(ToolError::Rejected(msg)) => {
+                // Normalize common rejection messages for exec tools so tests and
+                // users see a clear, consistent phrase.
+                let normalized = if msg == "rejected by user" {
+                    "exec command rejected by user".to_string()
+                } else {
+                    msg
+                };
+                let event = ToolEventStage::Failure(ToolEventFailure::Message(normalized.clone()));
+                let result = Err(FunctionCallError::RespondToModel(normalized));
+                (event, result)
+            }
+        };
+        self.emit(ctx, event).await;
+        result
+    }
+}
+
+async fn emit_exec_end(
+    ctx: ToolEventCtx<'_>,
+    stdout: String,
+    stderr: String,
+    aggregated_output: String,
+    exit_code: i32,
+    duration: Duration,
+    formatted_output: String,
+) {
+    ctx.session
+        .send_event(
+            ctx.turn,
+            EventMsg::ExecCommandEnd(ExecCommandEndEvent {
+                call_id: ctx.call_id.to_string(),
+                stdout,
+                stderr,
+                aggregated_output,
+                exit_code,
+                duration,
+                formatted_output,
+            }),
+        )
+        .await;
+}
+
+async fn emit_patch_end(ctx: ToolEventCtx<'_>, stdout: String, stderr: String, success: bool) {
+    ctx.session
+        .send_event(
+            ctx.turn,
+            EventMsg::PatchApplyEnd(PatchApplyEndEvent {
+                call_id: ctx.call_id.to_string(),
+                stdout,
+                stderr,
+                success,
+            }),
+        )
+        .await;
+
+    if let Some(tracker) = ctx.turn_diff_tracker {
+        let unified_diff = {
+            let mut guard = tracker.lock().await;
+            guard.get_unified_diff()
+        };
+        if let Ok(Some(unified_diff)) = unified_diff {
+            ctx.session
+                .send_event(ctx.turn, EventMsg::TurnDiff(TurnDiffEvent { unified_diff }))
+                .await;
+        }
+    }
+}

llmx-rs/core/src/tools/handlers/apply_patch.rs

@@ -0,0 +1,265 @@
+use std::collections::BTreeMap;
+
+use crate::apply_patch;
+use crate::apply_patch::InternalApplyPatchInvocation;
+use crate::apply_patch::convert_apply_patch_to_protocol;
+use crate::client_common::tools::FreeformTool;
+use crate::client_common::tools::FreeformToolFormat;
+use crate::client_common::tools::ResponsesApiTool;
+use crate::client_common::tools::ToolSpec;
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::events::ToolEmitter;
+use crate::tools::events::ToolEventCtx;
+use crate::tools::orchestrator::ToolOrchestrator;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+use crate::tools::runtimes::apply_patch::ApplyPatchRequest;
+use crate::tools::runtimes::apply_patch::ApplyPatchRuntime;
+use crate::tools::sandboxing::ToolCtx;
+use crate::tools::spec::ApplyPatchToolArgs;
+use crate::tools::spec::JsonSchema;
+use async_trait::async_trait;
+use serde::Deserialize;
+use serde::Serialize;
+
+pub struct ApplyPatchHandler;
+
+const APPLY_PATCH_LARK_GRAMMAR: &str = include_str!("tool_apply_patch.lark");
+
+#[async_trait]
+impl ToolHandler for ApplyPatchHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    fn matches_kind(&self, payload: &ToolPayload) -> bool {
+        matches!(
+            payload,
+            ToolPayload::Function { .. } | ToolPayload::Custom { .. }
+        )
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation {
+            session,
+            turn,
+            tracker,
+            call_id,
+            tool_name,
+            payload,
+        } = invocation;
+
+        let patch_input = match payload {
+            ToolPayload::Function { arguments } => {
+                let args: ApplyPatchToolArgs = serde_json::from_str(&arguments).map_err(|e| {
+                    FunctionCallError::RespondToModel(format!(
+                        "failed to parse function arguments: {e:?}"
+                    ))
+                })?;
+                args.input
+            }
+            ToolPayload::Custom { input } => input,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "apply_patch handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        // Re-parse and verify the patch so we can compute changes and approval.
+        // Avoid building temporary ExecParams/command vectors; derive directly from inputs.
+        let cwd = turn.cwd.clone();
+        let command = vec!["apply_patch".to_string(), patch_input.clone()];
+        match llmx_apply_patch::maybe_parse_apply_patch_verified(&command, &cwd) {
+            llmx_apply_patch::MaybeApplyPatchVerified::Body(changes) => {
+                match apply_patch::apply_patch(session.as_ref(), turn.as_ref(), &call_id, changes)
+                    .await
+                {
+                    InternalApplyPatchInvocation::Output(item) => {
+                        let content = item?;
+                        Ok(ToolOutput::Function {
+                            content,
+                            content_items: None,
+                            success: Some(true),
+                        })
+                    }
+                    InternalApplyPatchInvocation::DelegateToExec(apply) => {
+                        let emitter = ToolEmitter::apply_patch(
+                            convert_apply_patch_to_protocol(&apply.action),
+                            !apply.user_explicitly_approved_this_action,
+                        );
+                        let event_ctx = ToolEventCtx::new(
+                            session.as_ref(),
+                            turn.as_ref(),
+                            &call_id,
+                            Some(&tracker),
+                        );
+                        emitter.begin(event_ctx).await;
+
+                        let req = ApplyPatchRequest {
+                            patch: apply.action.patch.clone(),
+                            cwd: apply.action.cwd.clone(),
+                            timeout_ms: None,
+                            user_explicitly_approved: apply.user_explicitly_approved_this_action,
+                            llmx_exe: turn.llmx_linux_sandbox_exe.clone(),
+                        };
+
+                        let mut orchestrator = ToolOrchestrator::new();
+                        let mut runtime = ApplyPatchRuntime::new();
+                        let tool_ctx = ToolCtx {
+                            session: session.as_ref(),
+                            turn: turn.as_ref(),
+                            call_id: call_id.clone(),
+                            tool_name: tool_name.to_string(),
+                        };
+                        let out = orchestrator
+                            .run(&mut runtime, &req, &tool_ctx, &turn, turn.approval_policy)
+                            .await;
+                        let event_ctx = ToolEventCtx::new(
+                            session.as_ref(),
+                            turn.as_ref(),
+                            &call_id,
+                            Some(&tracker),
+                        );
+                        let content = emitter.finish(event_ctx, out).await?;
+                        Ok(ToolOutput::Function {
+                            content,
+                            content_items: None,
+                            success: Some(true),
+                        })
+                    }
+                }
+            }
+            llmx_apply_patch::MaybeApplyPatchVerified::CorrectnessError(parse_error) => {
+                Err(FunctionCallError::RespondToModel(format!(
+                    "apply_patch verification failed: {parse_error}"
+                )))
+            }
+            llmx_apply_patch::MaybeApplyPatchVerified::ShellParseError(error) => {
+                tracing::trace!("Failed to parse apply_patch input, {error:?}");
+                Err(FunctionCallError::RespondToModel(
+                    "apply_patch handler received invalid patch input".to_string(),
+                ))
+            }
+            llmx_apply_patch::MaybeApplyPatchVerified::NotApplyPatch => {
+                Err(FunctionCallError::RespondToModel(
+                    "apply_patch handler received non-apply_patch input".to_string(),
+                ))
+            }
+        }
+    }
+}
+
+#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Hash)]
+#[serde(rename_all = "snake_case")]
+pub enum ApplyPatchToolType {
+    Freeform,
+    Function,
+}
+
+/// Returns a custom tool that can be used to edit files. Well-suited for GPT-5 models
+/// https://platform.openai.com/docs/guides/function-calling#custom-tools
+pub(crate) fn create_apply_patch_freeform_tool() -> ToolSpec {
+    ToolSpec::Freeform(FreeformTool {
+        name: "apply_patch".to_string(),
+        description: "Use the `apply_patch` tool to edit files. This is a FREEFORM tool, so do not wrap the patch in JSON.".to_string(),
+        format: FreeformToolFormat {
+            r#type: "grammar".to_string(),
+            syntax: "lark".to_string(),
+            definition: APPLY_PATCH_LARK_GRAMMAR.to_string(),
+        },
+    })
+}
+
+/// Returns a json tool that can be used to edit files. Should only be used with gpt-oss models
+pub(crate) fn create_apply_patch_json_tool() -> ToolSpec {
+    let mut properties = BTreeMap::new();
+    properties.insert(
+        "input".to_string(),
+        JsonSchema::String {
+            description: Some(r#"The entire contents of the apply_patch command"#.to_string()),
+        },
+    );
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "apply_patch".to_string(),
+        description: r#"Use the `apply_patch` tool to edit files.
+Your patch language is a stripped‑down, file‑oriented diff format designed to be easy to parse and safe to apply. You can think of it as a high‑level envelope:
+
+*** Begin Patch
+[ one or more file sections ]
+*** End Patch
+
+Within that envelope, you get a sequence of file operations.
+You MUST include a header to specify the action you are taking.
+Each operation starts with one of three headers:
+
+*** Add File: <path> - create a new file. Every following line is a + line (the initial contents).
+*** Delete File: <path> - remove an existing file. Nothing follows.
+*** Update File: <path> - patch an existing file in place (optionally with a rename).
+
+May be immediately followed by *** Move to: <new path> if you want to rename the file.
+Then one or more “hunks”, each introduced by @@ (optionally followed by a hunk header).
+Within a hunk each line starts with:
+
+For instructions on [context_before] and [context_after]:
+- By default, show 3 lines of code immediately above and 3 lines immediately below each change. If a change is within 3 lines of a previous change, do NOT duplicate the first change’s [context_after] lines in the second change’s [context_before] lines.
+- If 3 lines of context is insufficient to uniquely identify the snippet of code within the file, use the @@ operator to indicate the class or function to which the snippet belongs. For instance, we might have:
+@@ class BaseClass
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+- If a code block is repeated so many times in a class or function such that even a single `@@` statement and 3 lines of context cannot uniquely identify the snippet of code, you can use multiple `@@` statements to jump to the right context. For instance:
+
+@@ class BaseClass
+@@ 	 def method():
+[3 lines of pre-context]
+- [old_code]
++ [new_code]
+[3 lines of post-context]
+
+The full grammar definition is below:
+Patch := Begin { FileOp } End
+Begin := "*** Begin Patch" NEWLINE
+End := "*** End Patch" NEWLINE
+FileOp := AddFile | DeleteFile | UpdateFile
+AddFile := "*** Add File: " path NEWLINE { "+" line NEWLINE }
+DeleteFile := "*** Delete File: " path NEWLINE
+UpdateFile := "*** Update File: " path NEWLINE [ MoveTo ] { Hunk }
+MoveTo := "*** Move to: " newPath NEWLINE
+Hunk := "@@" [ header ] NEWLINE { HunkLine } [ "*** End of File" NEWLINE ]
+HunkLine := (" " | "-" | "+") text NEWLINE
+
+A full patch can combine several operations:
+
+*** Begin Patch
+*** Add File: hello.txt
++Hello world
+*** Update File: src/app.py
+*** Move to: src/main.py
+@@ def greet():
+-print("Hi")
++print("Hello, world!")
+*** Delete File: obsolete.txt
+*** End Patch
+
+It is important to remember:
+
+- You must include a header with your intended action (Add/Delete/Update)
+- You must prefix new lines with `+` even when creating a new file
+- File references can only be relative, NEVER ABSOLUTE.
+"#
+            .to_string(),
+        strict: false,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["input".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+    })
+}

llmx-rs/core/src/tools/handlers/grep_files.rs

@@ -0,0 +1,274 @@
+use std::path::Path;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use serde::Deserialize;
+use tokio::process::Command;
+use tokio::time::timeout;
+
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+
+pub struct GrepFilesHandler;
+
+const DEFAULT_LIMIT: usize = 100;
+const MAX_LIMIT: usize = 2000;
+const COMMAND_TIMEOUT: Duration = Duration::from_secs(30);
+
+fn default_limit() -> usize {
+    DEFAULT_LIMIT
+}
+
+#[derive(Deserialize)]
+struct GrepFilesArgs {
+    pattern: String,
+    #[serde(default)]
+    include: Option<String>,
+    #[serde(default)]
+    path: Option<String>,
+    #[serde(default = "default_limit")]
+    limit: usize,
+}
+
+#[async_trait]
+impl ToolHandler for GrepFilesHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation { payload, turn, .. } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "grep_files handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let args: GrepFilesArgs = serde_json::from_str(&arguments).map_err(|err| {
+            FunctionCallError::RespondToModel(format!(
+                "failed to parse function arguments: {err:?}"
+            ))
+        })?;
+
+        let pattern = args.pattern.trim();
+        if pattern.is_empty() {
+            return Err(FunctionCallError::RespondToModel(
+                "pattern must not be empty".to_string(),
+            ));
+        }
+
+        if args.limit == 0 {
+            return Err(FunctionCallError::RespondToModel(
+                "limit must be greater than zero".to_string(),
+            ));
+        }
+
+        let limit = args.limit.min(MAX_LIMIT);
+        let search_path = turn.resolve_path(args.path.clone());
+
+        verify_path_exists(&search_path).await?;
+
+        let include = args.include.as_deref().map(str::trim).and_then(|val| {
+            if val.is_empty() {
+                None
+            } else {
+                Some(val.to_string())
+            }
+        });
+
+        let search_results =
+            run_rg_search(pattern, include.as_deref(), &search_path, limit, &turn.cwd).await?;
+
+        if search_results.is_empty() {
+            Ok(ToolOutput::Function {
+                content: "No matches found.".to_string(),
+                content_items: None,
+                success: Some(false),
+            })
+        } else {
+            Ok(ToolOutput::Function {
+                content: search_results.join("\n"),
+                content_items: None,
+                success: Some(true),
+            })
+        }
+    }
+}
+
+async fn verify_path_exists(path: &Path) -> Result<(), FunctionCallError> {
+    tokio::fs::metadata(path).await.map_err(|err| {
+        FunctionCallError::RespondToModel(format!("unable to access `{}`: {err}", path.display()))
+    })?;
+    Ok(())
+}
+
+async fn run_rg_search(
+    pattern: &str,
+    include: Option<&str>,
+    search_path: &Path,
+    limit: usize,
+    cwd: &Path,
+) -> Result<Vec<String>, FunctionCallError> {
+    let mut command = Command::new("rg");
+    command
+        .current_dir(cwd)
+        .arg("--files-with-matches")
+        .arg("--sortr=modified")
+        .arg("--regexp")
+        .arg(pattern)
+        .arg("--no-messages");
+
+    if let Some(glob) = include {
+        command.arg("--glob").arg(glob);
+    }
+
+    command.arg("--").arg(search_path);
+
+    let output = timeout(COMMAND_TIMEOUT, command.output())
+        .await
+        .map_err(|_| {
+            FunctionCallError::RespondToModel("rg timed out after 30 seconds".to_string())
+        })?
+        .map_err(|err| {
+            FunctionCallError::RespondToModel(format!(
+                "failed to launch rg: {err}. Ensure ripgrep is installed and on PATH."
+            ))
+        })?;
+
+    match output.status.code() {
+        Some(0) => Ok(parse_results(&output.stdout, limit)),
+        Some(1) => Ok(Vec::new()),
+        _ => {
+            let stderr = String::from_utf8_lossy(&output.stderr);
+            Err(FunctionCallError::RespondToModel(format!(
+                "rg failed: {stderr}"
+            )))
+        }
+    }
+}
+
+fn parse_results(stdout: &[u8], limit: usize) -> Vec<String> {
+    let mut results = Vec::new();
+    for line in stdout.split(|byte| *byte == b'\n') {
+        if line.is_empty() {
+            continue;
+        }
+        if let Ok(text) = std::str::from_utf8(line) {
+            if text.is_empty() {
+                continue;
+            }
+            results.push(text.to_string());
+            if results.len() == limit {
+                break;
+            }
+        }
+    }
+    results
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use std::process::Command as StdCommand;
+    use tempfile::tempdir;
+
+    #[test]
+    fn parses_basic_results() {
+        let stdout = b"/tmp/file_a.rs\n/tmp/file_b.rs\n";
+        let parsed = parse_results(stdout, 10);
+        assert_eq!(
+            parsed,
+            vec!["/tmp/file_a.rs".to_string(), "/tmp/file_b.rs".to_string()]
+        );
+    }
+
+    #[test]
+    fn parse_truncates_after_limit() {
+        let stdout = b"/tmp/file_a.rs\n/tmp/file_b.rs\n/tmp/file_c.rs\n";
+        let parsed = parse_results(stdout, 2);
+        assert_eq!(
+            parsed,
+            vec!["/tmp/file_a.rs".to_string(), "/tmp/file_b.rs".to_string()]
+        );
+    }
+
+    #[tokio::test]
+    async fn run_search_returns_results() -> anyhow::Result<()> {
+        if !rg_available() {
+            return Ok(());
+        }
+        let temp = tempdir().expect("create temp dir");
+        let dir = temp.path();
+        std::fs::write(dir.join("match_one.txt"), "alpha beta gamma").unwrap();
+        std::fs::write(dir.join("match_two.txt"), "alpha delta").unwrap();
+        std::fs::write(dir.join("other.txt"), "omega").unwrap();
+
+        let results = run_rg_search("alpha", None, dir, 10, dir).await?;
+        assert_eq!(results.len(), 2);
+        assert!(results.iter().any(|path| path.ends_with("match_one.txt")));
+        assert!(results.iter().any(|path| path.ends_with("match_two.txt")));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn run_search_with_glob_filter() -> anyhow::Result<()> {
+        if !rg_available() {
+            return Ok(());
+        }
+        let temp = tempdir().expect("create temp dir");
+        let dir = temp.path();
+        std::fs::write(dir.join("match_one.rs"), "alpha beta gamma").unwrap();
+        std::fs::write(dir.join("match_two.txt"), "alpha delta").unwrap();
+
+        let results = run_rg_search("alpha", Some("*.rs"), dir, 10, dir).await?;
+        assert_eq!(results.len(), 1);
+        assert!(results.iter().all(|path| path.ends_with("match_one.rs")));
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn run_search_respects_limit() -> anyhow::Result<()> {
+        if !rg_available() {
+            return Ok(());
+        }
+        let temp = tempdir().expect("create temp dir");
+        let dir = temp.path();
+        std::fs::write(dir.join("one.txt"), "alpha one").unwrap();
+        std::fs::write(dir.join("two.txt"), "alpha two").unwrap();
+        std::fs::write(dir.join("three.txt"), "alpha three").unwrap();
+
+        let results = run_rg_search("alpha", None, dir, 2, dir).await?;
+        assert_eq!(results.len(), 2);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn run_search_handles_no_matches() -> anyhow::Result<()> {
+        if !rg_available() {
+            return Ok(());
+        }
+        let temp = tempdir().expect("create temp dir");
+        let dir = temp.path();
+        std::fs::write(dir.join("one.txt"), "omega").unwrap();
+
+        let results = run_rg_search("alpha", None, dir, 5, dir).await?;
+        assert!(results.is_empty());
+        Ok(())
+    }
+
+    fn rg_available() -> bool {
+        StdCommand::new("rg")
+            .arg("--version")
+            .output()
+            .map(|output| output.status.success())
+            .unwrap_or(false)
+    }
+}

llmx-rs/core/src/tools/handlers/list_dir.rs

@@ -0,0 +1,477 @@
+use std::collections::VecDeque;
+use std::ffi::OsStr;
+use std::fs::FileType;
+use std::path::Path;
+use std::path::PathBuf;
+
+use async_trait::async_trait;
+use llmx_utils_string::take_bytes_at_char_boundary;
+use serde::Deserialize;
+use tokio::fs;
+
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+
+pub struct ListDirHandler;
+
+const MAX_ENTRY_LENGTH: usize = 500;
+const INDENTATION_SPACES: usize = 2;
+
+fn default_offset() -> usize {
+    1
+}
+
+fn default_limit() -> usize {
+    25
+}
+
+fn default_depth() -> usize {
+    2
+}
+
+#[derive(Deserialize)]
+struct ListDirArgs {
+    dir_path: String,
+    #[serde(default = "default_offset")]
+    offset: usize,
+    #[serde(default = "default_limit")]
+    limit: usize,
+    #[serde(default = "default_depth")]
+    depth: usize,
+}
+
+#[async_trait]
+impl ToolHandler for ListDirHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation { payload, .. } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "list_dir handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let args: ListDirArgs = serde_json::from_str(&arguments).map_err(|err| {
+            FunctionCallError::RespondToModel(format!(
+                "failed to parse function arguments: {err:?}"
+            ))
+        })?;
+
+        let ListDirArgs {
+            dir_path,
+            offset,
+            limit,
+            depth,
+        } = args;
+
+        if offset == 0 {
+            return Err(FunctionCallError::RespondToModel(
+                "offset must be a 1-indexed entry number".to_string(),
+            ));
+        }
+
+        if limit == 0 {
+            return Err(FunctionCallError::RespondToModel(
+                "limit must be greater than zero".to_string(),
+            ));
+        }
+
+        if depth == 0 {
+            return Err(FunctionCallError::RespondToModel(
+                "depth must be greater than zero".to_string(),
+            ));
+        }
+
+        let path = PathBuf::from(&dir_path);
+        if !path.is_absolute() {
+            return Err(FunctionCallError::RespondToModel(
+                "dir_path must be an absolute path".to_string(),
+            ));
+        }
+
+        let entries = list_dir_slice(&path, offset, limit, depth).await?;
+        let mut output = Vec::with_capacity(entries.len() + 1);
+        output.push(format!("Absolute path: {}", path.display()));
+        output.extend(entries);
+        Ok(ToolOutput::Function {
+            content: output.join("\n"),
+            content_items: None,
+            success: Some(true),
+        })
+    }
+}
+
+async fn list_dir_slice(
+    path: &Path,
+    offset: usize,
+    limit: usize,
+    depth: usize,
+) -> Result<Vec<String>, FunctionCallError> {
+    let mut entries = Vec::new();
+    collect_entries(path, Path::new(""), depth, &mut entries).await?;
+
+    if entries.is_empty() {
+        return Ok(Vec::new());
+    }
+
+    let start_index = offset - 1;
+    if start_index >= entries.len() {
+        return Err(FunctionCallError::RespondToModel(
+            "offset exceeds directory entry count".to_string(),
+        ));
+    }
+
+    let remaining_entries = entries.len() - start_index;
+    let capped_limit = limit.min(remaining_entries);
+    let end_index = start_index + capped_limit;
+    let mut selected_entries = entries[start_index..end_index].to_vec();
+    selected_entries.sort_unstable_by(|a, b| a.name.cmp(&b.name));
+    let mut formatted = Vec::with_capacity(selected_entries.len());
+
+    for entry in &selected_entries {
+        formatted.push(format_entry_line(entry));
+    }
+
+    if end_index < entries.len() {
+        formatted.push(format!("More than {capped_limit} entries found"));
+    }
+
+    Ok(formatted)
+}
+
+async fn collect_entries(
+    dir_path: &Path,
+    relative_prefix: &Path,
+    depth: usize,
+    entries: &mut Vec<DirEntry>,
+) -> Result<(), FunctionCallError> {
+    let mut queue = VecDeque::new();
+    queue.push_back((dir_path.to_path_buf(), relative_prefix.to_path_buf(), depth));
+
+    while let Some((current_dir, prefix, remaining_depth)) = queue.pop_front() {
+        let mut read_dir = fs::read_dir(&current_dir).await.map_err(|err| {
+            FunctionCallError::RespondToModel(format!("failed to read directory: {err}"))
+        })?;
+
+        let mut dir_entries = Vec::new();
+
+        while let Some(entry) = read_dir.next_entry().await.map_err(|err| {
+            FunctionCallError::RespondToModel(format!("failed to read directory: {err}"))
+        })? {
+            let file_type = entry.file_type().await.map_err(|err| {
+                FunctionCallError::RespondToModel(format!("failed to inspect entry: {err}"))
+            })?;
+
+            let file_name = entry.file_name();
+            let relative_path = if prefix.as_os_str().is_empty() {
+                PathBuf::from(&file_name)
+            } else {
+                prefix.join(&file_name)
+            };
+
+            let display_name = format_entry_component(&file_name);
+            let display_depth = prefix.components().count();
+            let sort_key = format_entry_name(&relative_path);
+            let kind = DirEntryKind::from(&file_type);
+            dir_entries.push((
+                entry.path(),
+                relative_path,
+                kind,
+                DirEntry {
+                    name: sort_key,
+                    display_name,
+                    depth: display_depth,
+                    kind,
+                },
+            ));
+        }
+
+        dir_entries.sort_unstable_by(|a, b| a.3.name.cmp(&b.3.name));
+
+        for (entry_path, relative_path, kind, dir_entry) in dir_entries {
+            if kind == DirEntryKind::Directory && remaining_depth > 1 {
+                queue.push_back((entry_path, relative_path, remaining_depth - 1));
+            }
+            entries.push(dir_entry);
+        }
+    }
+
+    Ok(())
+}
+
+fn format_entry_name(path: &Path) -> String {
+    let normalized = path.to_string_lossy().replace("\\", "/");
+    if normalized.len() > MAX_ENTRY_LENGTH {
+        take_bytes_at_char_boundary(&normalized, MAX_ENTRY_LENGTH).to_string()
+    } else {
+        normalized
+    }
+}
+
+fn format_entry_component(name: &OsStr) -> String {
+    let normalized = name.to_string_lossy();
+    if normalized.len() > MAX_ENTRY_LENGTH {
+        take_bytes_at_char_boundary(&normalized, MAX_ENTRY_LENGTH).to_string()
+    } else {
+        normalized.to_string()
+    }
+}
+
+fn format_entry_line(entry: &DirEntry) -> String {
+    let indent = " ".repeat(entry.depth * INDENTATION_SPACES);
+    let mut name = entry.display_name.clone();
+    match entry.kind {
+        DirEntryKind::Directory => name.push('/'),
+        DirEntryKind::Symlink => name.push('@'),
+        DirEntryKind::Other => name.push('?'),
+        DirEntryKind::File => {}
+    }
+    format!("{indent}{name}")
+}
+
+#[derive(Clone)]
+struct DirEntry {
+    name: String,
+    display_name: String,
+    depth: usize,
+    kind: DirEntryKind,
+}
+
+#[derive(Clone, Copy, PartialEq, Eq)]
+enum DirEntryKind {
+    Directory,
+    File,
+    Symlink,
+    Other,
+}
+
+impl From<&FileType> for DirEntryKind {
+    fn from(file_type: &FileType) -> Self {
+        if file_type.is_symlink() {
+            DirEntryKind::Symlink
+        } else if file_type.is_dir() {
+            DirEntryKind::Directory
+        } else if file_type.is_file() {
+            DirEntryKind::File
+        } else {
+            DirEntryKind::Other
+        }
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use tempfile::tempdir;
+
+    #[tokio::test]
+    async fn lists_directory_entries() {
+        let temp = tempdir().expect("create tempdir");
+        let dir_path = temp.path();
+
+        let sub_dir = dir_path.join("nested");
+        tokio::fs::create_dir(&sub_dir)
+            .await
+            .expect("create sub dir");
+
+        let deeper_dir = sub_dir.join("deeper");
+        tokio::fs::create_dir(&deeper_dir)
+            .await
+            .expect("create deeper dir");
+
+        tokio::fs::write(dir_path.join("entry.txt"), b"content")
+            .await
+            .expect("write file");
+        tokio::fs::write(sub_dir.join("child.txt"), b"child")
+            .await
+            .expect("write child");
+        tokio::fs::write(deeper_dir.join("grandchild.txt"), b"grandchild")
+            .await
+            .expect("write grandchild");
+
+        #[cfg(unix)]
+        {
+            use std::os::unix::fs::symlink;
+            let link_path = dir_path.join("link");
+            symlink(dir_path.join("entry.txt"), &link_path).expect("create symlink");
+        }
+
+        let entries = list_dir_slice(dir_path, 1, 20, 3)
+            .await
+            .expect("list directory");
+
+        #[cfg(unix)]
+        let expected = vec![
+            "entry.txt".to_string(),
+            "link@".to_string(),
+            "nested/".to_string(),
+            "  child.txt".to_string(),
+            "  deeper/".to_string(),
+            "    grandchild.txt".to_string(),
+        ];
+
+        #[cfg(not(unix))]
+        let expected = vec![
+            "entry.txt".to_string(),
+            "nested/".to_string(),
+            "  child.txt".to_string(),
+            "  deeper/".to_string(),
+            "    grandchild.txt".to_string(),
+        ];
+
+        assert_eq!(entries, expected);
+    }
+
+    #[tokio::test]
+    async fn errors_when_offset_exceeds_entries() {
+        let temp = tempdir().expect("create tempdir");
+        let dir_path = temp.path();
+        tokio::fs::create_dir(dir_path.join("nested"))
+            .await
+            .expect("create sub dir");
+
+        let err = list_dir_slice(dir_path, 10, 1, 2)
+            .await
+            .expect_err("offset exceeds entries");
+        assert_eq!(
+            err,
+            FunctionCallError::RespondToModel("offset exceeds directory entry count".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn respects_depth_parameter() {
+        let temp = tempdir().expect("create tempdir");
+        let dir_path = temp.path();
+        let nested = dir_path.join("nested");
+        let deeper = nested.join("deeper");
+        tokio::fs::create_dir(&nested).await.expect("create nested");
+        tokio::fs::create_dir(&deeper).await.expect("create deeper");
+        tokio::fs::write(dir_path.join("root.txt"), b"root")
+            .await
+            .expect("write root");
+        tokio::fs::write(nested.join("child.txt"), b"child")
+            .await
+            .expect("write nested");
+        tokio::fs::write(deeper.join("grandchild.txt"), b"deep")
+            .await
+            .expect("write deeper");
+
+        let entries_depth_one = list_dir_slice(dir_path, 1, 10, 1)
+            .await
+            .expect("list depth 1");
+        assert_eq!(
+            entries_depth_one,
+            vec!["nested/".to_string(), "root.txt".to_string(),]
+        );
+
+        let entries_depth_two = list_dir_slice(dir_path, 1, 20, 2)
+            .await
+            .expect("list depth 2");
+        assert_eq!(
+            entries_depth_two,
+            vec![
+                "nested/".to_string(),
+                "  child.txt".to_string(),
+                "  deeper/".to_string(),
+                "root.txt".to_string(),
+            ]
+        );
+
+        let entries_depth_three = list_dir_slice(dir_path, 1, 30, 3)
+            .await
+            .expect("list depth 3");
+        assert_eq!(
+            entries_depth_three,
+            vec![
+                "nested/".to_string(),
+                "  child.txt".to_string(),
+                "  deeper/".to_string(),
+                "    grandchild.txt".to_string(),
+                "root.txt".to_string(),
+            ]
+        );
+    }
+
+    #[tokio::test]
+    async fn handles_large_limit_without_overflow() {
+        let temp = tempdir().expect("create tempdir");
+        let dir_path = temp.path();
+        tokio::fs::write(dir_path.join("alpha.txt"), b"alpha")
+            .await
+            .expect("write alpha");
+        tokio::fs::write(dir_path.join("beta.txt"), b"beta")
+            .await
+            .expect("write beta");
+        tokio::fs::write(dir_path.join("gamma.txt"), b"gamma")
+            .await
+            .expect("write gamma");
+
+        let entries = list_dir_slice(dir_path, 2, usize::MAX, 1)
+            .await
+            .expect("list without overflow");
+        assert_eq!(
+            entries,
+            vec!["beta.txt".to_string(), "gamma.txt".to_string(),]
+        );
+    }
+
+    #[tokio::test]
+    async fn indicates_truncated_results() {
+        let temp = tempdir().expect("create tempdir");
+        let dir_path = temp.path();
+
+        for idx in 0..40 {
+            let file = dir_path.join(format!("file_{idx:02}.txt"));
+            tokio::fs::write(file, b"content")
+                .await
+                .expect("write file");
+        }
+
+        let entries = list_dir_slice(dir_path, 1, 25, 1)
+            .await
+            .expect("list directory");
+        assert_eq!(entries.len(), 26);
+        assert_eq!(
+            entries.last(),
+            Some(&"More than 25 entries found".to_string())
+        );
+    }
+
+    #[tokio::test]
+    async fn bfs_truncation() -> anyhow::Result<()> {
+        let temp = tempdir()?;
+        let dir_path = temp.path();
+        let nested = dir_path.join("nested");
+        let deeper = nested.join("deeper");
+        tokio::fs::create_dir(&nested).await?;
+        tokio::fs::create_dir(&deeper).await?;
+        tokio::fs::write(dir_path.join("root.txt"), b"root").await?;
+        tokio::fs::write(nested.join("child.txt"), b"child").await?;
+        tokio::fs::write(deeper.join("grandchild.txt"), b"deep").await?;
+
+        let entries_depth_three = list_dir_slice(dir_path, 1, 3, 3).await?;
+        assert_eq!(
+            entries_depth_three,
+            vec![
+                "nested/".to_string(),
+                "  child.txt".to_string(),
+                "root.txt".to_string(),
+                "More than 3 entries found".to_string()
+            ]
+        );
+
+        Ok(())
+    }
+}

llmx-rs/core/src/tools/handlers/mcp.rs

@@ -0,0 +1,75 @@
+use async_trait::async_trait;
+
+use crate::function_tool::FunctionCallError;
+use crate::mcp_tool_call::handle_mcp_tool_call;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+
+pub struct McpHandler;
+
+#[async_trait]
+impl ToolHandler for McpHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Mcp
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation {
+            session,
+            turn,
+            call_id,
+            payload,
+            ..
+        } = invocation;
+
+        let payload = match payload {
+            ToolPayload::Mcp {
+                server,
+                tool,
+                raw_arguments,
+            } => (server, tool, raw_arguments),
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "mcp handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let (server, tool, raw_arguments) = payload;
+        let arguments_str = raw_arguments;
+
+        let response = handle_mcp_tool_call(
+            session.as_ref(),
+            turn.as_ref(),
+            call_id.clone(),
+            server,
+            tool,
+            arguments_str,
+        )
+        .await;
+
+        match response {
+            llmx_protocol::models::ResponseInputItem::McpToolCallOutput { result, .. } => {
+                Ok(ToolOutput::Mcp { result })
+            }
+            llmx_protocol::models::ResponseInputItem::FunctionCallOutput { output, .. } => {
+                let llmx_protocol::models::FunctionCallOutputPayload {
+                    content,
+                    content_items,
+                    success,
+                } = output;
+                Ok(ToolOutput::Function {
+                    content,
+                    content_items,
+                    success,
+                })
+            }
+            _ => Err(FunctionCallError::RespondToModel(
+                "mcp handler received unexpected response variant".to_string(),
+            )),
+        }
+    }
+}

llmx-rs/core/src/tools/handlers/mcp_resource.rs

@@ -0,0 +1,789 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+use std::time::Instant;
+
+use async_trait::async_trait;
+use mcp_types::CallToolResult;
+use mcp_types::ContentBlock;
+use mcp_types::ListResourceTemplatesRequestParams;
+use mcp_types::ListResourceTemplatesResult;
+use mcp_types::ListResourcesRequestParams;
+use mcp_types::ListResourcesResult;
+use mcp_types::ReadResourceRequestParams;
+use mcp_types::ReadResourceResult;
+use mcp_types::Resource;
+use mcp_types::ResourceTemplate;
+use mcp_types::TextContent;
+use serde::Deserialize;
+use serde::Serialize;
+use serde::de::DeserializeOwned;
+use serde_json::Value;
+
+use crate::function_tool::FunctionCallError;
+use crate::llmx::Session;
+use crate::llmx::TurnContext;
+use crate::protocol::EventMsg;
+use crate::protocol::McpInvocation;
+use crate::protocol::McpToolCallBeginEvent;
+use crate::protocol::McpToolCallEndEvent;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+
+pub struct McpResourceHandler;
+
+#[derive(Debug, Deserialize, Default)]
+struct ListResourcesArgs {
+    /// Lists all resources from all servers if not specified.
+    #[serde(default)]
+    server: Option<String>,
+    #[serde(default)]
+    cursor: Option<String>,
+}
+
+#[derive(Debug, Deserialize, Default)]
+struct ListResourceTemplatesArgs {
+    /// Lists all resource templates from all servers if not specified.
+    #[serde(default)]
+    server: Option<String>,
+    #[serde(default)]
+    cursor: Option<String>,
+}
+
+#[derive(Debug, Deserialize)]
+struct ReadResourceArgs {
+    server: String,
+    uri: String,
+}
+
+#[derive(Debug, Serialize)]
+struct ResourceWithServer {
+    server: String,
+    #[serde(flatten)]
+    resource: Resource,
+}
+
+impl ResourceWithServer {
+    fn new(server: String, resource: Resource) -> Self {
+        Self { server, resource }
+    }
+}
+
+#[derive(Debug, Serialize)]
+struct ResourceTemplateWithServer {
+    server: String,
+    #[serde(flatten)]
+    template: ResourceTemplate,
+}
+
+impl ResourceTemplateWithServer {
+    fn new(server: String, template: ResourceTemplate) -> Self {
+        Self { server, template }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ListResourcesPayload {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    server: Option<String>,
+    resources: Vec<ResourceWithServer>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    next_cursor: Option<String>,
+}
+
+impl ListResourcesPayload {
+    fn from_single_server(server: String, result: ListResourcesResult) -> Self {
+        let resources = result
+            .resources
+            .into_iter()
+            .map(|resource| ResourceWithServer::new(server.clone(), resource))
+            .collect();
+        Self {
+            server: Some(server),
+            resources,
+            next_cursor: result.next_cursor,
+        }
+    }
+
+    fn from_all_servers(resources_by_server: HashMap<String, Vec<Resource>>) -> Self {
+        let mut entries: Vec<(String, Vec<Resource>)> = resources_by_server.into_iter().collect();
+        entries.sort_by(|a, b| a.0.cmp(&b.0));
+
+        let mut resources = Vec::new();
+        for (server, server_resources) in entries {
+            for resource in server_resources {
+                resources.push(ResourceWithServer::new(server.clone(), resource));
+            }
+        }
+
+        Self {
+            server: None,
+            resources,
+            next_cursor: None,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+#[serde(rename_all = "camelCase")]
+struct ListResourceTemplatesPayload {
+    #[serde(skip_serializing_if = "Option::is_none")]
+    server: Option<String>,
+    resource_templates: Vec<ResourceTemplateWithServer>,
+    #[serde(skip_serializing_if = "Option::is_none")]
+    next_cursor: Option<String>,
+}
+
+impl ListResourceTemplatesPayload {
+    fn from_single_server(server: String, result: ListResourceTemplatesResult) -> Self {
+        let resource_templates = result
+            .resource_templates
+            .into_iter()
+            .map(|template| ResourceTemplateWithServer::new(server.clone(), template))
+            .collect();
+        Self {
+            server: Some(server),
+            resource_templates,
+            next_cursor: result.next_cursor,
+        }
+    }
+
+    fn from_all_servers(templates_by_server: HashMap<String, Vec<ResourceTemplate>>) -> Self {
+        let mut entries: Vec<(String, Vec<ResourceTemplate>)> =
+            templates_by_server.into_iter().collect();
+        entries.sort_by(|a, b| a.0.cmp(&b.0));
+
+        let mut resource_templates = Vec::new();
+        for (server, server_templates) in entries {
+            for template in server_templates {
+                resource_templates.push(ResourceTemplateWithServer::new(server.clone(), template));
+            }
+        }
+
+        Self {
+            server: None,
+            resource_templates,
+            next_cursor: None,
+        }
+    }
+}
+
+#[derive(Debug, Serialize)]
+struct ReadResourcePayload {
+    server: String,
+    uri: String,
+    #[serde(flatten)]
+    result: ReadResourceResult,
+}
+
+#[async_trait]
+impl ToolHandler for McpResourceHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation {
+            session,
+            turn,
+            call_id,
+            tool_name,
+            payload,
+            ..
+        } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "mcp_resource handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let arguments_value = parse_arguments(arguments.as_str())?;
+
+        match tool_name.as_str() {
+            "list_mcp_resources" => {
+                handle_list_resources(
+                    Arc::clone(&session),
+                    Arc::clone(&turn),
+                    call_id.clone(),
+                    arguments_value.clone(),
+                )
+                .await
+            }
+            "list_mcp_resource_templates" => {
+                handle_list_resource_templates(
+                    Arc::clone(&session),
+                    Arc::clone(&turn),
+                    call_id.clone(),
+                    arguments_value.clone(),
+                )
+                .await
+            }
+            "read_mcp_resource" => {
+                handle_read_resource(
+                    Arc::clone(&session),
+                    Arc::clone(&turn),
+                    call_id,
+                    arguments_value,
+                )
+                .await
+            }
+            other => Err(FunctionCallError::RespondToModel(format!(
+                "unsupported MCP resource tool: {other}"
+            ))),
+        }
+    }
+}
+
+async fn handle_list_resources(
+    session: Arc<Session>,
+    turn: Arc<TurnContext>,
+    call_id: String,
+    arguments: Option<Value>,
+) -> Result<ToolOutput, FunctionCallError> {
+    let args: ListResourcesArgs = parse_args_with_default(arguments.clone())?;
+    let ListResourcesArgs { server, cursor } = args;
+    let server = normalize_optional_string(server);
+    let cursor = normalize_optional_string(cursor);
+
+    let invocation = McpInvocation {
+        server: server.clone().unwrap_or_else(|| "llmx".to_string()),
+        tool: "list_mcp_resources".to_string(),
+        arguments: arguments.clone(),
+    };
+
+    emit_tool_call_begin(&session, turn.as_ref(), &call_id, invocation.clone()).await;
+    let start = Instant::now();
+
+    let payload_result: Result<ListResourcesPayload, FunctionCallError> = async {
+        if let Some(server_name) = server.clone() {
+            let params = cursor.clone().map(|value| ListResourcesRequestParams {
+                cursor: Some(value),
+            });
+            let result = session
+                .list_resources(&server_name, params)
+                .await
+                .map_err(|err| {
+                    FunctionCallError::RespondToModel(format!("resources/list failed: {err:#}"))
+                })?;
+            Ok(ListResourcesPayload::from_single_server(
+                server_name,
+                result,
+            ))
+        } else {
+            if cursor.is_some() {
+                return Err(FunctionCallError::RespondToModel(
+                    "cursor can only be used when a server is specified".to_string(),
+                ));
+            }
+
+            let resources = session
+                .services
+                .mcp_connection_manager
+                .list_all_resources()
+                .await;
+            Ok(ListResourcesPayload::from_all_servers(resources))
+        }
+    }
+    .await;
+
+    match payload_result {
+        Ok(payload) => match serialize_function_output(payload) {
+            Ok(output) => {
+                let ToolOutput::Function {
+                    content, success, ..
+                } = &output
+                else {
+                    unreachable!("MCP resource handler should return function output");
+                };
+                let duration = start.elapsed();
+                emit_tool_call_end(
+                    &session,
+                    turn.as_ref(),
+                    &call_id,
+                    invocation,
+                    duration,
+                    Ok(call_tool_result_from_content(content, *success)),
+                )
+                .await;
+                Ok(output)
+            }
+            Err(err) => {
+                let duration = start.elapsed();
+                let message = err.to_string();
+                emit_tool_call_end(
+                    &session,
+                    turn.as_ref(),
+                    &call_id,
+                    invocation,
+                    duration,
+                    Err(message.clone()),
+                )
+                .await;
+                Err(err)
+            }
+        },
+        Err(err) => {
+            let duration = start.elapsed();
+            let message = err.to_string();
+            emit_tool_call_end(
+                &session,
+                turn.as_ref(),
+                &call_id,
+                invocation,
+                duration,
+                Err(message.clone()),
+            )
+            .await;
+            Err(err)
+        }
+    }
+}
+
+async fn handle_list_resource_templates(
+    session: Arc<Session>,
+    turn: Arc<TurnContext>,
+    call_id: String,
+    arguments: Option<Value>,
+) -> Result<ToolOutput, FunctionCallError> {
+    let args: ListResourceTemplatesArgs = parse_args_with_default(arguments.clone())?;
+    let ListResourceTemplatesArgs { server, cursor } = args;
+    let server = normalize_optional_string(server);
+    let cursor = normalize_optional_string(cursor);
+
+    let invocation = McpInvocation {
+        server: server.clone().unwrap_or_else(|| "llmx".to_string()),
+        tool: "list_mcp_resource_templates".to_string(),
+        arguments: arguments.clone(),
+    };
+
+    emit_tool_call_begin(&session, turn.as_ref(), &call_id, invocation.clone()).await;
+    let start = Instant::now();
+
+    let payload_result: Result<ListResourceTemplatesPayload, FunctionCallError> = async {
+        if let Some(server_name) = server.clone() {
+            let params = cursor
+                .clone()
+                .map(|value| ListResourceTemplatesRequestParams {
+                    cursor: Some(value),
+                });
+            let result = session
+                .list_resource_templates(&server_name, params)
+                .await
+                .map_err(|err| {
+                    FunctionCallError::RespondToModel(format!(
+                        "resources/templates/list failed: {err:#}"
+                    ))
+                })?;
+            Ok(ListResourceTemplatesPayload::from_single_server(
+                server_name,
+                result,
+            ))
+        } else {
+            if cursor.is_some() {
+                return Err(FunctionCallError::RespondToModel(
+                    "cursor can only be used when a server is specified".to_string(),
+                ));
+            }
+
+            let templates = session
+                .services
+                .mcp_connection_manager
+                .list_all_resource_templates()
+                .await;
+            Ok(ListResourceTemplatesPayload::from_all_servers(templates))
+        }
+    }
+    .await;
+
+    match payload_result {
+        Ok(payload) => match serialize_function_output(payload) {
+            Ok(output) => {
+                let ToolOutput::Function {
+                    content, success, ..
+                } = &output
+                else {
+                    unreachable!("MCP resource handler should return function output");
+                };
+                let duration = start.elapsed();
+                emit_tool_call_end(
+                    &session,
+                    turn.as_ref(),
+                    &call_id,
+                    invocation,
+                    duration,
+                    Ok(call_tool_result_from_content(content, *success)),
+                )
+                .await;
+                Ok(output)
+            }
+            Err(err) => {
+                let duration = start.elapsed();
+                let message = err.to_string();
+                emit_tool_call_end(
+                    &session,
+                    turn.as_ref(),
+                    &call_id,
+                    invocation,
+                    duration,
+                    Err(message.clone()),
+                )
+                .await;
+                Err(err)
+            }
+        },
+        Err(err) => {
+            let duration = start.elapsed();
+            let message = err.to_string();
+            emit_tool_call_end(
+                &session,
+                turn.as_ref(),
+                &call_id,
+                invocation,
+                duration,
+                Err(message.clone()),
+            )
+            .await;
+            Err(err)
+        }
+    }
+}
+
+async fn handle_read_resource(
+    session: Arc<Session>,
+    turn: Arc<TurnContext>,
+    call_id: String,
+    arguments: Option<Value>,
+) -> Result<ToolOutput, FunctionCallError> {
+    let args: ReadResourceArgs = parse_args(arguments.clone())?;
+    let ReadResourceArgs { server, uri } = args;
+    let server = normalize_required_string("server", server)?;
+    let uri = normalize_required_string("uri", uri)?;
+
+    let invocation = McpInvocation {
+        server: server.clone(),
+        tool: "read_mcp_resource".to_string(),
+        arguments: arguments.clone(),
+    };
+
+    emit_tool_call_begin(&session, turn.as_ref(), &call_id, invocation.clone()).await;
+    let start = Instant::now();
+
+    let payload_result: Result<ReadResourcePayload, FunctionCallError> = async {
+        let result = session
+            .read_resource(&server, ReadResourceRequestParams { uri: uri.clone() })
+            .await
+            .map_err(|err| {
+                FunctionCallError::RespondToModel(format!("resources/read failed: {err:#}"))
+            })?;
+
+        Ok(ReadResourcePayload {
+            server,
+            uri,
+            result,
+        })
+    }
+    .await;
+
+    match payload_result {
+        Ok(payload) => match serialize_function_output(payload) {
+            Ok(output) => {
+                let ToolOutput::Function {
+                    content, success, ..
+                } = &output
+                else {
+                    unreachable!("MCP resource handler should return function output");
+                };
+                let duration = start.elapsed();
+                emit_tool_call_end(
+                    &session,
+                    turn.as_ref(),
+                    &call_id,
+                    invocation,
+                    duration,
+                    Ok(call_tool_result_from_content(content, *success)),
+                )
+                .await;
+                Ok(output)
+            }
+            Err(err) => {
+                let duration = start.elapsed();
+                let message = err.to_string();
+                emit_tool_call_end(
+                    &session,
+                    turn.as_ref(),
+                    &call_id,
+                    invocation,
+                    duration,
+                    Err(message.clone()),
+                )
+                .await;
+                Err(err)
+            }
+        },
+        Err(err) => {
+            let duration = start.elapsed();
+            let message = err.to_string();
+            emit_tool_call_end(
+                &session,
+                turn.as_ref(),
+                &call_id,
+                invocation,
+                duration,
+                Err(message.clone()),
+            )
+            .await;
+            Err(err)
+        }
+    }
+}
+
+fn call_tool_result_from_content(content: &str, success: Option<bool>) -> CallToolResult {
+    CallToolResult {
+        content: vec![ContentBlock::TextContent(TextContent {
+            annotations: None,
+            text: content.to_string(),
+            r#type: "text".to_string(),
+        })],
+        is_error: success.map(|value| !value),
+        structured_content: None,
+    }
+}
+
+async fn emit_tool_call_begin(
+    session: &Arc<Session>,
+    turn: &TurnContext,
+    call_id: &str,
+    invocation: McpInvocation,
+) {
+    session
+        .send_event(
+            turn,
+            EventMsg::McpToolCallBegin(McpToolCallBeginEvent {
+                call_id: call_id.to_string(),
+                invocation,
+            }),
+        )
+        .await;
+}
+
+async fn emit_tool_call_end(
+    session: &Arc<Session>,
+    turn: &TurnContext,
+    call_id: &str,
+    invocation: McpInvocation,
+    duration: Duration,
+    result: Result<CallToolResult, String>,
+) {
+    session
+        .send_event(
+            turn,
+            EventMsg::McpToolCallEnd(McpToolCallEndEvent {
+                call_id: call_id.to_string(),
+                invocation,
+                duration,
+                result,
+            }),
+        )
+        .await;
+}
+
+fn normalize_optional_string(input: Option<String>) -> Option<String> {
+    input.and_then(|value| {
+        let trimmed = value.trim().to_string();
+        if trimmed.is_empty() {
+            None
+        } else {
+            Some(trimmed)
+        }
+    })
+}
+
+fn normalize_required_string(field: &str, value: String) -> Result<String, FunctionCallError> {
+    match normalize_optional_string(Some(value)) {
+        Some(normalized) => Ok(normalized),
+        None => Err(FunctionCallError::RespondToModel(format!(
+            "{field} must be provided"
+        ))),
+    }
+}
+
+fn serialize_function_output<T>(payload: T) -> Result<ToolOutput, FunctionCallError>
+where
+    T: Serialize,
+{
+    let content = serde_json::to_string(&payload).map_err(|err| {
+        FunctionCallError::RespondToModel(format!(
+            "failed to serialize MCP resource response: {err}"
+        ))
+    })?;
+
+    Ok(ToolOutput::Function {
+        content,
+        content_items: None,
+        success: Some(true),
+    })
+}
+
+fn parse_arguments(raw_args: &str) -> Result<Option<Value>, FunctionCallError> {
+    if raw_args.trim().is_empty() {
+        Ok(None)
+    } else {
+        serde_json::from_str(raw_args).map(Some).map_err(|err| {
+            FunctionCallError::RespondToModel(format!("failed to parse function arguments: {err}"))
+        })
+    }
+}
+
+fn parse_args<T>(arguments: Option<Value>) -> Result<T, FunctionCallError>
+where
+    T: DeserializeOwned,
+{
+    match arguments {
+        Some(value) => serde_json::from_value(value).map_err(|err| {
+            FunctionCallError::RespondToModel(format!("failed to parse function arguments: {err}"))
+        }),
+        None => Err(FunctionCallError::RespondToModel(
+            "failed to parse function arguments: expected value".to_string(),
+        )),
+    }
+}
+
+fn parse_args_with_default<T>(arguments: Option<Value>) -> Result<T, FunctionCallError>
+where
+    T: DeserializeOwned + Default,
+{
+    match arguments {
+        Some(value) => parse_args(Some(value)),
+        None => Ok(T::default()),
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    use mcp_types::ListResourcesResult;
+    use mcp_types::ResourceTemplate;
+    use pretty_assertions::assert_eq;
+    use serde_json::json;
+
+    fn resource(uri: &str, name: &str) -> Resource {
+        Resource {
+            annotations: None,
+            description: None,
+            mime_type: None,
+            name: name.to_string(),
+            size: None,
+            title: None,
+            uri: uri.to_string(),
+        }
+    }
+
+    fn template(uri_template: &str, name: &str) -> ResourceTemplate {
+        ResourceTemplate {
+            annotations: None,
+            description: None,
+            mime_type: None,
+            name: name.to_string(),
+            title: None,
+            uri_template: uri_template.to_string(),
+        }
+    }
+
+    #[test]
+    fn resource_with_server_serializes_server_field() {
+        let entry = ResourceWithServer::new("test".to_string(), resource("memo://id", "memo"));
+        let value = serde_json::to_value(&entry).expect("serialize resource");
+
+        assert_eq!(value["server"], json!("test"));
+        assert_eq!(value["uri"], json!("memo://id"));
+        assert_eq!(value["name"], json!("memo"));
+    }
+
+    #[test]
+    fn list_resources_payload_from_single_server_copies_next_cursor() {
+        let result = ListResourcesResult {
+            next_cursor: Some("cursor-1".to_string()),
+            resources: vec![resource("memo://id", "memo")],
+        };
+        let payload = ListResourcesPayload::from_single_server("srv".to_string(), result);
+        let value = serde_json::to_value(&payload).expect("serialize payload");
+
+        assert_eq!(value["server"], json!("srv"));
+        assert_eq!(value["nextCursor"], json!("cursor-1"));
+        let resources = value["resources"].as_array().expect("resources array");
+        assert_eq!(resources.len(), 1);
+        assert_eq!(resources[0]["server"], json!("srv"));
+    }
+
+    #[test]
+    fn list_resources_payload_from_all_servers_is_sorted() {
+        let mut map = HashMap::new();
+        map.insert("beta".to_string(), vec![resource("memo://b-1", "b-1")]);
+        map.insert(
+            "alpha".to_string(),
+            vec![resource("memo://a-1", "a-1"), resource("memo://a-2", "a-2")],
+        );
+
+        let payload = ListResourcesPayload::from_all_servers(map);
+        let value = serde_json::to_value(&payload).expect("serialize payload");
+        let uris: Vec<String> = value["resources"]
+            .as_array()
+            .expect("resources array")
+            .iter()
+            .map(|entry| entry["uri"].as_str().unwrap().to_string())
+            .collect();
+
+        assert_eq!(
+            uris,
+            vec![
+                "memo://a-1".to_string(),
+                "memo://a-2".to_string(),
+                "memo://b-1".to_string()
+            ]
+        );
+    }
+
+    #[test]
+    fn call_tool_result_from_content_marks_success() {
+        let result = call_tool_result_from_content("{}", Some(true));
+        assert_eq!(result.is_error, Some(false));
+        assert_eq!(result.content.len(), 1);
+    }
+
+    #[test]
+    fn parse_arguments_handles_empty_and_json() {
+        assert!(
+            parse_arguments(" \n\t").unwrap().is_none(),
+            "expected None for empty arguments"
+        );
+
+        let value = parse_arguments(r#"{"server":"figma"}"#)
+            .expect("parse json")
+            .expect("value present");
+        assert_eq!(value["server"], json!("figma"));
+    }
+
+    #[test]
+    fn template_with_server_serializes_server_field() {
+        let entry =
+            ResourceTemplateWithServer::new("srv".to_string(), template("memo://{id}", "memo"));
+        let value = serde_json::to_value(&entry).expect("serialize template");
+
+        assert_eq!(
+            value,
+            json!({
+                "server": "srv",
+                "uriTemplate": "memo://{id}",
+                "name": "memo"
+            })
+        );
+    }
+}

llmx-rs/core/src/tools/handlers/mod.rs

@@ -0,0 +1,25 @@
+pub mod apply_patch;
+mod grep_files;
+mod list_dir;
+mod mcp;
+mod mcp_resource;
+mod plan;
+mod read_file;
+mod shell;
+mod test_sync;
+mod unified_exec;
+mod view_image;
+
+pub use plan::PLAN_TOOL;
+
+pub use apply_patch::ApplyPatchHandler;
+pub use grep_files::GrepFilesHandler;
+pub use list_dir::ListDirHandler;
+pub use mcp::McpHandler;
+pub use mcp_resource::McpResourceHandler;
+pub use plan::PlanHandler;
+pub use read_file::ReadFileHandler;
+pub use shell::ShellHandler;
+pub use test_sync::TestSyncHandler;
+pub use unified_exec::UnifiedExecHandler;
+pub use view_image::ViewImageHandler;

llmx-rs/core/src/tools/handlers/plan.rs

@@ -0,0 +1,117 @@
+use crate::client_common::tools::ResponsesApiTool;
+use crate::client_common::tools::ToolSpec;
+use crate::function_tool::FunctionCallError;
+use crate::llmx::Session;
+use crate::llmx::TurnContext;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+use crate::tools::spec::JsonSchema;
+use async_trait::async_trait;
+use llmx_protocol::plan_tool::UpdatePlanArgs;
+use llmx_protocol::protocol::EventMsg;
+use std::collections::BTreeMap;
+use std::sync::LazyLock;
+
+pub struct PlanHandler;
+
+pub static PLAN_TOOL: LazyLock<ToolSpec> = LazyLock::new(|| {
+    let mut plan_item_props = BTreeMap::new();
+    plan_item_props.insert("step".to_string(), JsonSchema::String { description: None });
+    plan_item_props.insert(
+        "status".to_string(),
+        JsonSchema::String {
+            description: Some("One of: pending, in_progress, completed".to_string()),
+        },
+    );
+
+    let plan_items_schema = JsonSchema::Array {
+        description: Some("The list of steps".to_string()),
+        items: Box::new(JsonSchema::Object {
+            properties: plan_item_props,
+            required: Some(vec!["step".to_string(), "status".to_string()]),
+            additional_properties: Some(false.into()),
+        }),
+    };
+
+    let mut properties = BTreeMap::new();
+    properties.insert(
+        "explanation".to_string(),
+        JsonSchema::String { description: None },
+    );
+    properties.insert("plan".to_string(), plan_items_schema);
+
+    ToolSpec::Function(ResponsesApiTool {
+        name: "update_plan".to_string(),
+        description: r#"Updates the task plan.
+Provide an optional explanation and a list of plan items, each with a step and status.
+At most one step can be in_progress at a time.
+"#
+        .to_string(),
+        strict: false,
+        parameters: JsonSchema::Object {
+            properties,
+            required: Some(vec!["plan".to_string()]),
+            additional_properties: Some(false.into()),
+        },
+    })
+});
+
+#[async_trait]
+impl ToolHandler for PlanHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation {
+            session,
+            turn,
+            call_id,
+            payload,
+            ..
+        } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "update_plan handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let content =
+            handle_update_plan(session.as_ref(), turn.as_ref(), arguments, call_id).await?;
+
+        Ok(ToolOutput::Function {
+            content,
+            content_items: None,
+            success: Some(true),
+        })
+    }
+}
+
+/// This function doesn't do anything useful. However, it gives the model a structured way to record its plan that clients can read and render.
+/// So it's the _inputs_ to this function that are useful to clients, not the outputs and neither are actually useful for the model other
+/// than forcing it to come up and document a plan (TBD how that affects performance).
+pub(crate) async fn handle_update_plan(
+    session: &Session,
+    turn_context: &TurnContext,
+    arguments: String,
+    _call_id: String,
+) -> Result<String, FunctionCallError> {
+    let args = parse_update_plan_arguments(&arguments)?;
+    session
+        .send_event(turn_context, EventMsg::PlanUpdate(args))
+        .await;
+    Ok("Plan updated".to_string())
+}
+
+fn parse_update_plan_arguments(arguments: &str) -> Result<UpdatePlanArgs, FunctionCallError> {
+    serde_json::from_str::<UpdatePlanArgs>(arguments).map_err(|e| {
+        FunctionCallError::RespondToModel(format!("failed to parse function arguments: {e}"))
+    })
+}

llmx-rs/core/src/tools/handlers/read_file.rs

@@ -0,0 +1,999 @@
+use std::collections::VecDeque;
+use std::path::PathBuf;
+
+use async_trait::async_trait;
+use llmx_utils_string::take_bytes_at_char_boundary;
+use serde::Deserialize;
+
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+
+pub struct ReadFileHandler;
+
+const MAX_LINE_LENGTH: usize = 500;
+const TAB_WIDTH: usize = 4;
+
+// TODO(jif) add support for block comments
+const COMMENT_PREFIXES: &[&str] = &["#", "//", "--"];
+
+/// JSON arguments accepted by the `read_file` tool handler.
+#[derive(Deserialize)]
+struct ReadFileArgs {
+    /// Absolute path to the file that will be read.
+    file_path: String,
+    /// 1-indexed line number to start reading from; defaults to 1.
+    #[serde(default = "defaults::offset")]
+    offset: usize,
+    /// Maximum number of lines to return; defaults to 2000.
+    #[serde(default = "defaults::limit")]
+    limit: usize,
+    /// Determines whether the handler reads a simple slice or indentation-aware block.
+    #[serde(default)]
+    mode: ReadMode,
+    /// Optional indentation configuration used when `mode` is `Indentation`.
+    #[serde(default)]
+    indentation: Option<IndentationArgs>,
+}
+
+#[derive(Deserialize)]
+#[serde(rename_all = "snake_case")]
+enum ReadMode {
+    Slice,
+    Indentation,
+}
+/// Additional configuration for indentation-aware reads.
+#[derive(Deserialize, Clone)]
+struct IndentationArgs {
+    /// Optional explicit anchor line; defaults to `offset` when omitted.
+    #[serde(default)]
+    anchor_line: Option<usize>,
+    /// Maximum indentation depth to collect; `0` means unlimited.
+    #[serde(default = "defaults::max_levels")]
+    max_levels: usize,
+    /// Whether to include sibling blocks at the same indentation level.
+    #[serde(default = "defaults::include_siblings")]
+    include_siblings: bool,
+    /// Whether to include header lines above the anchor block. This made on a best effort basis.
+    #[serde(default = "defaults::include_header")]
+    include_header: bool,
+    /// Optional hard cap on returned lines; defaults to the global `limit`.
+    #[serde(default)]
+    max_lines: Option<usize>,
+}
+
+#[derive(Clone, Debug)]
+struct LineRecord {
+    number: usize,
+    raw: String,
+    display: String,
+    indent: usize,
+}
+
+impl LineRecord {
+    fn trimmed(&self) -> &str {
+        self.raw.trim_start()
+    }
+
+    fn is_blank(&self) -> bool {
+        self.trimmed().is_empty()
+    }
+
+    fn is_comment(&self) -> bool {
+        COMMENT_PREFIXES
+            .iter()
+            .any(|prefix| self.raw.trim().starts_with(prefix))
+    }
+}
+
+#[async_trait]
+impl ToolHandler for ReadFileHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation { payload, .. } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "read_file handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let args: ReadFileArgs = serde_json::from_str(&arguments).map_err(|err| {
+            FunctionCallError::RespondToModel(format!(
+                "failed to parse function arguments: {err:?}"
+            ))
+        })?;
+
+        let ReadFileArgs {
+            file_path,
+            offset,
+            limit,
+            mode,
+            indentation,
+        } = args;
+
+        if offset == 0 {
+            return Err(FunctionCallError::RespondToModel(
+                "offset must be a 1-indexed line number".to_string(),
+            ));
+        }
+
+        if limit == 0 {
+            return Err(FunctionCallError::RespondToModel(
+                "limit must be greater than zero".to_string(),
+            ));
+        }
+
+        let path = PathBuf::from(&file_path);
+        if !path.is_absolute() {
+            return Err(FunctionCallError::RespondToModel(
+                "file_path must be an absolute path".to_string(),
+            ));
+        }
+
+        let collected = match mode {
+            ReadMode::Slice => slice::read(&path, offset, limit).await?,
+            ReadMode::Indentation => {
+                let indentation = indentation.unwrap_or_default();
+                indentation::read_block(&path, offset, limit, indentation).await?
+            }
+        };
+        Ok(ToolOutput::Function {
+            content: collected.join("\n"),
+            content_items: None,
+            success: Some(true),
+        })
+    }
+}
+
+mod slice {
+    use crate::function_tool::FunctionCallError;
+    use crate::tools::handlers::read_file::format_line;
+    use std::path::Path;
+    use tokio::fs::File;
+    use tokio::io::AsyncBufReadExt;
+    use tokio::io::BufReader;
+
+    pub async fn read(
+        path: &Path,
+        offset: usize,
+        limit: usize,
+    ) -> Result<Vec<String>, FunctionCallError> {
+        let file = File::open(path).await.map_err(|err| {
+            FunctionCallError::RespondToModel(format!("failed to read file: {err}"))
+        })?;
+
+        let mut reader = BufReader::new(file);
+        let mut collected = Vec::new();
+        let mut seen = 0usize;
+        let mut buffer = Vec::new();
+
+        loop {
+            buffer.clear();
+            let bytes_read = reader.read_until(b'\n', &mut buffer).await.map_err(|err| {
+                FunctionCallError::RespondToModel(format!("failed to read file: {err}"))
+            })?;
+
+            if bytes_read == 0 {
+                break;
+            }
+
+            if buffer.last() == Some(&b'\n') {
+                buffer.pop();
+                if buffer.last() == Some(&b'\r') {
+                    buffer.pop();
+                }
+            }
+
+            seen += 1;
+
+            if seen < offset {
+                continue;
+            }
+
+            if collected.len() == limit {
+                break;
+            }
+
+            let formatted = format_line(&buffer);
+            collected.push(format!("L{seen}: {formatted}"));
+
+            if collected.len() == limit {
+                break;
+            }
+        }
+
+        if seen < offset {
+            return Err(FunctionCallError::RespondToModel(
+                "offset exceeds file length".to_string(),
+            ));
+        }
+
+        Ok(collected)
+    }
+}
+
+mod indentation {
+    use crate::function_tool::FunctionCallError;
+    use crate::tools::handlers::read_file::IndentationArgs;
+    use crate::tools::handlers::read_file::LineRecord;
+    use crate::tools::handlers::read_file::TAB_WIDTH;
+    use crate::tools::handlers::read_file::format_line;
+    use crate::tools::handlers::read_file::trim_empty_lines;
+    use std::collections::VecDeque;
+    use std::path::Path;
+    use tokio::fs::File;
+    use tokio::io::AsyncBufReadExt;
+    use tokio::io::BufReader;
+
+    pub async fn read_block(
+        path: &Path,
+        offset: usize,
+        limit: usize,
+        options: IndentationArgs,
+    ) -> Result<Vec<String>, FunctionCallError> {
+        let anchor_line = options.anchor_line.unwrap_or(offset);
+        if anchor_line == 0 {
+            return Err(FunctionCallError::RespondToModel(
+                "anchor_line must be a 1-indexed line number".to_string(),
+            ));
+        }
+
+        let guard_limit = options.max_lines.unwrap_or(limit);
+        if guard_limit == 0 {
+            return Err(FunctionCallError::RespondToModel(
+                "max_lines must be greater than zero".to_string(),
+            ));
+        }
+
+        let collected = collect_file_lines(path).await?;
+        if collected.is_empty() || anchor_line > collected.len() {
+            return Err(FunctionCallError::RespondToModel(
+                "anchor_line exceeds file length".to_string(),
+            ));
+        }
+
+        let anchor_index = anchor_line - 1;
+        let effective_indents = compute_effective_indents(&collected);
+        let anchor_indent = effective_indents[anchor_index];
+
+        // Compute the min indent
+        let min_indent = if options.max_levels == 0 {
+            0
+        } else {
+            anchor_indent.saturating_sub(options.max_levels * TAB_WIDTH)
+        };
+
+        // Cap requested lines by guard_limit and file length
+        let final_limit = limit.min(guard_limit).min(collected.len());
+
+        if final_limit == 1 {
+            return Ok(vec![format!(
+                "L{}: {}",
+                collected[anchor_index].number, collected[anchor_index].display
+            )]);
+        }
+
+        // Cursors
+        let mut i: isize = anchor_index as isize - 1; // up (inclusive)
+        let mut j: usize = anchor_index + 1; // down (inclusive)
+        let mut i_counter_min_indent = 0;
+        let mut j_counter_min_indent = 0;
+
+        let mut out = VecDeque::with_capacity(limit);
+        out.push_back(&collected[anchor_index]);
+
+        while out.len() < final_limit {
+            let mut progressed = 0;
+
+            // Up.
+            if i >= 0 {
+                let iu = i as usize;
+                if effective_indents[iu] >= min_indent {
+                    out.push_front(&collected[iu]);
+                    progressed += 1;
+                    i -= 1;
+
+                    // We do not include the siblings (not applied to comments).
+                    if effective_indents[iu] == min_indent && !options.include_siblings {
+                        let allow_header_comment =
+                            options.include_header && collected[iu].is_comment();
+                        let can_take_line = allow_header_comment || i_counter_min_indent == 0;
+
+                        if can_take_line {
+                            i_counter_min_indent += 1;
+                        } else {
+                            // This line shouldn't have been taken.
+                            out.pop_front();
+                            progressed -= 1;
+                            i = -1; // consider using Option<usize> or a control flag instead of a sentinel
+                        }
+                    }
+
+                    // Short-cut.
+                    if out.len() >= final_limit {
+                        break;
+                    }
+                } else {
+                    // Stop moving up.
+                    i = -1;
+                }
+            }
+
+            // Down.
+            if j < collected.len() {
+                let ju = j;
+                if effective_indents[ju] >= min_indent {
+                    out.push_back(&collected[ju]);
+                    progressed += 1;
+                    j += 1;
+
+                    // We do not include the siblings (applied to comments).
+                    if effective_indents[ju] == min_indent && !options.include_siblings {
+                        if j_counter_min_indent > 0 {
+                            // This line shouldn't have been taken.
+                            out.pop_back();
+                            progressed -= 1;
+                            j = collected.len();
+                        }
+                        j_counter_min_indent += 1;
+                    }
+                } else {
+                    // Stop moving down.
+                    j = collected.len();
+                }
+            }
+
+            if progressed == 0 {
+                break;
+            }
+        }
+
+        // Trim empty lines
+        trim_empty_lines(&mut out);
+
+        Ok(out
+            .into_iter()
+            .map(|record| format!("L{}: {}", record.number, record.display))
+            .collect())
+    }
+
+    async fn collect_file_lines(path: &Path) -> Result<Vec<LineRecord>, FunctionCallError> {
+        let file = File::open(path).await.map_err(|err| {
+            FunctionCallError::RespondToModel(format!("failed to read file: {err}"))
+        })?;
+
+        let mut reader = BufReader::new(file);
+        let mut buffer = Vec::new();
+        let mut lines = Vec::new();
+        let mut number = 0usize;
+
+        loop {
+            buffer.clear();
+            let bytes_read = reader.read_until(b'\n', &mut buffer).await.map_err(|err| {
+                FunctionCallError::RespondToModel(format!("failed to read file: {err}"))
+            })?;
+
+            if bytes_read == 0 {
+                break;
+            }
+
+            if buffer.last() == Some(&b'\n') {
+                buffer.pop();
+                if buffer.last() == Some(&b'\r') {
+                    buffer.pop();
+                }
+            }
+
+            number += 1;
+            let raw = String::from_utf8_lossy(&buffer).into_owned();
+            let indent = measure_indent(&raw);
+            let display = format_line(&buffer);
+            lines.push(LineRecord {
+                number,
+                raw,
+                display,
+                indent,
+            });
+        }
+
+        Ok(lines)
+    }
+
+    fn compute_effective_indents(records: &[LineRecord]) -> Vec<usize> {
+        let mut effective = Vec::with_capacity(records.len());
+        let mut previous_indent = 0usize;
+        for record in records {
+            if record.is_blank() {
+                effective.push(previous_indent);
+            } else {
+                previous_indent = record.indent;
+                effective.push(previous_indent);
+            }
+        }
+        effective
+    }
+
+    fn measure_indent(line: &str) -> usize {
+        line.chars()
+            .take_while(|c| matches!(c, ' ' | '\t'))
+            .map(|c| if c == '\t' { TAB_WIDTH } else { 1 })
+            .sum()
+    }
+}
+
+fn format_line(bytes: &[u8]) -> String {
+    let decoded = String::from_utf8_lossy(bytes);
+    if decoded.len() > MAX_LINE_LENGTH {
+        take_bytes_at_char_boundary(&decoded, MAX_LINE_LENGTH).to_string()
+    } else {
+        decoded.into_owned()
+    }
+}
+
+fn trim_empty_lines(out: &mut VecDeque<&LineRecord>) {
+    while matches!(out.front(), Some(line) if line.raw.trim().is_empty()) {
+        out.pop_front();
+    }
+    while matches!(out.back(), Some(line) if line.raw.trim().is_empty()) {
+        out.pop_back();
+    }
+}
+
+mod defaults {
+    use super::*;
+
+    impl Default for IndentationArgs {
+        fn default() -> Self {
+            Self {
+                anchor_line: None,
+                max_levels: max_levels(),
+                include_siblings: include_siblings(),
+                include_header: include_header(),
+                max_lines: None,
+            }
+        }
+    }
+
+    impl Default for ReadMode {
+        fn default() -> Self {
+            Self::Slice
+        }
+    }
+
+    pub fn offset() -> usize {
+        1
+    }
+
+    pub fn limit() -> usize {
+        2000
+    }
+
+    pub fn max_levels() -> usize {
+        0
+    }
+
+    pub fn include_siblings() -> bool {
+        false
+    }
+
+    pub fn include_header() -> bool {
+        true
+    }
+}
+
+#[cfg(test)]
+mod tests {
+    use super::indentation::read_block;
+    use super::slice::read;
+    use super::*;
+    use pretty_assertions::assert_eq;
+    use tempfile::NamedTempFile;
+
+    #[tokio::test]
+    async fn reads_requested_range() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(
+            temp,
+            "alpha
+beta
+gamma
+"
+        )?;
+
+        let lines = read(temp.path(), 2, 2).await?;
+        assert_eq!(lines, vec!["L2: beta".to_string(), "L3: gamma".to_string()]);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn errors_when_offset_exceeds_length() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        writeln!(temp, "only")?;
+
+        let err = read(temp.path(), 3, 1)
+            .await
+            .expect_err("offset exceeds length");
+        assert_eq!(
+            err,
+            FunctionCallError::RespondToModel("offset exceeds file length".to_string())
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn reads_non_utf8_lines() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        temp.as_file_mut().write_all(b"\xff\xfe\nplain\n")?;
+
+        let lines = read(temp.path(), 1, 2).await?;
+        let expected_first = format!("L1: {}{}", '\u{FFFD}', '\u{FFFD}');
+        assert_eq!(lines, vec![expected_first, "L2: plain".to_string()]);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn trims_crlf_endings() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(temp, "one\r\ntwo\r\n")?;
+
+        let lines = read(temp.path(), 1, 2).await?;
+        assert_eq!(lines, vec!["L1: one".to_string(), "L2: two".to_string()]);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn respects_limit_even_with_more_lines() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(
+            temp,
+            "first
+second
+third
+"
+        )?;
+
+        let lines = read(temp.path(), 1, 2).await?;
+        assert_eq!(
+            lines,
+            vec!["L1: first".to_string(), "L2: second".to_string()]
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn truncates_lines_longer_than_max_length() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        let long_line = "x".repeat(MAX_LINE_LENGTH + 50);
+        writeln!(temp, "{long_line}")?;
+
+        let lines = read(temp.path(), 1, 1).await?;
+        let expected = "x".repeat(MAX_LINE_LENGTH);
+        assert_eq!(lines, vec![format!("L1: {expected}")]);
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn indentation_mode_captures_block() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(
+            temp,
+            "fn outer() {{
+    if cond {{
+        inner();
+    }}
+    tail();
+}}
+"
+        )?;
+
+        let options = IndentationArgs {
+            anchor_line: Some(3),
+            include_siblings: false,
+            max_levels: 1,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 3, 10, options).await?;
+
+        assert_eq!(
+            lines,
+            vec![
+                "L2:     if cond {".to_string(),
+                "L3:         inner();".to_string(),
+                "L4:     }".to_string()
+            ]
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn indentation_mode_expands_parents() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(
+            temp,
+            "mod root {{
+    fn outer() {{
+        if cond {{
+            inner();
+        }}
+    }}
+}}
+"
+        )?;
+
+        let mut options = IndentationArgs {
+            anchor_line: Some(4),
+            max_levels: 2,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 4, 50, options.clone()).await?;
+        assert_eq!(
+            lines,
+            vec![
+                "L2:     fn outer() {".to_string(),
+                "L3:         if cond {".to_string(),
+                "L4:             inner();".to_string(),
+                "L5:         }".to_string(),
+                "L6:     }".to_string(),
+            ]
+        );
+
+        options.max_levels = 3;
+        let expanded = read_block(temp.path(), 4, 50, options).await?;
+        assert_eq!(
+            expanded,
+            vec![
+                "L1: mod root {".to_string(),
+                "L2:     fn outer() {".to_string(),
+                "L3:         if cond {".to_string(),
+                "L4:             inner();".to_string(),
+                "L5:         }".to_string(),
+                "L6:     }".to_string(),
+                "L7: }".to_string(),
+            ]
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn indentation_mode_respects_sibling_flag() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(
+            temp,
+            "fn wrapper() {{
+    if first {{
+        do_first();
+    }}
+    if second {{
+        do_second();
+    }}
+}}
+"
+        )?;
+
+        let mut options = IndentationArgs {
+            anchor_line: Some(3),
+            include_siblings: false,
+            max_levels: 1,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 3, 50, options.clone()).await?;
+        assert_eq!(
+            lines,
+            vec![
+                "L2:     if first {".to_string(),
+                "L3:         do_first();".to_string(),
+                "L4:     }".to_string(),
+            ]
+        );
+
+        options.include_siblings = true;
+        let with_siblings = read_block(temp.path(), 3, 50, options).await?;
+        assert_eq!(
+            with_siblings,
+            vec![
+                "L2:     if first {".to_string(),
+                "L3:         do_first();".to_string(),
+                "L4:     }".to_string(),
+                "L5:     if second {".to_string(),
+                "L6:         do_second();".to_string(),
+                "L7:     }".to_string(),
+            ]
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn indentation_mode_handles_python_sample() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(
+            temp,
+            "class Foo:
+    def __init__(self, size):
+        self.size = size
+    def double(self, value):
+        if value is None:
+            return 0
+        result = value * self.size
+        return result
+class Bar:
+    def compute(self):
+        helper = Foo(2)
+        return helper.double(5)
+"
+        )?;
+
+        let options = IndentationArgs {
+            anchor_line: Some(7),
+            include_siblings: true,
+            max_levels: 1,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 1, 200, options).await?;
+        assert_eq!(
+            lines,
+            vec![
+                "L2:     def __init__(self, size):".to_string(),
+                "L3:         self.size = size".to_string(),
+                "L4:     def double(self, value):".to_string(),
+                "L5:         if value is None:".to_string(),
+                "L6:             return 0".to_string(),
+                "L7:         result = value * self.size".to_string(),
+                "L8:         return result".to_string(),
+            ]
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    #[ignore]
+    async fn indentation_mode_handles_javascript_sample() -> anyhow::Result<()> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(
+            temp,
+            "export function makeThing() {{
+    const cache = new Map();
+    function ensure(key) {{
+        if (!cache.has(key)) {{
+            cache.set(key, []);
+        }}
+        return cache.get(key);
+    }}
+    const handlers = {{
+        init() {{
+            console.log(\"init\");
+        }},
+        run() {{
+            if (Math.random() > 0.5) {{
+                return \"heads\";
+            }}
+            return \"tails\";
+        }},
+    }};
+    return {{ cache, handlers }};
+}}
+export function other() {{
+    return makeThing();
+}}
+"
+        )?;
+
+        let options = IndentationArgs {
+            anchor_line: Some(15),
+            max_levels: 1,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 15, 200, options).await?;
+        assert_eq!(
+            lines,
+            vec![
+                "L10:         init() {".to_string(),
+                "L11:             console.log(\"init\");".to_string(),
+                "L12:         },".to_string(),
+                "L13:         run() {".to_string(),
+                "L14:             if (Math.random() > 0.5) {".to_string(),
+                "L15:                 return \"heads\";".to_string(),
+                "L16:             }".to_string(),
+                "L17:             return \"tails\";".to_string(),
+                "L18:         },".to_string(),
+            ]
+        );
+        Ok(())
+    }
+
+    fn write_cpp_sample() -> anyhow::Result<NamedTempFile> {
+        let mut temp = NamedTempFile::new()?;
+        use std::io::Write as _;
+        write!(
+            temp,
+            "#include <vector>
+#include <string>
+
+namespace sample {{
+class Runner {{
+public:
+    void setup() {{
+        if (enabled_) {{
+            init();
+        }}
+    }}
+
+    // Run the code
+    int run() const {{
+        switch (mode_) {{
+            case Mode::Fast:
+                return fast();
+            case Mode::Slow:
+                return slow();
+            default:
+                return fallback();
+        }}
+    }}
+
+private:
+    bool enabled_ = false;
+    Mode mode_ = Mode::Fast;
+
+    int fast() const {{
+        return 1;
+    }}
+}};
+}}  // namespace sample
+"
+        )?;
+        Ok(temp)
+    }
+
+    #[tokio::test]
+    async fn indentation_mode_handles_cpp_sample_shallow() -> anyhow::Result<()> {
+        let temp = write_cpp_sample()?;
+
+        let options = IndentationArgs {
+            include_siblings: false,
+            anchor_line: Some(18),
+            max_levels: 1,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 18, 200, options).await?;
+        assert_eq!(
+            lines,
+            vec![
+                "L15:         switch (mode_) {".to_string(),
+                "L16:             case Mode::Fast:".to_string(),
+                "L17:                 return fast();".to_string(),
+                "L18:             case Mode::Slow:".to_string(),
+                "L19:                 return slow();".to_string(),
+                "L20:             default:".to_string(),
+                "L21:                 return fallback();".to_string(),
+                "L22:         }".to_string(),
+            ]
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn indentation_mode_handles_cpp_sample() -> anyhow::Result<()> {
+        let temp = write_cpp_sample()?;
+
+        let options = IndentationArgs {
+            include_siblings: false,
+            anchor_line: Some(18),
+            max_levels: 2,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 18, 200, options).await?;
+        assert_eq!(
+            lines,
+            vec![
+                "L13:     // Run the code".to_string(),
+                "L14:     int run() const {".to_string(),
+                "L15:         switch (mode_) {".to_string(),
+                "L16:             case Mode::Fast:".to_string(),
+                "L17:                 return fast();".to_string(),
+                "L18:             case Mode::Slow:".to_string(),
+                "L19:                 return slow();".to_string(),
+                "L20:             default:".to_string(),
+                "L21:                 return fallback();".to_string(),
+                "L22:         }".to_string(),
+                "L23:     }".to_string(),
+            ]
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn indentation_mode_handles_cpp_sample_no_headers() -> anyhow::Result<()> {
+        let temp = write_cpp_sample()?;
+
+        let options = IndentationArgs {
+            include_siblings: false,
+            include_header: false,
+            anchor_line: Some(18),
+            max_levels: 2,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 18, 200, options).await?;
+        assert_eq!(
+            lines,
+            vec![
+                "L14:     int run() const {".to_string(),
+                "L15:         switch (mode_) {".to_string(),
+                "L16:             case Mode::Fast:".to_string(),
+                "L17:                 return fast();".to_string(),
+                "L18:             case Mode::Slow:".to_string(),
+                "L19:                 return slow();".to_string(),
+                "L20:             default:".to_string(),
+                "L21:                 return fallback();".to_string(),
+                "L22:         }".to_string(),
+                "L23:     }".to_string(),
+            ]
+        );
+        Ok(())
+    }
+
+    #[tokio::test]
+    async fn indentation_mode_handles_cpp_sample_siblings() -> anyhow::Result<()> {
+        let temp = write_cpp_sample()?;
+
+        let options = IndentationArgs {
+            include_siblings: true,
+            include_header: false,
+            anchor_line: Some(18),
+            max_levels: 2,
+            ..Default::default()
+        };
+
+        let lines = read_block(temp.path(), 18, 200, options).await?;
+        assert_eq!(
+            lines,
+            vec![
+                "L7:     void setup() {".to_string(),
+                "L8:         if (enabled_) {".to_string(),
+                "L9:             init();".to_string(),
+                "L10:         }".to_string(),
+                "L11:     }".to_string(),
+                "L12: ".to_string(),
+                "L13:     // Run the code".to_string(),
+                "L14:     int run() const {".to_string(),
+                "L15:         switch (mode_) {".to_string(),
+                "L16:             case Mode::Fast:".to_string(),
+                "L17:                 return fast();".to_string(),
+                "L18:             case Mode::Slow:".to_string(),
+                "L19:                 return slow();".to_string(),
+                "L20:             default:".to_string(),
+                "L21:                 return fallback();".to_string(),
+                "L22:         }".to_string(),
+                "L23:     }".to_string(),
+            ]
+        );
+        Ok(())
+    }
+}

llmx-rs/core/src/tools/handlers/shell.rs

@@ -0,0 +1,242 @@
+use async_trait::async_trait;
+use llmx_protocol::models::ShellToolCallParams;
+use std::sync::Arc;
+
+use crate::apply_patch;
+use crate::apply_patch::InternalApplyPatchInvocation;
+use crate::apply_patch::convert_apply_patch_to_protocol;
+use crate::exec::ExecParams;
+use crate::exec_env::create_env;
+use crate::function_tool::FunctionCallError;
+use crate::llmx::TurnContext;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::events::ToolEmitter;
+use crate::tools::events::ToolEventCtx;
+use crate::tools::orchestrator::ToolOrchestrator;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+use crate::tools::runtimes::apply_patch::ApplyPatchRequest;
+use crate::tools::runtimes::apply_patch::ApplyPatchRuntime;
+use crate::tools::runtimes::shell::ShellRequest;
+use crate::tools::runtimes::shell::ShellRuntime;
+use crate::tools::sandboxing::ToolCtx;
+
+pub struct ShellHandler;
+
+impl ShellHandler {
+    fn to_exec_params(params: ShellToolCallParams, turn_context: &TurnContext) -> ExecParams {
+        ExecParams {
+            command: params.command,
+            cwd: turn_context.resolve_path(params.workdir.clone()),
+            timeout_ms: params.timeout_ms,
+            env: create_env(&turn_context.shell_environment_policy),
+            with_escalated_permissions: params.with_escalated_permissions,
+            justification: params.justification,
+            arg0: None,
+        }
+    }
+}
+
+#[async_trait]
+impl ToolHandler for ShellHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    fn matches_kind(&self, payload: &ToolPayload) -> bool {
+        matches!(
+            payload,
+            ToolPayload::Function { .. } | ToolPayload::LocalShell { .. }
+        )
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation {
+            session,
+            turn,
+            tracker,
+            call_id,
+            tool_name,
+            payload,
+        } = invocation;
+
+        match payload {
+            ToolPayload::Function { arguments } => {
+                let params: ShellToolCallParams =
+                    serde_json::from_str(&arguments).map_err(|e| {
+                        FunctionCallError::RespondToModel(format!(
+                            "failed to parse function arguments: {e:?}"
+                        ))
+                    })?;
+                let exec_params = Self::to_exec_params(params, turn.as_ref());
+                Self::run_exec_like(
+                    tool_name.as_str(),
+                    exec_params,
+                    session,
+                    turn,
+                    tracker,
+                    call_id,
+                    false,
+                )
+                .await
+            }
+            ToolPayload::LocalShell { params } => {
+                let exec_params = Self::to_exec_params(params, turn.as_ref());
+                Self::run_exec_like(
+                    tool_name.as_str(),
+                    exec_params,
+                    session,
+                    turn,
+                    tracker,
+                    call_id,
+                    true,
+                )
+                .await
+            }
+            _ => Err(FunctionCallError::RespondToModel(format!(
+                "unsupported payload for shell handler: {tool_name}"
+            ))),
+        }
+    }
+}
+
+impl ShellHandler {
+    async fn run_exec_like(
+        tool_name: &str,
+        exec_params: ExecParams,
+        session: Arc<crate::llmx::Session>,
+        turn: Arc<TurnContext>,
+        tracker: crate::tools::context::SharedTurnDiffTracker,
+        call_id: String,
+        is_user_shell_command: bool,
+    ) -> Result<ToolOutput, FunctionCallError> {
+        // Approval policy guard for explicit escalation in non-OnRequest modes.
+        if exec_params.with_escalated_permissions.unwrap_or(false)
+            && !matches!(
+                turn.approval_policy,
+                llmx_protocol::protocol::AskForApproval::OnRequest
+            )
+        {
+            return Err(FunctionCallError::RespondToModel(format!(
+                "approval policy is {policy:?}; reject command — you should not ask for escalated permissions if the approval policy is {policy:?}",
+                policy = turn.approval_policy
+            )));
+        }
+
+        // Intercept apply_patch if present.
+        match llmx_apply_patch::maybe_parse_apply_patch_verified(
+            &exec_params.command,
+            &exec_params.cwd,
+        ) {
+            llmx_apply_patch::MaybeApplyPatchVerified::Body(changes) => {
+                match apply_patch::apply_patch(session.as_ref(), turn.as_ref(), &call_id, changes)
+                    .await
+                {
+                    InternalApplyPatchInvocation::Output(item) => {
+                        // Programmatic apply_patch path; return its result.
+                        let content = item?;
+                        return Ok(ToolOutput::Function {
+                            content,
+                            content_items: None,
+                            success: Some(true),
+                        });
+                    }
+                    InternalApplyPatchInvocation::DelegateToExec(apply) => {
+                        let emitter = ToolEmitter::apply_patch(
+                            convert_apply_patch_to_protocol(&apply.action),
+                            !apply.user_explicitly_approved_this_action,
+                        );
+                        let event_ctx = ToolEventCtx::new(
+                            session.as_ref(),
+                            turn.as_ref(),
+                            &call_id,
+                            Some(&tracker),
+                        );
+                        emitter.begin(event_ctx).await;
+
+                        let req = ApplyPatchRequest {
+                            patch: apply.action.patch.clone(),
+                            cwd: apply.action.cwd.clone(),
+                            timeout_ms: exec_params.timeout_ms,
+                            user_explicitly_approved: apply.user_explicitly_approved_this_action,
+                            llmx_exe: turn.llmx_linux_sandbox_exe.clone(),
+                        };
+                        let mut orchestrator = ToolOrchestrator::new();
+                        let mut runtime = ApplyPatchRuntime::new();
+                        let tool_ctx = ToolCtx {
+                            session: session.as_ref(),
+                            turn: turn.as_ref(),
+                            call_id: call_id.clone(),
+                            tool_name: tool_name.to_string(),
+                        };
+                        let out = orchestrator
+                            .run(&mut runtime, &req, &tool_ctx, &turn, turn.approval_policy)
+                            .await;
+                        let event_ctx = ToolEventCtx::new(
+                            session.as_ref(),
+                            turn.as_ref(),
+                            &call_id,
+                            Some(&tracker),
+                        );
+                        let content = emitter.finish(event_ctx, out).await?;
+                        return Ok(ToolOutput::Function {
+                            content,
+                            content_items: None,
+                            success: Some(true),
+                        });
+                    }
+                }
+            }
+            llmx_apply_patch::MaybeApplyPatchVerified::CorrectnessError(parse_error) => {
+                return Err(FunctionCallError::RespondToModel(format!(
+                    "apply_patch verification failed: {parse_error}"
+                )));
+            }
+            llmx_apply_patch::MaybeApplyPatchVerified::ShellParseError(error) => {
+                tracing::trace!("Failed to parse shell command, {error:?}");
+                // Fall through to regular shell execution.
+            }
+            llmx_apply_patch::MaybeApplyPatchVerified::NotApplyPatch => {
+                // Fall through to regular shell execution.
+            }
+        }
+
+        // Regular shell execution path.
+        let emitter = ToolEmitter::shell(
+            exec_params.command.clone(),
+            exec_params.cwd.clone(),
+            is_user_shell_command,
+        );
+        let event_ctx = ToolEventCtx::new(session.as_ref(), turn.as_ref(), &call_id, None);
+        emitter.begin(event_ctx).await;
+
+        let req = ShellRequest {
+            command: exec_params.command.clone(),
+            cwd: exec_params.cwd.clone(),
+            timeout_ms: exec_params.timeout_ms,
+            env: exec_params.env.clone(),
+            with_escalated_permissions: exec_params.with_escalated_permissions,
+            justification: exec_params.justification.clone(),
+        };
+        let mut orchestrator = ToolOrchestrator::new();
+        let mut runtime = ShellRuntime::new();
+        let tool_ctx = ToolCtx {
+            session: session.as_ref(),
+            turn: turn.as_ref(),
+            call_id: call_id.clone(),
+            tool_name: tool_name.to_string(),
+        };
+        let out = orchestrator
+            .run(&mut runtime, &req, &tool_ctx, &turn, turn.approval_policy)
+            .await;
+        let event_ctx = ToolEventCtx::new(session.as_ref(), turn.as_ref(), &call_id, None);
+        let content = emitter.finish(event_ctx, out).await?;
+        Ok(ToolOutput::Function {
+            content,
+            content_items: None,
+            success: Some(true),
+        })
+    }
+}

llmx-rs/core/src/tools/handlers/test_sync.rs

@@ -0,0 +1,159 @@
+use std::collections::HashMap;
+use std::collections::hash_map::Entry;
+use std::sync::Arc;
+use std::sync::OnceLock;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use serde::Deserialize;
+use tokio::sync::Barrier;
+use tokio::time::sleep;
+
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+
+pub struct TestSyncHandler;
+
+const DEFAULT_TIMEOUT_MS: u64 = 1_000;
+
+static BARRIERS: OnceLock<tokio::sync::Mutex<HashMap<String, BarrierState>>> = OnceLock::new();
+
+struct BarrierState {
+    barrier: Arc<Barrier>,
+    participants: usize,
+}
+
+#[derive(Debug, Deserialize)]
+struct BarrierArgs {
+    id: String,
+    participants: usize,
+    #[serde(default = "default_timeout_ms")]
+    timeout_ms: u64,
+}
+
+#[derive(Debug, Deserialize)]
+struct TestSyncArgs {
+    #[serde(default)]
+    sleep_before_ms: Option<u64>,
+    #[serde(default)]
+    sleep_after_ms: Option<u64>,
+    #[serde(default)]
+    barrier: Option<BarrierArgs>,
+}
+
+fn default_timeout_ms() -> u64 {
+    DEFAULT_TIMEOUT_MS
+}
+
+fn barrier_map() -> &'static tokio::sync::Mutex<HashMap<String, BarrierState>> {
+    BARRIERS.get_or_init(|| tokio::sync::Mutex::new(HashMap::new()))
+}
+
+#[async_trait]
+impl ToolHandler for TestSyncHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation { payload, .. } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "test_sync_tool handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let args: TestSyncArgs = serde_json::from_str(&arguments).map_err(|err| {
+            FunctionCallError::RespondToModel(format!(
+                "failed to parse function arguments: {err:?}"
+            ))
+        })?;
+
+        if let Some(delay) = args.sleep_before_ms
+            && delay > 0
+        {
+            sleep(Duration::from_millis(delay)).await;
+        }
+
+        if let Some(barrier) = args.barrier {
+            wait_on_barrier(barrier).await?;
+        }
+
+        if let Some(delay) = args.sleep_after_ms
+            && delay > 0
+        {
+            sleep(Duration::from_millis(delay)).await;
+        }
+
+        Ok(ToolOutput::Function {
+            content: "ok".to_string(),
+            content_items: None,
+            success: Some(true),
+        })
+    }
+}
+
+async fn wait_on_barrier(args: BarrierArgs) -> Result<(), FunctionCallError> {
+    if args.participants == 0 {
+        return Err(FunctionCallError::RespondToModel(
+            "barrier participants must be greater than zero".to_string(),
+        ));
+    }
+
+    if args.timeout_ms == 0 {
+        return Err(FunctionCallError::RespondToModel(
+            "barrier timeout must be greater than zero".to_string(),
+        ));
+    }
+
+    let barrier_id = args.id.clone();
+    let barrier = {
+        let mut map = barrier_map().lock().await;
+        match map.entry(barrier_id.clone()) {
+            Entry::Occupied(entry) => {
+                let state = entry.get();
+                if state.participants != args.participants {
+                    let existing = state.participants;
+                    return Err(FunctionCallError::RespondToModel(format!(
+                        "barrier {barrier_id} already registered with {existing} participants"
+                    )));
+                }
+                state.barrier.clone()
+            }
+            Entry::Vacant(entry) => {
+                let barrier = Arc::new(Barrier::new(args.participants));
+                entry.insert(BarrierState {
+                    barrier: barrier.clone(),
+                    participants: args.participants,
+                });
+                barrier
+            }
+        }
+    };
+
+    let timeout = Duration::from_millis(args.timeout_ms);
+    let wait_result = tokio::time::timeout(timeout, barrier.wait())
+        .await
+        .map_err(|_| {
+            FunctionCallError::RespondToModel("test_sync_tool barrier wait timed out".to_string())
+        })?;
+
+    if wait_result.is_leader() {
+        let mut map = barrier_map().lock().await;
+        if let Some(state) = map.get(&barrier_id)
+            && Arc::ptr_eq(&state.barrier, &barrier)
+        {
+            map.remove(&barrier_id);
+        }
+    }
+
+    Ok(())
+}

llmx-rs/core/src/tools/handlers/tool_apply_patch.lark

@@ -0,0 +1,19 @@
+start: begin_patch hunk+ end_patch
+begin_patch: "*** Begin Patch" LF
+end_patch: "*** End Patch" LF?
+
+hunk: add_hunk | delete_hunk | update_hunk
+add_hunk: "*** Add File: " filename LF add_line+
+delete_hunk: "*** Delete File: " filename LF
+update_hunk: "*** Update File: " filename LF change_move? change?
+
+filename: /(.+)/
+add_line: "+" /(.*)/ LF -> line
+
+change_move: "*** Move to: " filename LF
+change: (change_context | change_line)+ eof_line?
+change_context: ("@@" | "@@ " /(.+)/) LF
+change_line: ("+" | "-" | " ") /(.*)/ LF
+eof_line: "*** End of File" LF
+
+%import common.LF

llmx-rs/core/src/tools/handlers/unified_exec.rs

@@ -0,0 +1,209 @@
+use std::path::PathBuf;
+
+use async_trait::async_trait;
+use serde::Deserialize;
+
+use crate::function_tool::FunctionCallError;
+use crate::protocol::EventMsg;
+use crate::protocol::ExecCommandOutputDeltaEvent;
+use crate::protocol::ExecOutputStream;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::events::ToolEmitter;
+use crate::tools::events::ToolEventCtx;
+use crate::tools::events::ToolEventStage;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+use crate::unified_exec::ExecCommandRequest;
+use crate::unified_exec::UnifiedExecContext;
+use crate::unified_exec::UnifiedExecResponse;
+use crate::unified_exec::UnifiedExecSessionManager;
+use crate::unified_exec::WriteStdinRequest;
+
+pub struct UnifiedExecHandler;
+
+#[derive(Debug, Deserialize)]
+struct ExecCommandArgs {
+    cmd: String,
+    #[serde(default)]
+    workdir: Option<String>,
+    #[serde(default = "default_shell")]
+    shell: String,
+    #[serde(default = "default_login")]
+    login: bool,
+    #[serde(default)]
+    yield_time_ms: Option<u64>,
+    #[serde(default)]
+    max_output_tokens: Option<usize>,
+}
+
+#[derive(Debug, Deserialize)]
+struct WriteStdinArgs {
+    session_id: i32,
+    #[serde(default)]
+    chars: String,
+    #[serde(default)]
+    yield_time_ms: Option<u64>,
+    #[serde(default)]
+    max_output_tokens: Option<usize>,
+}
+
+fn default_shell() -> String {
+    "/bin/bash".to_string()
+}
+
+fn default_login() -> bool {
+    true
+}
+
+#[async_trait]
+impl ToolHandler for UnifiedExecHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    fn matches_kind(&self, payload: &ToolPayload) -> bool {
+        matches!(
+            payload,
+            ToolPayload::Function { .. } | ToolPayload::UnifiedExec { .. }
+        )
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation {
+            session,
+            turn,
+            call_id,
+            tool_name,
+            payload,
+            ..
+        } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            ToolPayload::UnifiedExec { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "unified_exec handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let manager: &UnifiedExecSessionManager = &session.services.unified_exec_manager;
+        let context = UnifiedExecContext::new(session.clone(), turn.clone(), call_id.clone());
+
+        let response = match tool_name.as_str() {
+            "exec_command" => {
+                let args: ExecCommandArgs = serde_json::from_str(&arguments).map_err(|err| {
+                    FunctionCallError::RespondToModel(format!(
+                        "failed to parse exec_command arguments: {err:?}"
+                    ))
+                })?;
+                let workdir = args
+                    .workdir
+                    .as_deref()
+                    .filter(|value| !value.is_empty())
+                    .map(PathBuf::from);
+                let cwd = workdir.clone().unwrap_or_else(|| context.turn.cwd.clone());
+
+                let event_ctx = ToolEventCtx::new(
+                    context.session.as_ref(),
+                    context.turn.as_ref(),
+                    &context.call_id,
+                    None,
+                );
+                let emitter = ToolEmitter::unified_exec(args.cmd.clone(), cwd.clone(), true);
+                emitter.emit(event_ctx, ToolEventStage::Begin).await;
+
+                manager
+                    .exec_command(
+                        ExecCommandRequest {
+                            command: &args.cmd,
+                            shell: &args.shell,
+                            login: args.login,
+                            yield_time_ms: args.yield_time_ms,
+                            max_output_tokens: args.max_output_tokens,
+                            workdir,
+                        },
+                        &context,
+                    )
+                    .await
+                    .map_err(|err| {
+                        FunctionCallError::RespondToModel(format!("exec_command failed: {err:?}"))
+                    })?
+            }
+            "write_stdin" => {
+                let args: WriteStdinArgs = serde_json::from_str(&arguments).map_err(|err| {
+                    FunctionCallError::RespondToModel(format!(
+                        "failed to parse write_stdin arguments: {err:?}"
+                    ))
+                })?;
+                manager
+                    .write_stdin(WriteStdinRequest {
+                        session_id: args.session_id,
+                        input: &args.chars,
+                        yield_time_ms: args.yield_time_ms,
+                        max_output_tokens: args.max_output_tokens,
+                    })
+                    .await
+                    .map_err(|err| {
+                        FunctionCallError::RespondToModel(format!("write_stdin failed: {err:?}"))
+                    })?
+            }
+            other => {
+                return Err(FunctionCallError::RespondToModel(format!(
+                    "unsupported unified exec function {other}"
+                )));
+            }
+        };
+
+        // Emit a delta event with the chunk of output we just produced, if any.
+        if !response.output.is_empty() {
+            let delta = ExecCommandOutputDeltaEvent {
+                call_id: response.event_call_id.clone(),
+                stream: ExecOutputStream::Stdout,
+                chunk: response.output.as_bytes().to_vec(),
+            };
+            session
+                .send_event(turn.as_ref(), EventMsg::ExecCommandOutputDelta(delta))
+                .await;
+        }
+
+        let content = format_response(&response);
+
+        Ok(ToolOutput::Function {
+            content,
+            content_items: None,
+            success: Some(true),
+        })
+    }
+}
+
+fn format_response(response: &UnifiedExecResponse) -> String {
+    let mut sections = Vec::new();
+
+    if !response.chunk_id.is_empty() {
+        sections.push(format!("Chunk ID: {}", response.chunk_id));
+    }
+
+    let wall_time_seconds = response.wall_time.as_secs_f64();
+    sections.push(format!("Wall time: {wall_time_seconds:.4} seconds"));
+
+    if let Some(exit_code) = response.exit_code {
+        sections.push(format!("Process exited with code {exit_code}"));
+    }
+
+    if let Some(session_id) = response.session_id {
+        sections.push(format!("Process running with session ID {session_id}"));
+    }
+
+    if let Some(original_token_count) = response.original_token_count {
+        sections.push(format!("Original token count: {original_token_count}"));
+    }
+
+    sections.push("Output:".to_string());
+    sections.push(response.output.clone());
+
+    sections.join("\n")
+}

llmx-rs/core/src/tools/handlers/view_image.rs

@@ -0,0 +1,92 @@
+use async_trait::async_trait;
+use serde::Deserialize;
+use tokio::fs;
+
+use crate::function_tool::FunctionCallError;
+use crate::protocol::EventMsg;
+use crate::protocol::ViewImageToolCallEvent;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ToolHandler;
+use crate::tools::registry::ToolKind;
+use llmx_protocol::user_input::UserInput;
+
+pub struct ViewImageHandler;
+
+#[derive(Deserialize)]
+struct ViewImageArgs {
+    path: String,
+}
+
+#[async_trait]
+impl ToolHandler for ViewImageHandler {
+    fn kind(&self) -> ToolKind {
+        ToolKind::Function
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
+        let ToolInvocation {
+            session,
+            turn,
+            payload,
+            call_id,
+            ..
+        } = invocation;
+
+        let arguments = match payload {
+            ToolPayload::Function { arguments } => arguments,
+            _ => {
+                return Err(FunctionCallError::RespondToModel(
+                    "view_image handler received unsupported payload".to_string(),
+                ));
+            }
+        };
+
+        let args: ViewImageArgs = serde_json::from_str(&arguments).map_err(|e| {
+            FunctionCallError::RespondToModel(format!("failed to parse function arguments: {e:?}"))
+        })?;
+
+        let abs_path = turn.resolve_path(Some(args.path));
+
+        let metadata = fs::metadata(&abs_path).await.map_err(|error| {
+            FunctionCallError::RespondToModel(format!(
+                "unable to locate image at `{}`: {error}",
+                abs_path.display()
+            ))
+        })?;
+
+        if !metadata.is_file() {
+            return Err(FunctionCallError::RespondToModel(format!(
+                "image path `{}` is not a file",
+                abs_path.display()
+            )));
+        }
+        let event_path = abs_path.clone();
+
+        session
+            .inject_input(vec![UserInput::LocalImage { path: abs_path }])
+            .await
+            .map_err(|_| {
+                FunctionCallError::RespondToModel(
+                    "unable to attach image (no active task)".to_string(),
+                )
+            })?;
+
+        session
+            .send_event(
+                turn.as_ref(),
+                EventMsg::ViewImageToolCall(ViewImageToolCallEvent {
+                    call_id,
+                    path: event_path,
+                }),
+            )
+            .await;
+
+        Ok(ToolOutput::Function {
+            content: "attached local image path".to_string(),
+            content_items: None,
+            success: Some(true),
+        })
+    }
+}

llmx-rs/core/src/tools/mod.rs

@@ -0,0 +1,79 @@
+pub mod context;
+pub mod events;
+pub(crate) mod handlers;
+pub mod orchestrator;
+pub mod parallel;
+pub mod registry;
+pub mod router;
+pub mod runtimes;
+pub mod sandboxing;
+pub mod spec;
+
+use crate::context_manager::format_output_for_model_body;
+use crate::exec::ExecToolCallOutput;
+pub use router::ToolRouter;
+use serde::Serialize;
+
+// Telemetry preview limits: keep log events smaller than model budgets.
+pub(crate) const TELEMETRY_PREVIEW_MAX_BYTES: usize = 2 * 1024; // 2 KiB
+pub(crate) const TELEMETRY_PREVIEW_MAX_LINES: usize = 64; // lines
+pub(crate) const TELEMETRY_PREVIEW_TRUNCATION_NOTICE: &str =
+    "[... telemetry preview truncated ...]";
+
+/// Format the combined exec output for sending back to the model.
+/// Includes exit code and duration metadata; truncates large bodies safely.
+pub fn format_exec_output_for_model(exec_output: &ExecToolCallOutput) -> String {
+    let ExecToolCallOutput {
+        exit_code,
+        duration,
+        ..
+    } = exec_output;
+
+    #[derive(Serialize)]
+    struct ExecMetadata {
+        exit_code: i32,
+        duration_seconds: f32,
+    }
+
+    #[derive(Serialize)]
+    struct ExecOutput<'a> {
+        output: &'a str,
+        metadata: ExecMetadata,
+    }
+
+    // round to 1 decimal place
+    let duration_seconds = ((duration.as_secs_f32()) * 10.0).round() / 10.0;
+
+    let formatted_output = format_exec_output_str(exec_output);
+
+    let payload = ExecOutput {
+        output: &formatted_output,
+        metadata: ExecMetadata {
+            exit_code: *exit_code,
+            duration_seconds,
+        },
+    };
+
+    #[expect(clippy::expect_used)]
+    serde_json::to_string(&payload).expect("serialize ExecOutput")
+}
+
+pub fn format_exec_output_str(exec_output: &ExecToolCallOutput) -> String {
+    let ExecToolCallOutput {
+        aggregated_output, ..
+    } = exec_output;
+
+    let content = aggregated_output.text.as_str();
+
+    let body = if exec_output.timed_out {
+        format!(
+            "command timed out after {} milliseconds\n{content}",
+            exec_output.duration.as_millis()
+        )
+    } else {
+        content.to_string()
+    };
+
+    // Truncate for model consumption before serialization.
+    format_output_for_model_body(&body)
+}

llmx-rs/core/src/tools/orchestrator.rs

@@ -0,0 +1,186 @@
+/*
+Module: orchestrator
+
+Central place for approvals + sandbox selection + retry semantics. Drives a
+simple sequence for any ToolRuntime: approval → select sandbox → attempt →
+retry without sandbox on denial (no re‑approval thanks to caching).
+*/
+use crate::error::LlmxErr;
+use crate::error::SandboxErr;
+use crate::error::get_error_message_ui;
+use crate::exec::ExecToolCallOutput;
+use crate::sandboxing::SandboxManager;
+use crate::tools::sandboxing::ApprovalCtx;
+use crate::tools::sandboxing::ProvidesSandboxRetryData;
+use crate::tools::sandboxing::SandboxAttempt;
+use crate::tools::sandboxing::ToolCtx;
+use crate::tools::sandboxing::ToolError;
+use crate::tools::sandboxing::ToolRuntime;
+use llmx_protocol::protocol::AskForApproval;
+use llmx_protocol::protocol::ReviewDecision;
+
+pub(crate) struct ToolOrchestrator {
+    sandbox: SandboxManager,
+}
+
+impl ToolOrchestrator {
+    pub fn new() -> Self {
+        Self {
+            sandbox: SandboxManager::new(),
+        }
+    }
+
+    pub async fn run<Rq, Out, T>(
+        &mut self,
+        tool: &mut T,
+        req: &Rq,
+        tool_ctx: &ToolCtx<'_>,
+        turn_ctx: &crate::llmx::TurnContext,
+        approval_policy: AskForApproval,
+    ) -> Result<Out, ToolError>
+    where
+        T: ToolRuntime<Rq, Out>,
+        Rq: ProvidesSandboxRetryData,
+    {
+        let otel = turn_ctx.client.get_otel_event_manager();
+        let otel_tn = &tool_ctx.tool_name;
+        let otel_ci = &tool_ctx.call_id;
+        let otel_user = llmx_otel::otel_event_manager::ToolDecisionSource::User;
+        let otel_cfg = llmx_otel::otel_event_manager::ToolDecisionSource::Config;
+
+        // 1) Approval
+        let needs_initial_approval =
+            tool.wants_initial_approval(req, approval_policy, &turn_ctx.sandbox_policy);
+        let mut already_approved = false;
+
+        if needs_initial_approval {
+            let mut risk = None;
+
+            if let Some(metadata) = req.sandbox_retry_data() {
+                risk = tool_ctx
+                    .session
+                    .assess_sandbox_command(turn_ctx, &tool_ctx.call_id, &metadata.command, None)
+                    .await;
+            }
+
+            let approval_ctx = ApprovalCtx {
+                session: tool_ctx.session,
+                turn: turn_ctx,
+                call_id: &tool_ctx.call_id,
+                retry_reason: None,
+                risk,
+            };
+            let decision = tool.start_approval_async(req, approval_ctx).await;
+
+            otel.tool_decision(otel_tn, otel_ci, decision, otel_user.clone());
+
+            match decision {
+                ReviewDecision::Denied | ReviewDecision::Abort => {
+                    return Err(ToolError::Rejected("rejected by user".to_string()));
+                }
+                ReviewDecision::Approved | ReviewDecision::ApprovedForSession => {}
+            }
+            already_approved = true;
+        } else {
+            otel.tool_decision(otel_tn, otel_ci, ReviewDecision::Approved, otel_cfg);
+        }
+
+        // 2) First attempt under the selected sandbox.
+        let mut initial_sandbox = self
+            .sandbox
+            .select_initial(&turn_ctx.sandbox_policy, tool.sandbox_preference());
+        if tool.wants_escalated_first_attempt(req) {
+            initial_sandbox = crate::exec::SandboxType::None;
+        }
+        // Platform-specific flag gating is handled by SandboxManager::select_initial
+        // via crate::safety::get_platform_sandbox().
+        let initial_attempt = SandboxAttempt {
+            sandbox: initial_sandbox,
+            policy: &turn_ctx.sandbox_policy,
+            manager: &self.sandbox,
+            sandbox_cwd: &turn_ctx.cwd,
+            llmx_linux_sandbox_exe: turn_ctx.llmx_linux_sandbox_exe.as_ref(),
+        };
+
+        match tool.run(req, &initial_attempt, tool_ctx).await {
+            Ok(out) => {
+                // We have a successful initial result
+                Ok(out)
+            }
+            Err(ToolError::Llmx(LlmxErr::Sandbox(SandboxErr::Denied { output }))) => {
+                if !tool.escalate_on_failure() {
+                    return Err(ToolError::Llmx(LlmxErr::Sandbox(SandboxErr::Denied {
+                        output,
+                    })));
+                }
+                // Under `Never` or `OnRequest`, do not retry without sandbox; surface a concise
+                // sandbox denial that preserves the original output.
+                if !tool.wants_no_sandbox_approval(approval_policy) {
+                    return Err(ToolError::Llmx(LlmxErr::Sandbox(SandboxErr::Denied {
+                        output,
+                    })));
+                }
+
+                // Ask for approval before retrying without sandbox.
+                if !tool.should_bypass_approval(approval_policy, already_approved) {
+                    let mut risk = None;
+
+                    if let Some(metadata) = req.sandbox_retry_data() {
+                        let err = SandboxErr::Denied {
+                            output: output.clone(),
+                        };
+                        let friendly = get_error_message_ui(&LlmxErr::Sandbox(err));
+                        let failure_summary = format!("failed in sandbox: {friendly}");
+
+                        risk = tool_ctx
+                            .session
+                            .assess_sandbox_command(
+                                turn_ctx,
+                                &tool_ctx.call_id,
+                                &metadata.command,
+                                Some(failure_summary.as_str()),
+                            )
+                            .await;
+                    }
+
+                    let reason_msg = build_denial_reason_from_output(output.as_ref());
+                    let approval_ctx = ApprovalCtx {
+                        session: tool_ctx.session,
+                        turn: turn_ctx,
+                        call_id: &tool_ctx.call_id,
+                        retry_reason: Some(reason_msg),
+                        risk,
+                    };
+
+                    let decision = tool.start_approval_async(req, approval_ctx).await;
+                    otel.tool_decision(otel_tn, otel_ci, decision, otel_user);
+
+                    match decision {
+                        ReviewDecision::Denied | ReviewDecision::Abort => {
+                            return Err(ToolError::Rejected("rejected by user".to_string()));
+                        }
+                        ReviewDecision::Approved | ReviewDecision::ApprovedForSession => {}
+                    }
+                }
+
+                let escalated_attempt = SandboxAttempt {
+                    sandbox: crate::exec::SandboxType::None,
+                    policy: &turn_ctx.sandbox_policy,
+                    manager: &self.sandbox,
+                    sandbox_cwd: &turn_ctx.cwd,
+                    llmx_linux_sandbox_exe: None,
+                };
+
+                // Second attempt.
+                (*tool).run(req, &escalated_attempt, tool_ctx).await
+            }
+            other => other,
+        }
+    }
+}
+
+fn build_denial_reason_from_output(_output: &ExecToolCallOutput) -> String {
+    // Keep approval reason terse and stable for UX/tests, but accept the
+    // output so we can evolve heuristics later without touching call sites.
+    "command failed; retry without sandbox?".to_string()
+}

llmx-rs/core/src/tools/parallel.rs

@@ -0,0 +1,126 @@
+use std::sync::Arc;
+use std::time::Instant;
+
+use tokio::sync::RwLock;
+use tokio_util::either::Either;
+use tokio_util::sync::CancellationToken;
+use tokio_util::task::AbortOnDropHandle;
+
+use crate::error::LlmxErr;
+use crate::function_tool::FunctionCallError;
+use crate::llmx::Session;
+use crate::llmx::TurnContext;
+use crate::tools::context::SharedTurnDiffTracker;
+use crate::tools::context::ToolPayload;
+use crate::tools::router::ToolCall;
+use crate::tools::router::ToolRouter;
+use llmx_protocol::models::FunctionCallOutputPayload;
+use llmx_protocol::models::ResponseInputItem;
+use llmx_utils_readiness::Readiness;
+
+pub(crate) struct ToolCallRuntime {
+    router: Arc<ToolRouter>,
+    session: Arc<Session>,
+    turn_context: Arc<TurnContext>,
+    tracker: SharedTurnDiffTracker,
+    parallel_execution: Arc<RwLock<()>>,
+}
+
+impl ToolCallRuntime {
+    pub(crate) fn new(
+        router: Arc<ToolRouter>,
+        session: Arc<Session>,
+        turn_context: Arc<TurnContext>,
+        tracker: SharedTurnDiffTracker,
+    ) -> Self {
+        Self {
+            router,
+            session,
+            turn_context,
+            tracker,
+            parallel_execution: Arc::new(RwLock::new(())),
+        }
+    }
+
+    pub(crate) fn handle_tool_call(
+        &self,
+        call: ToolCall,
+        cancellation_token: CancellationToken,
+    ) -> impl std::future::Future<Output = Result<ResponseInputItem, LlmxErr>> {
+        let supports_parallel = self.router.tool_supports_parallel(&call.tool_name);
+
+        let router = Arc::clone(&self.router);
+        let session = Arc::clone(&self.session);
+        let turn = Arc::clone(&self.turn_context);
+        let tracker = Arc::clone(&self.tracker);
+        let lock = Arc::clone(&self.parallel_execution);
+        let started = Instant::now();
+        let readiness = self.turn_context.tool_call_gate.clone();
+
+        let handle: AbortOnDropHandle<Result<ResponseInputItem, FunctionCallError>> =
+            AbortOnDropHandle::new(tokio::spawn(async move {
+                tokio::select! {
+                    _ = cancellation_token.cancelled() => {
+                        let secs = started.elapsed().as_secs_f32().max(0.1);
+                        Ok(Self::aborted_response(&call, secs))
+                    },
+                    res = async {
+                        tracing::info!("waiting for tool gate");
+                        readiness.wait_ready().await;
+                        tracing::info!("tool gate released");
+                        let _guard = if supports_parallel {
+                            Either::Left(lock.read().await)
+                        } else {
+                            Either::Right(lock.write().await)
+                        };
+
+                        router
+                            .dispatch_tool_call(session, turn, tracker, call.clone())
+                            .await
+                    } => res,
+                }
+            }));
+
+        async move {
+            match handle.await {
+                Ok(Ok(response)) => Ok(response),
+                Ok(Err(FunctionCallError::Fatal(message))) => Err(LlmxErr::Fatal(message)),
+                Ok(Err(other)) => Err(LlmxErr::Fatal(other.to_string())),
+                Err(err) => Err(LlmxErr::Fatal(format!(
+                    "tool task failed to receive: {err:?}"
+                ))),
+            }
+        }
+    }
+}
+
+impl ToolCallRuntime {
+    fn aborted_response(call: &ToolCall, secs: f32) -> ResponseInputItem {
+        match &call.payload {
+            ToolPayload::Custom { .. } => ResponseInputItem::CustomToolCallOutput {
+                call_id: call.call_id.clone(),
+                output: Self::abort_message(call, secs),
+            },
+            ToolPayload::Mcp { .. } => ResponseInputItem::McpToolCallOutput {
+                call_id: call.call_id.clone(),
+                result: Err(Self::abort_message(call, secs)),
+            },
+            _ => ResponseInputItem::FunctionCallOutput {
+                call_id: call.call_id.clone(),
+                output: FunctionCallOutputPayload {
+                    content: Self::abort_message(call, secs),
+                    ..Default::default()
+                },
+            },
+        }
+    }
+
+    fn abort_message(call: &ToolCall, secs: f32) -> String {
+        match call.tool_name.as_str() {
+            "shell" | "container.exec" | "local_shell" | "unified_exec" => {
+                format!("Wall time: {secs:.1} seconds\naborted by user")
+            }
+            _ => format!("aborted by user after {secs:.1}s"),
+        }
+    }
+}

llmx-rs/core/src/tools/registry.rs

@@ -0,0 +1,218 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+use std::time::Duration;
+
+use async_trait::async_trait;
+use llmx_protocol::models::ResponseInputItem;
+use tracing::warn;
+
+use crate::client_common::tools::ToolSpec;
+use crate::function_tool::FunctionCallError;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolOutput;
+use crate::tools::context::ToolPayload;
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq, Hash)]
+pub enum ToolKind {
+    Function,
+    Mcp,
+}
+
+#[async_trait]
+pub trait ToolHandler: Send + Sync {
+    fn kind(&self) -> ToolKind;
+
+    fn matches_kind(&self, payload: &ToolPayload) -> bool {
+        matches!(
+            (self.kind(), payload),
+            (ToolKind::Function, ToolPayload::Function { .. })
+                | (ToolKind::Mcp, ToolPayload::Mcp { .. })
+        )
+    }
+
+    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError>;
+}
+
+pub struct ToolRegistry {
+    handlers: HashMap<String, Arc<dyn ToolHandler>>,
+}
+
+impl ToolRegistry {
+    pub fn new(handlers: HashMap<String, Arc<dyn ToolHandler>>) -> Self {
+        Self { handlers }
+    }
+
+    pub fn handler(&self, name: &str) -> Option<Arc<dyn ToolHandler>> {
+        self.handlers.get(name).map(Arc::clone)
+    }
+
+    // TODO(jif) for dynamic tools.
+    // pub fn register(&mut self, name: impl Into<String>, handler: Arc<dyn ToolHandler>) {
+    //     let name = name.into();
+    //     if self.handlers.insert(name.clone(), handler).is_some() {
+    //         warn!("overwriting handler for tool {name}");
+    //     }
+    // }
+
+    pub async fn dispatch(
+        &self,
+        invocation: ToolInvocation,
+    ) -> Result<ResponseInputItem, FunctionCallError> {
+        let tool_name = invocation.tool_name.clone();
+        let call_id_owned = invocation.call_id.clone();
+        let otel = invocation.turn.client.get_otel_event_manager();
+        let payload_for_response = invocation.payload.clone();
+        let log_payload = payload_for_response.log_payload();
+
+        let handler = match self.handler(tool_name.as_ref()) {
+            Some(handler) => handler,
+            None => {
+                let message =
+                    unsupported_tool_call_message(&invocation.payload, tool_name.as_ref());
+                otel.tool_result(
+                    tool_name.as_ref(),
+                    &call_id_owned,
+                    log_payload.as_ref(),
+                    Duration::ZERO,
+                    false,
+                    &message,
+                );
+                return Err(FunctionCallError::RespondToModel(message));
+            }
+        };
+
+        if !handler.matches_kind(&invocation.payload) {
+            let message = format!("tool {tool_name} invoked with incompatible payload");
+            otel.tool_result(
+                tool_name.as_ref(),
+                &call_id_owned,
+                log_payload.as_ref(),
+                Duration::ZERO,
+                false,
+                &message,
+            );
+            return Err(FunctionCallError::Fatal(message));
+        }
+
+        let output_cell = tokio::sync::Mutex::new(None);
+
+        let result = otel
+            .log_tool_result(
+                tool_name.as_ref(),
+                &call_id_owned,
+                log_payload.as_ref(),
+                || {
+                    let handler = handler.clone();
+                    let output_cell = &output_cell;
+                    let invocation = invocation;
+                    async move {
+                        match handler.handle(invocation).await {
+                            Ok(output) => {
+                                let preview = output.log_preview();
+                                let success = output.success_for_logging();
+                                let mut guard = output_cell.lock().await;
+                                *guard = Some(output);
+                                Ok((preview, success))
+                            }
+                            Err(err) => Err(err),
+                        }
+                    }
+                },
+            )
+            .await;
+
+        match result {
+            Ok(_) => {
+                let mut guard = output_cell.lock().await;
+                let output = guard.take().ok_or_else(|| {
+                    FunctionCallError::Fatal("tool produced no output".to_string())
+                })?;
+                Ok(output.into_response(&call_id_owned, &payload_for_response))
+            }
+            Err(err) => Err(err),
+        }
+    }
+}
+
+#[derive(Debug, Clone)]
+pub struct ConfiguredToolSpec {
+    pub spec: ToolSpec,
+    pub supports_parallel_tool_calls: bool,
+}
+
+impl ConfiguredToolSpec {
+    pub fn new(spec: ToolSpec, supports_parallel_tool_calls: bool) -> Self {
+        Self {
+            spec,
+            supports_parallel_tool_calls,
+        }
+    }
+}
+
+pub struct ToolRegistryBuilder {
+    handlers: HashMap<String, Arc<dyn ToolHandler>>,
+    specs: Vec<ConfiguredToolSpec>,
+}
+
+impl ToolRegistryBuilder {
+    pub fn new() -> Self {
+        Self {
+            handlers: HashMap::new(),
+            specs: Vec::new(),
+        }
+    }
+
+    pub fn push_spec(&mut self, spec: ToolSpec) {
+        self.push_spec_with_parallel_support(spec, false);
+    }
+
+    pub fn push_spec_with_parallel_support(
+        &mut self,
+        spec: ToolSpec,
+        supports_parallel_tool_calls: bool,
+    ) {
+        self.specs
+            .push(ConfiguredToolSpec::new(spec, supports_parallel_tool_calls));
+    }
+
+    pub fn register_handler(&mut self, name: impl Into<String>, handler: Arc<dyn ToolHandler>) {
+        let name = name.into();
+        if self
+            .handlers
+            .insert(name.clone(), handler.clone())
+            .is_some()
+        {
+            warn!("overwriting handler for tool {name}");
+        }
+    }
+
+    // TODO(jif) for dynamic tools.
+    // pub fn register_many<I>(&mut self, names: I, handler: Arc<dyn ToolHandler>)
+    // where
+    //     I: IntoIterator,
+    //     I::Item: Into<String>,
+    // {
+    //     for name in names {
+    //         let name = name.into();
+    //         if self
+    //             .handlers
+    //             .insert(name.clone(), handler.clone())
+    //             .is_some()
+    //         {
+    //             warn!("overwriting handler for tool {name}");
+    //         }
+    //     }
+    // }
+
+    pub fn build(self) -> (Vec<ConfiguredToolSpec>, ToolRegistry) {
+        let registry = ToolRegistry::new(self.handlers);
+        (self.specs, registry)
+    }
+}
+
+fn unsupported_tool_call_message(payload: &ToolPayload, tool_name: &str) -> String {
+    match payload {
+        ToolPayload::Custom { .. } => format!("unsupported custom tool call: {tool_name}"),
+        _ => format!("unsupported call: {tool_name}"),
+    }
+}

llmx-rs/core/src/tools/router.rs

@@ -0,0 +1,189 @@
+use std::collections::HashMap;
+use std::sync::Arc;
+
+use crate::client_common::tools::ToolSpec;
+use crate::function_tool::FunctionCallError;
+use crate::llmx::Session;
+use crate::llmx::TurnContext;
+use crate::tools::context::SharedTurnDiffTracker;
+use crate::tools::context::ToolInvocation;
+use crate::tools::context::ToolPayload;
+use crate::tools::registry::ConfiguredToolSpec;
+use crate::tools::registry::ToolRegistry;
+use crate::tools::spec::ToolsConfig;
+use crate::tools::spec::build_specs;
+use llmx_protocol::models::LocalShellAction;
+use llmx_protocol::models::ResponseInputItem;
+use llmx_protocol::models::ResponseItem;
+use llmx_protocol::models::ShellToolCallParams;
+
+#[derive(Clone)]
+pub struct ToolCall {
+    pub tool_name: String,
+    pub call_id: String,
+    pub payload: ToolPayload,
+}
+
+pub struct ToolRouter {
+    registry: ToolRegistry,
+    specs: Vec<ConfiguredToolSpec>,
+}
+
+impl ToolRouter {
+    pub fn from_config(
+        config: &ToolsConfig,
+        mcp_tools: Option<HashMap<String, mcp_types::Tool>>,
+    ) -> Self {
+        let builder = build_specs(config, mcp_tools);
+        let (specs, registry) = builder.build();
+
+        Self { registry, specs }
+    }
+
+    pub fn specs(&self) -> Vec<ToolSpec> {
+        self.specs
+            .iter()
+            .map(|config| config.spec.clone())
+            .collect()
+    }
+
+    pub fn tool_supports_parallel(&self, tool_name: &str) -> bool {
+        self.specs
+            .iter()
+            .filter(|config| config.supports_parallel_tool_calls)
+            .any(|config| config.spec.name() == tool_name)
+    }
+
+    pub fn build_tool_call(
+        session: &Session,
+        item: ResponseItem,
+    ) -> Result<Option<ToolCall>, FunctionCallError> {
+        match item {
+            ResponseItem::FunctionCall {
+                name,
+                arguments,
+                call_id,
+                ..
+            } => {
+                if let Some((server, tool)) = session.parse_mcp_tool_name(&name) {
+                    Ok(Some(ToolCall {
+                        tool_name: name,
+                        call_id,
+                        payload: ToolPayload::Mcp {
+                            server,
+                            tool,
+                            raw_arguments: arguments,
+                        },
+                    }))
+                } else {
+                    let payload = if name == "unified_exec" {
+                        ToolPayload::UnifiedExec { arguments }
+                    } else {
+                        ToolPayload::Function { arguments }
+                    };
+                    Ok(Some(ToolCall {
+                        tool_name: name,
+                        call_id,
+                        payload,
+                    }))
+                }
+            }
+            ResponseItem::CustomToolCall {
+                name,
+                input,
+                call_id,
+                ..
+            } => Ok(Some(ToolCall {
+                tool_name: name,
+                call_id,
+                payload: ToolPayload::Custom { input },
+            })),
+            ResponseItem::LocalShellCall {
+                id,
+                call_id,
+                action,
+                ..
+            } => {
+                let call_id = call_id
+                    .or(id)
+                    .ok_or(FunctionCallError::MissingLocalShellCallId)?;
+
+                match action {
+                    LocalShellAction::Exec(exec) => {
+                        let params = ShellToolCallParams {
+                            command: exec.command,
+                            workdir: exec.working_directory,
+                            timeout_ms: exec.timeout_ms,
+                            with_escalated_permissions: None,
+                            justification: None,
+                        };
+                        Ok(Some(ToolCall {
+                            tool_name: "local_shell".to_string(),
+                            call_id,
+                            payload: ToolPayload::LocalShell { params },
+                        }))
+                    }
+                }
+            }
+            _ => Ok(None),
+        }
+    }
+
+    pub async fn dispatch_tool_call(
+        &self,
+        session: Arc<Session>,
+        turn: Arc<TurnContext>,
+        tracker: SharedTurnDiffTracker,
+        call: ToolCall,
+    ) -> Result<ResponseInputItem, FunctionCallError> {
+        let ToolCall {
+            tool_name,
+            call_id,
+            payload,
+        } = call;
+        let payload_outputs_custom = matches!(payload, ToolPayload::Custom { .. });
+        let failure_call_id = call_id.clone();
+
+        let invocation = ToolInvocation {
+            session,
+            turn,
+            tracker,
+            call_id,
+            tool_name,
+            payload,
+        };
+
+        match self.registry.dispatch(invocation).await {
+            Ok(response) => Ok(response),
+            Err(FunctionCallError::Fatal(message)) => Err(FunctionCallError::Fatal(message)),
+            Err(err) => Ok(Self::failure_response(
+                failure_call_id,
+                payload_outputs_custom,
+                err,
+            )),
+        }
+    }
+
+    fn failure_response(
+        call_id: String,
+        payload_outputs_custom: bool,
+        err: FunctionCallError,
+    ) -> ResponseInputItem {
+        let message = err.to_string();
+        if payload_outputs_custom {
+            ResponseInputItem::CustomToolCallOutput {
+                call_id,
+                output: message,
+            }
+        } else {
+            ResponseInputItem::FunctionCallOutput {
+                call_id,
+                output: llmx_protocol::models::FunctionCallOutputPayload {
+                    content: message,
+                    success: Some(false),
+                    ..Default::default()
+                },
+            }
+        }
+    }
+}

llmx-rs/core/src/tools/runtimes/apply_patch.rs

@@ -0,0 +1,163 @@
+//! Apply Patch runtime: executes verified patches under the orchestrator.
+//!
+//! Assumes `apply_patch` verification/approval happened upstream. Reuses that
+//! decision to avoid re-prompting, builds the self-invocation command for
+//! `llmx --llmx-run-as-apply-patch`, and runs under the current
+//! `SandboxAttempt` with a minimal environment.
+use crate::LLMX_APPLY_PATCH_ARG1;
+use crate::exec::ExecToolCallOutput;
+use crate::sandboxing::CommandSpec;
+use crate::sandboxing::execute_env;
+use crate::tools::sandboxing::Approvable;
+use crate::tools::sandboxing::ApprovalCtx;
+use crate::tools::sandboxing::ProvidesSandboxRetryData;
+use crate::tools::sandboxing::SandboxAttempt;
+use crate::tools::sandboxing::SandboxRetryData;
+use crate::tools::sandboxing::Sandboxable;
+use crate::tools::sandboxing::SandboxablePreference;
+use crate::tools::sandboxing::ToolCtx;
+use crate::tools::sandboxing::ToolError;
+use crate::tools::sandboxing::ToolRuntime;
+use crate::tools::sandboxing::with_cached_approval;
+use futures::future::BoxFuture;
+use llmx_protocol::protocol::AskForApproval;
+use llmx_protocol::protocol::ReviewDecision;
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+#[derive(Clone, Debug)]
+pub struct ApplyPatchRequest {
+    pub patch: String,
+    pub cwd: PathBuf,
+    pub timeout_ms: Option<u64>,
+    pub user_explicitly_approved: bool,
+    pub llmx_exe: Option<PathBuf>,
+}
+
+impl ProvidesSandboxRetryData for ApplyPatchRequest {
+    fn sandbox_retry_data(&self) -> Option<SandboxRetryData> {
+        None
+    }
+}
+
+#[derive(Default)]
+pub struct ApplyPatchRuntime;
+
+#[derive(serde::Serialize, Clone, Debug, Eq, PartialEq, Hash)]
+pub(crate) struct ApprovalKey {
+    patch: String,
+    cwd: PathBuf,
+}
+
+impl ApplyPatchRuntime {
+    pub fn new() -> Self {
+        Self
+    }
+
+    fn build_command_spec(req: &ApplyPatchRequest) -> Result<CommandSpec, ToolError> {
+        use std::env;
+        let exe = if let Some(path) = &req.llmx_exe {
+            path.clone()
+        } else {
+            env::current_exe()
+                .map_err(|e| ToolError::Rejected(format!("failed to determine llmx exe: {e}")))?
+        };
+        let program = exe.to_string_lossy().to_string();
+        Ok(CommandSpec {
+            program,
+            args: vec![LLMX_APPLY_PATCH_ARG1.to_string(), req.patch.clone()],
+            cwd: req.cwd.clone(),
+            timeout_ms: req.timeout_ms,
+            // Run apply_patch with a minimal environment for determinism and to avoid leaks.
+            env: HashMap::new(),
+            with_escalated_permissions: None,
+            justification: None,
+        })
+    }
+
+    fn stdout_stream(ctx: &ToolCtx<'_>) -> Option<crate::exec::StdoutStream> {
+        Some(crate::exec::StdoutStream {
+            sub_id: ctx.turn.sub_id.clone(),
+            call_id: ctx.call_id.clone(),
+            tx_event: ctx.session.get_tx_event(),
+        })
+    }
+}
+
+impl Sandboxable for ApplyPatchRuntime {
+    fn sandbox_preference(&self) -> SandboxablePreference {
+        SandboxablePreference::Auto
+    }
+    fn escalate_on_failure(&self) -> bool {
+        true
+    }
+}
+
+impl Approvable<ApplyPatchRequest> for ApplyPatchRuntime {
+    type ApprovalKey = ApprovalKey;
+
+    fn approval_key(&self, req: &ApplyPatchRequest) -> Self::ApprovalKey {
+        ApprovalKey {
+            patch: req.patch.clone(),
+            cwd: req.cwd.clone(),
+        }
+    }
+
+    fn start_approval_async<'a>(
+        &'a mut self,
+        req: &'a ApplyPatchRequest,
+        ctx: ApprovalCtx<'a>,
+    ) -> BoxFuture<'a, ReviewDecision> {
+        let key = self.approval_key(req);
+        let session = ctx.session;
+        let turn = ctx.turn;
+        let call_id = ctx.call_id.to_string();
+        let cwd = req.cwd.clone();
+        let retry_reason = ctx.retry_reason.clone();
+        let risk = ctx.risk.clone();
+        let user_explicitly_approved = req.user_explicitly_approved;
+        Box::pin(async move {
+            with_cached_approval(&session.services, key, move || async move {
+                if let Some(reason) = retry_reason {
+                    session
+                        .request_command_approval(
+                            turn,
+                            call_id,
+                            vec!["apply_patch".to_string()],
+                            cwd,
+                            Some(reason),
+                            risk,
+                        )
+                        .await
+                } else if user_explicitly_approved {
+                    ReviewDecision::ApprovedForSession
+                } else {
+                    ReviewDecision::Approved
+                }
+            })
+            .await
+        })
+    }
+
+    fn wants_no_sandbox_approval(&self, policy: AskForApproval) -> bool {
+        !matches!(policy, AskForApproval::Never)
+    }
+}
+
+impl ToolRuntime<ApplyPatchRequest, ExecToolCallOutput> for ApplyPatchRuntime {
+    async fn run(
+        &mut self,
+        req: &ApplyPatchRequest,
+        attempt: &SandboxAttempt<'_>,
+        ctx: &ToolCtx<'_>,
+    ) -> Result<ExecToolCallOutput, ToolError> {
+        let spec = Self::build_command_spec(req)?;
+        let env = attempt
+            .env_for(&spec)
+            .map_err(|err| ToolError::Llmx(err.into()))?;
+        let out = execute_env(&env, attempt.policy, Self::stdout_stream(ctx))
+            .await
+            .map_err(ToolError::Llmx)?;
+        Ok(out)
+    }
+}

llmx-rs/core/src/tools/runtimes/mod.rs

@@ -0,0 +1,38 @@
+/*
+Module: runtimes
+
+Concrete ToolRuntime implementations for specific tools. Each runtime stays
+small and focused and reuses the orchestrator for approvals + sandbox + retry.
+*/
+use crate::sandboxing::CommandSpec;
+use crate::tools::sandboxing::ToolError;
+use std::collections::HashMap;
+use std::path::Path;
+
+pub mod apply_patch;
+pub mod shell;
+pub mod unified_exec;
+
+/// Shared helper to construct a CommandSpec from a tokenized command line.
+/// Validates that at least a program is present.
+pub(crate) fn build_command_spec(
+    command: &[String],
+    cwd: &Path,
+    env: &HashMap<String, String>,
+    timeout_ms: Option<u64>,
+    with_escalated_permissions: Option<bool>,
+    justification: Option<String>,
+) -> Result<CommandSpec, ToolError> {
+    let (program, args) = command
+        .split_first()
+        .ok_or_else(|| ToolError::Rejected("command args are empty".to_string()))?;
+    Ok(CommandSpec {
+        program: program.clone(),
+        args: args.to_vec(),
+        cwd: cwd.to_path_buf(),
+        env: env.clone(),
+        timeout_ms,
+        with_escalated_permissions,
+        justification,
+    })
+}

llmx-rs/core/src/tools/runtimes/shell.rs

@@ -0,0 +1,159 @@
+/*
+Runtime: shell
+
+Executes shell requests under the orchestrator: asks for approval when needed,
+builds a CommandSpec, and runs it under the current SandboxAttempt.
+*/
+use crate::command_safety::is_dangerous_command::requires_initial_appoval;
+use crate::exec::ExecToolCallOutput;
+use crate::protocol::SandboxPolicy;
+use crate::sandboxing::execute_env;
+use crate::tools::runtimes::build_command_spec;
+use crate::tools::sandboxing::Approvable;
+use crate::tools::sandboxing::ApprovalCtx;
+use crate::tools::sandboxing::ProvidesSandboxRetryData;
+use crate::tools::sandboxing::SandboxAttempt;
+use crate::tools::sandboxing::SandboxRetryData;
+use crate::tools::sandboxing::Sandboxable;
+use crate::tools::sandboxing::SandboxablePreference;
+use crate::tools::sandboxing::ToolCtx;
+use crate::tools::sandboxing::ToolError;
+use crate::tools::sandboxing::ToolRuntime;
+use crate::tools::sandboxing::with_cached_approval;
+use futures::future::BoxFuture;
+use llmx_protocol::protocol::AskForApproval;
+use llmx_protocol::protocol::ReviewDecision;
+use std::path::PathBuf;
+
+#[derive(Clone, Debug)]
+pub struct ShellRequest {
+    pub command: Vec<String>,
+    pub cwd: PathBuf,
+    pub timeout_ms: Option<u64>,
+    pub env: std::collections::HashMap<String, String>,
+    pub with_escalated_permissions: Option<bool>,
+    pub justification: Option<String>,
+}
+
+impl ProvidesSandboxRetryData for ShellRequest {
+    fn sandbox_retry_data(&self) -> Option<SandboxRetryData> {
+        Some(SandboxRetryData {
+            command: self.command.clone(),
+            cwd: self.cwd.clone(),
+        })
+    }
+}
+
+#[derive(Default)]
+pub struct ShellRuntime;
+
+#[derive(serde::Serialize, Clone, Debug, Eq, PartialEq, Hash)]
+pub(crate) struct ApprovalKey {
+    command: Vec<String>,
+    cwd: PathBuf,
+    escalated: bool,
+}
+
+impl ShellRuntime {
+    pub fn new() -> Self {
+        Self
+    }
+
+    fn stdout_stream(ctx: &ToolCtx<'_>) -> Option<crate::exec::StdoutStream> {
+        Some(crate::exec::StdoutStream {
+            sub_id: ctx.turn.sub_id.clone(),
+            call_id: ctx.call_id.clone(),
+            tx_event: ctx.session.get_tx_event(),
+        })
+    }
+}
+
+impl Sandboxable for ShellRuntime {
+    fn sandbox_preference(&self) -> SandboxablePreference {
+        SandboxablePreference::Auto
+    }
+    fn escalate_on_failure(&self) -> bool {
+        true
+    }
+}
+
+impl Approvable<ShellRequest> for ShellRuntime {
+    type ApprovalKey = ApprovalKey;
+
+    fn approval_key(&self, req: &ShellRequest) -> Self::ApprovalKey {
+        ApprovalKey {
+            command: req.command.clone(),
+            cwd: req.cwd.clone(),
+            escalated: req.with_escalated_permissions.unwrap_or(false),
+        }
+    }
+
+    fn start_approval_async<'a>(
+        &'a mut self,
+        req: &'a ShellRequest,
+        ctx: ApprovalCtx<'a>,
+    ) -> BoxFuture<'a, ReviewDecision> {
+        let key = self.approval_key(req);
+        let command = req.command.clone();
+        let cwd = req.cwd.clone();
+        let reason = ctx
+            .retry_reason
+            .clone()
+            .or_else(|| req.justification.clone());
+        let risk = ctx.risk.clone();
+        let session = ctx.session;
+        let turn = ctx.turn;
+        let call_id = ctx.call_id.to_string();
+        Box::pin(async move {
+            with_cached_approval(&session.services, key, move || async move {
+                session
+                    .request_command_approval(turn, call_id, command, cwd, reason, risk)
+                    .await
+            })
+            .await
+        })
+    }
+
+    fn wants_initial_approval(
+        &self,
+        req: &ShellRequest,
+        policy: AskForApproval,
+        sandbox_policy: &SandboxPolicy,
+    ) -> bool {
+        requires_initial_appoval(
+            policy,
+            sandbox_policy,
+            &req.command,
+            req.with_escalated_permissions.unwrap_or(false),
+        )
+    }
+
+    fn wants_escalated_first_attempt(&self, req: &ShellRequest) -> bool {
+        req.with_escalated_permissions.unwrap_or(false)
+    }
+}
+
+impl ToolRuntime<ShellRequest, ExecToolCallOutput> for ShellRuntime {
+    async fn run(
+        &mut self,
+        req: &ShellRequest,
+        attempt: &SandboxAttempt<'_>,
+        ctx: &ToolCtx<'_>,
+    ) -> Result<ExecToolCallOutput, ToolError> {
+        let spec = build_command_spec(
+            &req.command,
+            &req.cwd,
+            &req.env,
+            req.timeout_ms,
+            req.with_escalated_permissions,
+            req.justification.clone(),
+        )?;
+        let env = attempt
+            .env_for(&spec)
+            .map_err(|err| ToolError::Llmx(err.into()))?;
+        let out = execute_env(&env, attempt.policy, Self::stdout_stream(ctx))
+            .await
+            .map_err(ToolError::Llmx)?;
+        Ok(out)
+    }
+}

llmx-rs/core/src/tools/runtimes/unified_exec.rs

@@ -0,0 +1,147 @@
+use crate::command_safety::is_dangerous_command::requires_initial_appoval;
+/*
+Runtime: unified exec
+
+Handles approval + sandbox orchestration for unified exec requests, delegating to
+the session manager to spawn PTYs once an ExecEnv is prepared.
+*/
+use crate::error::LlmxErr;
+use crate::error::SandboxErr;
+use crate::tools::runtimes::build_command_spec;
+use crate::tools::sandboxing::Approvable;
+use crate::tools::sandboxing::ApprovalCtx;
+use crate::tools::sandboxing::ProvidesSandboxRetryData;
+use crate::tools::sandboxing::SandboxAttempt;
+use crate::tools::sandboxing::SandboxRetryData;
+use crate::tools::sandboxing::Sandboxable;
+use crate::tools::sandboxing::SandboxablePreference;
+use crate::tools::sandboxing::ToolCtx;
+use crate::tools::sandboxing::ToolError;
+use crate::tools::sandboxing::ToolRuntime;
+use crate::tools::sandboxing::with_cached_approval;
+use crate::unified_exec::UnifiedExecError;
+use crate::unified_exec::UnifiedExecSession;
+use crate::unified_exec::UnifiedExecSessionManager;
+use futures::future::BoxFuture;
+use llmx_protocol::protocol::AskForApproval;
+use llmx_protocol::protocol::ReviewDecision;
+use llmx_protocol::protocol::SandboxPolicy;
+use std::collections::HashMap;
+use std::path::PathBuf;
+
+#[derive(Clone, Debug)]
+pub struct UnifiedExecRequest {
+    pub command: Vec<String>,
+    pub cwd: PathBuf,
+    pub env: HashMap<String, String>,
+}
+
+impl ProvidesSandboxRetryData for UnifiedExecRequest {
+    fn sandbox_retry_data(&self) -> Option<SandboxRetryData> {
+        Some(SandboxRetryData {
+            command: self.command.clone(),
+            cwd: self.cwd.clone(),
+        })
+    }
+}
+
+#[derive(serde::Serialize, Clone, Debug, Eq, PartialEq, Hash)]
+pub struct UnifiedExecApprovalKey {
+    pub command: Vec<String>,
+    pub cwd: PathBuf,
+}
+
+pub struct UnifiedExecRuntime<'a> {
+    manager: &'a UnifiedExecSessionManager,
+}
+
+impl UnifiedExecRequest {
+    pub fn new(command: Vec<String>, cwd: PathBuf, env: HashMap<String, String>) -> Self {
+        Self { command, cwd, env }
+    }
+}
+
+impl<'a> UnifiedExecRuntime<'a> {
+    pub fn new(manager: &'a UnifiedExecSessionManager) -> Self {
+        Self { manager }
+    }
+}
+
+impl Sandboxable for UnifiedExecRuntime<'_> {
+    fn sandbox_preference(&self) -> SandboxablePreference {
+        SandboxablePreference::Auto
+    }
+
+    fn escalate_on_failure(&self) -> bool {
+        true
+    }
+}
+
+impl Approvable<UnifiedExecRequest> for UnifiedExecRuntime<'_> {
+    type ApprovalKey = UnifiedExecApprovalKey;
+
+    fn approval_key(&self, req: &UnifiedExecRequest) -> Self::ApprovalKey {
+        UnifiedExecApprovalKey {
+            command: req.command.clone(),
+            cwd: req.cwd.clone(),
+        }
+    }
+
+    fn start_approval_async<'b>(
+        &'b mut self,
+        req: &'b UnifiedExecRequest,
+        ctx: ApprovalCtx<'b>,
+    ) -> BoxFuture<'b, ReviewDecision> {
+        let key = self.approval_key(req);
+        let session = ctx.session;
+        let turn = ctx.turn;
+        let call_id = ctx.call_id.to_string();
+        let command = req.command.clone();
+        let cwd = req.cwd.clone();
+        let reason = ctx.retry_reason.clone();
+        let risk = ctx.risk.clone();
+        Box::pin(async move {
+            with_cached_approval(&session.services, key, || async move {
+                session
+                    .request_command_approval(turn, call_id, command, cwd, reason, risk)
+                    .await
+            })
+            .await
+        })
+    }
+
+    fn wants_initial_approval(
+        &self,
+        req: &UnifiedExecRequest,
+        policy: AskForApproval,
+        sandbox_policy: &SandboxPolicy,
+    ) -> bool {
+        requires_initial_appoval(policy, sandbox_policy, &req.command, false)
+    }
+}
+
+impl<'a> ToolRuntime<UnifiedExecRequest, UnifiedExecSession> for UnifiedExecRuntime<'a> {
+    async fn run(
+        &mut self,
+        req: &UnifiedExecRequest,
+        attempt: &SandboxAttempt<'_>,
+        _ctx: &ToolCtx<'_>,
+    ) -> Result<UnifiedExecSession, ToolError> {
+        let spec = build_command_spec(&req.command, &req.cwd, &req.env, None, None, None)
+            .map_err(|_| ToolError::Rejected("missing command line for PTY".to_string()))?;
+        let exec_env = attempt
+            .env_for(&spec)
+            .map_err(|err| ToolError::Llmx(err.into()))?;
+        self.manager
+            .open_session_with_exec_env(&exec_env)
+            .await
+            .map_err(|err| match err {
+                UnifiedExecError::SandboxDenied { output, .. } => {
+                    ToolError::Llmx(LlmxErr::Sandbox(SandboxErr::Denied {
+                        output: Box::new(output),
+                    }))
+                }
+                other => ToolError::Rejected(other.to_string()),
+            })
+    }
+}

llmx-rs/core/src/tools/sandboxing.rs

@@ -0,0 +1,209 @@
+//! Shared approvals and sandboxing traits used by tool runtimes.
+//!
+//! Consolidates the approval flow primitives (`ApprovalDecision`, `ApprovalStore`,
+//! `ApprovalCtx`, `Approvable`) together with the sandbox orchestration traits
+//! and helpers (`Sandboxable`, `ToolRuntime`, `SandboxAttempt`, etc.).
+
+use crate::error::LlmxErr;
+use crate::llmx::Session;
+use crate::llmx::TurnContext;
+use crate::protocol::SandboxCommandAssessment;
+use crate::protocol::SandboxPolicy;
+use crate::sandboxing::CommandSpec;
+use crate::sandboxing::SandboxManager;
+use crate::sandboxing::SandboxTransformError;
+use crate::state::SessionServices;
+use llmx_protocol::protocol::AskForApproval;
+use llmx_protocol::protocol::ReviewDecision;
+use std::collections::HashMap;
+use std::fmt::Debug;
+use std::hash::Hash;
+use std::path::Path;
+use std::path::PathBuf;
+
+use futures::Future;
+use futures::future::BoxFuture;
+use serde::Serialize;
+
+#[derive(Clone, Default, Debug)]
+pub(crate) struct ApprovalStore {
+    // Store serialized keys for generic caching across requests.
+    map: HashMap<String, ReviewDecision>,
+}
+
+impl ApprovalStore {
+    pub fn get<K>(&self, key: &K) -> Option<ReviewDecision>
+    where
+        K: Serialize,
+    {
+        let s = serde_json::to_string(key).ok()?;
+        self.map.get(&s).cloned()
+    }
+
+    pub fn put<K>(&mut self, key: K, value: ReviewDecision)
+    where
+        K: Serialize,
+    {
+        if let Ok(s) = serde_json::to_string(&key) {
+            self.map.insert(s, value);
+        }
+    }
+}
+
+pub(crate) async fn with_cached_approval<K, F, Fut>(
+    services: &SessionServices,
+    key: K,
+    fetch: F,
+) -> ReviewDecision
+where
+    K: Serialize + Clone,
+    F: FnOnce() -> Fut,
+    Fut: Future<Output = ReviewDecision>,
+{
+    {
+        let store = services.tool_approvals.lock().await;
+        if let Some(decision) = store.get(&key) {
+            return decision;
+        }
+    }
+
+    let decision = fetch().await;
+
+    if matches!(decision, ReviewDecision::ApprovedForSession) {
+        let mut store = services.tool_approvals.lock().await;
+        store.put(key, ReviewDecision::ApprovedForSession);
+    }
+
+    decision
+}
+
+#[derive(Clone)]
+pub(crate) struct ApprovalCtx<'a> {
+    pub session: &'a Session,
+    pub turn: &'a TurnContext,
+    pub call_id: &'a str,
+    pub retry_reason: Option<String>,
+    pub risk: Option<SandboxCommandAssessment>,
+}
+
+pub(crate) trait Approvable<Req> {
+    type ApprovalKey: Hash + Eq + Clone + Debug + Serialize;
+
+    fn approval_key(&self, req: &Req) -> Self::ApprovalKey;
+
+    /// Some tools may request to skip the sandbox on the first attempt
+    /// (e.g., when the request explicitly asks for escalated permissions).
+    /// Defaults to `false`.
+    fn wants_escalated_first_attempt(&self, _req: &Req) -> bool {
+        false
+    }
+
+    fn should_bypass_approval(&self, policy: AskForApproval, already_approved: bool) -> bool {
+        if already_approved {
+            // We do not ask one more time
+            return true;
+        }
+        matches!(policy, AskForApproval::Never)
+    }
+
+    /// Decide whether an initial user approval should be requested before the
+    /// first attempt. Defaults to the orchestrator's behavior (pre‑refactor):
+    /// - Never, OnFailure: do not ask
+    /// - OnRequest: ask unless sandbox policy is DangerFullAccess
+    /// - UnlessTrusted: always ask
+    fn wants_initial_approval(
+        &self,
+        _req: &Req,
+        policy: AskForApproval,
+        sandbox_policy: &SandboxPolicy,
+    ) -> bool {
+        match policy {
+            AskForApproval::Never | AskForApproval::OnFailure => false,
+            AskForApproval::OnRequest => !matches!(sandbox_policy, SandboxPolicy::DangerFullAccess),
+            AskForApproval::UnlessTrusted => true,
+        }
+    }
+
+    /// Decide we can request an approval for no-sandbox execution.
+    fn wants_no_sandbox_approval(&self, policy: AskForApproval) -> bool {
+        !matches!(policy, AskForApproval::Never | AskForApproval::OnRequest)
+    }
+
+    fn start_approval_async<'a>(
+        &'a mut self,
+        req: &'a Req,
+        ctx: ApprovalCtx<'a>,
+    ) -> BoxFuture<'a, ReviewDecision>;
+}
+
+#[derive(Clone, Copy, Debug, PartialEq, Eq)]
+pub(crate) enum SandboxablePreference {
+    Auto,
+    #[allow(dead_code)] // Will be used by later tools.
+    Require,
+    #[allow(dead_code)] // Will be used by later tools.
+    Forbid,
+}
+
+pub(crate) trait Sandboxable {
+    fn sandbox_preference(&self) -> SandboxablePreference;
+    fn escalate_on_failure(&self) -> bool {
+        true
+    }
+}
+
+pub(crate) struct ToolCtx<'a> {
+    pub session: &'a Session,
+    pub turn: &'a TurnContext,
+    pub call_id: String,
+    pub tool_name: String,
+}
+
+/// Captures the command metadata needed to re-run a tool request without sandboxing.
+#[derive(Clone, Debug, PartialEq, Eq)]
+pub(crate) struct SandboxRetryData {
+    pub command: Vec<String>,
+    pub cwd: PathBuf,
+}
+
+pub(crate) trait ProvidesSandboxRetryData {
+    fn sandbox_retry_data(&self) -> Option<SandboxRetryData>;
+}
+
+#[derive(Debug)]
+pub(crate) enum ToolError {
+    Rejected(String),
+    Llmx(LlmxErr),
+}
+
+pub(crate) trait ToolRuntime<Req, Out>: Approvable<Req> + Sandboxable {
+    async fn run(
+        &mut self,
+        req: &Req,
+        attempt: &SandboxAttempt<'_>,
+        ctx: &ToolCtx,
+    ) -> Result<Out, ToolError>;
+}
+
+pub(crate) struct SandboxAttempt<'a> {
+    pub sandbox: crate::exec::SandboxType,
+    pub policy: &'a crate::protocol::SandboxPolicy,
+    pub(crate) manager: &'a SandboxManager,
+    pub(crate) sandbox_cwd: &'a Path,
+    pub llmx_linux_sandbox_exe: Option<&'a std::path::PathBuf>,
+}
+
+impl<'a> SandboxAttempt<'a> {
+    pub fn env_for(
+        &self,
+        spec: &CommandSpec,
+    ) -> Result<crate::sandboxing::ExecEnv, SandboxTransformError> {
+        self.manager.transform(
+            spec,
+            self.policy,
+            self.sandbox,
+            self.sandbox_cwd,
+            self.llmx_linux_sandbox_exe,
+        )
+    }
+}