falsegreen_agent/

tools.rs

use std::collections::BTreeMap;
use std::fs;
use std::io::{Read, Write};
use std::path::Path;
use std::process::{Child, Command, ExitStatus, Stdio};
use std::sync::Mutex;
use std::thread;
use std::time::{Duration, Instant};

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

use crate::event::EventStore;
use crate::genui::{
    ActionCatalog, ActionSourceType, HostCapabilities, HostConfirmation, Surface,
    derive_host_workspace_state_identity,
};
use crate::inference::ToolCall;
use crate::mcp::{LiveToolIdentity, McpClientSet};
use crate::workspace::{Workspace, WorkspaceError};

#[derive(Debug, Clone, Copy)]
pub struct ToolLimits {
    pub timeout: Duration,
    pub max_output_bytes: usize,
    pub max_file_bytes: usize,
}

impl Default for ToolLimits {
    fn default() -> Self {
        Self {
            timeout: Duration::from_secs(60),
            max_output_bytes: 256 * 1024,
            max_file_bytes: 512 * 1024,
        }
    }
}

#[derive(Debug, Clone, PartialEq, Serialize, Deserialize)]
pub struct ToolResult {
    pub tool: String,
    pub tool_call_id: Option<String>,
    pub ok: bool,
    pub exit_code: Option<i32>,
    pub timed_out: bool,
    pub stdout: String,
    pub stderr: String,
    pub output_truncated: bool,
    pub metadata: Value,
}

impl ToolResult {
    #[must_use]
    pub fn rejected(tool: &str, error: &str) -> Self {
        Self {
            tool: tool.to_owned(),
            tool_call_id: None,
            ok: false,
            exit_code: None,
            timed_out: false,
            stdout: String::new(),
            stderr: error.to_owned(),
            output_truncated: false,
            metadata: json!({"validation_error": error}),
        }
    }
}

#[derive(Debug, Error)]
pub enum ToolError {
    #[error(transparent)]
    Workspace(#[from] WorkspaceError),
    #[error("invalid {tool} arguments: {message}")]
    InvalidArguments { tool: String, message: String },
    #[error("unknown tool: {0}")]
    UnknownTool(String),
    #[error("tool I/O failed: {0}")]
    Io(#[from] std::io::Error),
    #[error("tool JSON failed: {0}")]
    Json(#[from] serde_json::Error),
    #[error("patch is malformed or unsafe: {0}")]
    InvalidPatch(String),
    #[error("GenUI action rejected: {0}")]
    GenUi(String),
}

#[derive(Debug)]
pub struct NativeTools {
    workspace: Workspace,
    limits: ToolLimits,
    mcp: Option<McpClientSet>,
    workspace_authority: Mutex<Option<(String, u64)>>,
}

impl NativeTools {
    #[must_use]
    pub const fn new(workspace: Workspace, limits: ToolLimits) -> Self {
        Self {
            workspace,
            limits,
            mcp: None,
            workspace_authority: Mutex::new(None),
        }
    }

    #[must_use]
    pub fn with_mcp(mut self, mcp: McpClientSet) -> Self {
        self.mcp = Some(mcp);
        self
    }

    #[must_use]
    pub fn workspace(&self) -> &Workspace {
        &self.workspace
    }

    /// Read the current workspace authority. The generation is advanced only
    /// by a controlled mutator (apply-patch/shell) at mutation time; this read
    /// never lazily promotes a changed fingerprint into a new authority
    /// version. The exact identity is still returned so external filesystem
    /// changes are rejected at the fence, while controlled ABA changes remain
    /// visible through their mutation-time token.
    pub(crate) fn live_workspace_token(
        &self,
        session_id: &str,
        principal: &str,
    ) -> Result<((String, String), u64), WorkspaceError> {
        let state = self.workspace.state()?;
        let identity = derive_host_workspace_state_identity(session_id, principal, &state);
        let fingerprint = format!("{}\n{}", identity.0, identity.1);
        let mut authority = self
            .workspace_authority
            .lock()
            .expect("workspace authority lock is not poisoned");
        let generation = authority.as_ref().map_or(1, |(_, generation)| *generation);
        *authority = Some((fingerprint, generation));
        Ok((identity, generation))
    }

    fn note_workspace_mutation(&self) {
        let mut authority = self
            .workspace_authority
            .lock()
            .expect("workspace authority lock is not poisoned");
        let generation = authority
            .as_ref()
            .map_or(1, |(_, generation)| generation.saturating_add(1));
        let fingerprint = authority
            .as_ref()
            .map_or_else(String::new, |(fingerprint, _)| fingerprint.clone());
        *authority = Some((fingerprint, generation));
    }

    /// Mutation-time workspace authority token used by the publication CAS.
    #[must_use]
    pub fn workspace_authority_generation(&self) -> u64 {
        self.workspace_authority
            .lock()
            .expect("workspace authority lock is not poisoned")
            .as_ref()
            .map_or(0, |(_, generation)| *generation)
    }

    #[must_use]
    pub fn may_mutate_workspace(&self, call: &ToolCall) -> bool {
        matches!(call.name.as_str(), "apply_patch" | "shell")
            || self
                .mcp
                .as_ref()
                .is_some_and(|mcp| mcp.may_mutate(&call.name))
    }

    #[must_use]
    pub fn tool_schemas(&self) -> Value {
        let mut schemas = crate::inference::tool_schemas()
            .as_array()
            .expect("native tool schemas are an array")
            .clone();
        if let Some(mcp) = &self.mcp {
            schemas.extend_from_slice(mcp.tool_schemas());
        }
        Value::Array(schemas)
    }

    #[must_use]
    pub fn mcp_discovery_metadata(&self) -> Option<Value> {
        self.mcp.as_ref().map(McpClientSet::discovery_metadata)
    }

    /// Read the live MCP registry identity used by the execution path.
    #[must_use]
    pub fn live_mcp_tool_identity(&self, tool_name: &str) -> Option<LiveToolIdentity> {
        self.mcp.as_ref()?.live_tool_identity(tool_name)
    }

    /// Digest of the complete live MCP registry/source authority used by the
    /// admission and execution paths.
    #[must_use]
    pub fn live_mcp_registry_digest(&self) -> Option<String> {
        self.mcp.as_ref().map(McpClientSet::live_registry_digest)
    }

    /// Monotonic MCP registry authority token used by the G5 publication CAS.
    #[must_use]
    pub fn live_mcp_registry_generation(&self) -> u64 {
        self.mcp
            .as_ref()
            .map_or(0, McpClientSet::live_registry_generation)
    }

    /// Qualification-only access to the live MCP registry. Production code
    /// never needs to mutate this object; tests use it to change the actual
    /// source after the provider proposal and before admission.
    #[doc(hidden)]
    pub fn mcp_mut_for_testing(&mut self) -> Option<&mut McpClientSet> {
        self.mcp.as_mut()
    }

    pub fn execute(&self, call: &ToolCall) -> Result<ToolResult, ToolError> {
        match call.name.as_str() {
            "read_file" => self.read_file(&call.arguments),
            "search" => self.search(&call.arguments),
            "apply_patch" => self.apply_patch(&call.arguments),
            "shell" => self.shell(&call.arguments),
            "git" => self.git(&call.arguments),
            _ => {
                let mcp = self
                    .mcp
                    .as_ref()
                    .ok_or_else(|| ToolError::UnknownTool(call.name.clone()))?;
                if !mcp.handles(&call.name) {
                    return Err(ToolError::UnknownTool(call.name.clone()));
                }
                // Ordinary model tool calls use the same host policy gate as
                // GenUI. A consequential route cannot be activated by model
                // data: it returns a structured confirmation-required result
                // without invoking MCP or creating a lifecycle event.
                if mcp.may_mutate(&call.name) {
                    let mut result = ToolResult::rejected(
                        &call.name,
                        "host confirmation is required for consequential MCP tools",
                    );
                    result.metadata = json!({
                        "authority_state": "confirmation_required",
                        "confirmation_required": true,
                        "tool": call.name,
                    });
                    return Ok(result);
                }
                mcp.execute_validated(call)
                    .ok_or_else(|| ToolError::UnknownTool(call.name.clone()))
            }
        }
    }

    fn validate_fresh_workspace_before_transport(
        &self,
        store: &EventStore,
        session_id: &str,
        principal: &str,
        catalog: &ActionCatalog,
        action_id: &str,
    ) -> Result<(), ToolError> {
        let workspace_state = self.workspace.state()?;
        let (fresh_digest, fresh_authorization_context) =
            derive_host_workspace_state_identity(session_id, principal, &workspace_state);
        catalog
            .validate_fresh_workspace_identity(
                store,
                action_id,
                &fresh_digest,
                &fresh_authorization_context,
            )
            .map_err(|error| ToolError::GenUi(error.to_string()))
    }

    fn mark_stale_execution_unknown(
        &self,
        store: &mut EventStore,
        session_id: &str,
        action_id: &str,
        identity: &Value,
    ) -> Result<(), ToolError> {
        store
            .mark_genui_action_unknown(
                session_id,
                action_id,
                identity,
                "workspace_changed_before_external_transport",
            )
            .map(|_| ())
            .map_err(|error| ToolError::GenUi(error.to_string()))
    }

    /// Execute a host-bound GenUI action through the canonical MCP validation
    /// path. Durable lifecycle events are written before and after transport
    /// invocation; an unresolved start is reconciled as unknown on restart and
    /// is never retried blindly.
    #[allow(clippy::too_many_arguments)]
    pub fn execute_genui_action(
        &self,
        store: &mut EventStore,
        session_id: &str,
        principal: &str,
        surface: &Surface,
        catalog: &ActionCatalog,
        action_id: &str,
        payload: Value,
        confirmation: Option<&HostConfirmation>,
    ) -> Result<ToolResult, ToolError> {
        catalog
            .validate_surface(surface, &HostCapabilities::default())
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let binding = catalog
            .resolve(action_id)
            .ok_or_else(|| ToolError::GenUi("action is not in host catalog".to_owned()))?;
        match binding.source_type() {
            ActionSourceType::Mcp => {}
            ActionSourceType::HostLocal => {
                return Err(ToolError::GenUi(
                    "host-local action requires the host-local adapter".to_owned(),
                ));
            }
            ActionSourceType::Auto => {
                return Err(ToolError::GenUi(
                    "source-unresolved action cannot be executed".to_owned(),
                ));
            }
        }
        if binding.session_id() != session_id
            || binding.principal() != principal
            || binding.state_digest()
                != surface
                    .actions
                    .iter()
                    .find(|a| a.id == action_id)
                    .map(|a| a.state_digest.as_str())
                    .unwrap_or("")
        {
            return Err(ToolError::GenUi(
                "session, principal, or state binding changed".to_owned(),
            ));
        }
        let mcp = self
            .mcp
            .as_ref()
            .ok_or_else(|| ToolError::GenUi("MCP is not configured".to_owned()))?;
        let (policy_version, policy_digest, requires_confirmation) = mcp
            .tool_policy_identity(binding.tool_name())
            .ok_or_else(|| ToolError::GenUi("MCP tool policy disappeared".to_owned()))?;
        mcp.validate_tool_identity_full(
            binding.tool_name(),
            binding.provider_id(),
            binding.server_id(),
            binding.schema_digest(),
            policy_version,
            &policy_digest,
        )
        .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let (_, _, remote_tool) = mcp
            .tool_identity(binding.tool_name())
            .ok_or_else(|| ToolError::GenUi("MCP remote tool disappeared".to_owned()))?;
        if binding.remote_tool_name() != remote_tool {
            return Err(ToolError::GenUi(
                "MCP remote tool identity changed".to_owned(),
            ));
        }
        if binding.policy_version() != policy_version
            || binding.policy_digest() != policy_digest
            || binding.requires_confirmation() != requires_confirmation
        {
            return Err(ToolError::GenUi(
                "host tool policy changed since presentation".to_owned(),
            ));
        }
        mcp.validate_tool_arguments(binding.tool_name(), &payload)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let identity = catalog
            .identity_for(action_id, &payload)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        if binding.requires_confirmation() {
            let supplied = confirmation
                .ok_or_else(|| ToolError::GenUi("host confirmation is required".to_owned()))?;
            if supplied.identity() != &identity {
                return Err(ToolError::GenUi(
                    "confirmation is stale or bound to another action".to_owned(),
                ));
            }
        }
        // The durable start and the transport are separated by a second
        // host-state check. Reconciliation is intentionally not performed on
        // this normal activation route: another independent connection may be
        // between its durable start and transport, and only an explicit
        // restart/recovery seam may convert that unresolved start to Unknown.
        catalog
            .validate_durable_current_action(store, action_id)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        store
            .start_genui_action(
                session_id,
                action_id,
                &identity,
                binding.requires_confirmation(),
            )
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        catalog
            .validate_current_action(action_id)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        catalog
            .validate_durable_current_action(store, action_id)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        mcp.validate_tool_identity_full(
            binding.tool_name(),
            binding.provider_id(),
            binding.server_id(),
            binding.schema_digest(),
            policy_version,
            &policy_digest,
        )
        .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let (_, _, remote_tool) = mcp
            .tool_identity(binding.tool_name())
            .ok_or_else(|| ToolError::GenUi("MCP remote tool disappeared".to_owned()))?;
        if binding.remote_tool_name() != remote_tool {
            return Err(ToolError::GenUi(
                "MCP remote tool identity changed".to_owned(),
            ));
        }
        if let Err(error) = self.validate_fresh_workspace_before_transport(
            store, session_id, principal, catalog, action_id,
        ) {
            self.mark_stale_execution_unknown(store, session_id, action_id, &identity)?;
            return Err(error);
        }
        let call = ToolCall {
            id: None,
            name: binding.tool_name().to_owned(),
            arguments: payload,
        };
        let result = mcp
            .execute_validated_authorized(&call)
            .ok_or_else(|| ToolError::UnknownTool(binding.tool_name().to_owned()))?;
        let result_digest = crate::genui::digest_value(&result.metadata);
        store
            .complete_genui_action(session_id, action_id, &identity, result.ok, &result_digest)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        Ok(result)
    }

    /// Continue an already-durable execution start through the same authority
    /// gate without appending a terminal event. This is the explicit process-
    /// death seam used by Crash-C; it still rechecks every live binding before
    /// invoking transport and never exposes the raw MCP client.
    #[allow(clippy::too_many_arguments)]
    pub fn execute_genui_action_after_durable_start(
        &self,
        store: &mut EventStore,
        session_id: &str,
        principal: &str,
        surface: &Surface,
        catalog: &ActionCatalog,
        action_id: &str,
        payload: Value,
    ) -> Result<ToolResult, ToolError> {
        catalog
            .validate_surface(surface, &HostCapabilities::default())
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let binding = catalog
            .resolve(action_id)
            .ok_or_else(|| ToolError::GenUi("action is not in host catalog".to_owned()))?;
        if binding.source_type() != ActionSourceType::Mcp {
            return Err(ToolError::GenUi(
                "durable continuation requires an explicit MCP source".to_owned(),
            ));
        }
        if binding.session_id() != session_id || binding.principal() != principal {
            return Err(ToolError::GenUi("session or principal changed".to_owned()));
        }
        let identity = catalog
            .identity_for(action_id, &payload)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let Some((kind, started_identity)) = store
            .replay_genui_action(session_id, action_id)
            .map_err(|error| ToolError::GenUi(error.to_string()))?
        else {
            return Err(ToolError::GenUi(
                "execution start is not durable for this exact identity".to_owned(),
            ));
        };
        if kind != crate::event::EventKind::GenUiActionExecutionStarted
            || started_identity != identity
        {
            return Err(ToolError::GenUi(
                "execution start is not a valid unresolved lifecycle state".to_owned(),
            ));
        }
        catalog
            .validate_current_action(action_id)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        catalog
            .validate_durable_current_action(store, action_id)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let mcp = self
            .mcp
            .as_ref()
            .ok_or_else(|| ToolError::GenUi("MCP is not configured".to_owned()))?;
        let (policy_version, policy_digest, requires_confirmation) = mcp
            .tool_policy_identity(binding.tool_name())
            .ok_or_else(|| ToolError::GenUi("MCP tool policy disappeared".to_owned()))?;
        if !requires_confirmation || !binding.requires_confirmation() {
            return Err(ToolError::GenUi(
                "Crash-C continuation requires a consequential policy".to_owned(),
            ));
        }
        if binding.policy_version() != policy_version || binding.policy_digest() != policy_digest {
            return Err(ToolError::GenUi(
                "MCP tool policy changed before Crash-C continuation".to_owned(),
            ));
        }
        mcp.validate_tool_identity_full(
            binding.tool_name(),
            binding.provider_id(),
            binding.server_id(),
            binding.schema_digest(),
            policy_version,
            &policy_digest,
        )
        .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let (_, _, remote_tool) = mcp
            .tool_identity(binding.tool_name())
            .ok_or_else(|| ToolError::GenUi("MCP remote tool disappeared".to_owned()))?;
        if binding.remote_tool_name() != remote_tool {
            return Err(ToolError::GenUi(
                "MCP remote tool identity changed".to_owned(),
            ));
        }
        mcp.validate_tool_arguments(binding.tool_name(), &payload)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        if let Err(error) = self.validate_fresh_workspace_before_transport(
            store, session_id, principal, catalog, action_id,
        ) {
            self.mark_stale_execution_unknown(store, session_id, action_id, &identity)?;
            return Err(error);
        }
        let call = ToolCall {
            id: None,
            name: binding.tool_name().to_owned(),
            arguments: payload,
        };
        mcp.execute_validated_authorized(&call)
            .ok_or_else(|| ToolError::UnknownTool(binding.tool_name().to_owned()))
    }

    /// Live-revalidate MCP authority before persisting a confirmation. This is
    /// the sole production confirmation path; the catalog's persistence
    /// primitive is crate-private and can only be reached after these checks.
    pub fn confirm_genui_action(
        &self,
        store: &mut EventStore,
        catalog: &ActionCatalog,
        confirmation: &HostConfirmation,
    ) -> Result<(), ToolError> {
        let binding = catalog
            .validate_confirmation_identity(confirmation)
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        if binding.source_type() != ActionSourceType::Mcp {
            return Err(ToolError::GenUi(
                "confirmation transport is not MCP for this binding".to_owned(),
            ));
        }
        let session_id = confirmation
            .identity()
            .get("session_id")
            .and_then(Value::as_str)
            .ok_or_else(|| ToolError::GenUi("confirmation has no session identity".to_owned()))?;
        catalog
            .validate_durable_current_action(store, binding.action_id())
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let mcp = self
            .mcp
            .as_ref()
            .ok_or_else(|| ToolError::GenUi("MCP is not configured".to_owned()))?;
        let (policy_version, policy_digest, requires_confirmation) = mcp
            .tool_policy_identity(binding.tool_name())
            .ok_or_else(|| ToolError::GenUi("MCP tool policy disappeared".to_owned()))?;
        mcp.validate_tool_identity_full(
            binding.tool_name(),
            binding.provider_id(),
            binding.server_id(),
            binding.schema_digest(),
            policy_version,
            &policy_digest,
        )
        .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let (_, _, remote_tool) = mcp
            .tool_identity(binding.tool_name())
            .ok_or_else(|| ToolError::GenUi("MCP remote tool disappeared".to_owned()))?;
        if binding.remote_tool_name() != remote_tool {
            return Err(ToolError::GenUi(
                "MCP remote tool identity changed before confirmation".to_owned(),
            ));
        }
        if binding.policy_version() != policy_version
            || binding.policy_digest() != policy_digest
            || binding.requires_confirmation() != requires_confirmation
        {
            return Err(ToolError::GenUi(
                "live MCP policy changed before confirmation".to_owned(),
            ));
        }
        mcp.validate_tool_arguments(binding.tool_name(), confirmation.payload())
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        let identity = catalog
            .identity_for(binding.action_id(), confirmation.payload())
            .map_err(|error| ToolError::GenUi(error.to_string()))?;
        if confirmation.identity() != &identity {
            return Err(ToolError::GenUi(
                "confirmation payload does not match its bound identity".to_owned(),
            ));
        }
        catalog
            .append_confirmed_after_live_validation(store, confirmation)
            .map_err(|error| ToolError::GenUi(format!("{session_id}: {error}")))
    }

    fn read_file(&self, arguments: &Value) -> Result<ToolResult, ToolError> {
        #[derive(Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Arguments {
            path: String,
        }
        let arguments: Arguments = parse_arguments("read_file", arguments)?;
        let path = self.workspace.resolve(&arguments.path)?;
        let bytes = fs::read(&path)?;
        if bytes.len() > self.limits.max_file_bytes {
            return Err(ToolError::InvalidArguments {
                tool: "read_file".to_owned(),
                message: format!("file exceeds {} byte limit", self.limits.max_file_bytes),
            });
        }
        let contents = String::from_utf8(bytes).map_err(|error| ToolError::InvalidArguments {
            tool: "read_file".to_owned(),
            message: format!("file is not UTF-8: {error}"),
        })?;
        Ok(success(
            "read_file",
            contents,
            json!({"path": arguments.path}),
        ))
    }

    fn search(&self, arguments: &Value) -> Result<ToolResult, ToolError> {
        #[derive(Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Arguments {
            query: String,
            #[serde(default)]
            path: Option<String>,
        }
        let arguments: Arguments = parse_arguments("search", arguments)?;
        if arguments.query.is_empty() {
            return Err(invalid("search", "query must not be empty"));
        }
        let relative = arguments.path.unwrap_or_else(|| ".".to_owned());
        self.workspace.resolve(&relative)?;
        let argv = vec![
            "rg".to_owned(),
            "--line-number".to_owned(),
            "--color=never".to_owned(),
            "--".to_owned(),
            arguments.query,
            relative,
        ];
        let outcome = run_command(
            self.workspace.root(),
            &argv,
            &BTreeMap::new(),
            None,
            self.limits.timeout,
            self.limits.max_output_bytes,
        )?;
        Ok(outcome.into_tool_result("search", json!({})))
    }

    fn apply_patch(&self, arguments: &Value) -> Result<ToolResult, ToolError> {
        let _guard = crate::mcp::acquire_publication_guard();
        #[derive(Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Arguments {
            patch: String,
        }
        let arguments: Arguments = parse_arguments("apply_patch", arguments)?;
        validate_patch(&self.workspace, &arguments.patch)?;
        let check = run_command(
            self.workspace.root(),
            &[
                "git".to_owned(),
                "apply".to_owned(),
                "--check".to_owned(),
                "-".to_owned(),
            ],
            &BTreeMap::new(),
            Some(arguments.patch.as_bytes()),
            self.limits.timeout,
            self.limits.max_output_bytes,
        )?;
        if !check.status.success() {
            return Ok(check.into_tool_result("apply_patch", json!({"phase": "check"})));
        }
        let outcome = run_command(
            self.workspace.root(),
            &["git".to_owned(), "apply".to_owned(), "-".to_owned()],
            &BTreeMap::new(),
            Some(arguments.patch.as_bytes()),
            self.limits.timeout,
            self.limits.max_output_bytes,
        )?;
        let result = outcome.into_tool_result("apply_patch", json!({"phase": "apply"}));
        if result.ok {
            self.note_workspace_mutation();
        }
        Ok(result)
    }

    fn shell(&self, arguments: &Value) -> Result<ToolResult, ToolError> {
        let _guard = crate::mcp::acquire_publication_guard();
        #[derive(Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Arguments {
            argv: Vec<String>,
            #[serde(default)]
            cwd: Option<String>,
            #[serde(default)]
            timeout_ms: Option<u64>,
            #[serde(default)]
            env: BTreeMap<String, String>,
        }
        let arguments: Arguments = parse_arguments("shell", arguments)?;
        if arguments.argv.is_empty() || arguments.argv[0].is_empty() {
            return Err(invalid("shell", "argv must contain a non-empty program"));
        }
        if arguments
            .env
            .keys()
            .any(|key| key.contains('=') || key.contains('\0'))
        {
            return Err(invalid("shell", "environment key is invalid"));
        }
        let cwd = self
            .workspace
            .resolve(arguments.cwd.as_deref().unwrap_or("."))?;
        if !cwd.is_dir() {
            return Err(invalid("shell", "cwd is not a directory"));
        }
        let timeout = arguments
            .timeout_ms
            .map_or(self.limits.timeout, Duration::from_millis)
            .min(self.limits.timeout);
        let outcome = run_command(
            &cwd,
            &arguments.argv,
            &arguments.env,
            None,
            timeout,
            self.limits.max_output_bytes,
        )?;
        let result = outcome.into_tool_result(
            "shell",
            json!({"argv": arguments.argv, "cwd": arguments.cwd, "timeout_ms": timeout.as_millis()}),
        );
        if result.ok {
            // A shell command may mutate any tracked or untracked authority;
            // conservatively advance the boundary for every successful run.
            self.note_workspace_mutation();
        }
        Ok(result)
    }

    fn git(&self, arguments: &Value) -> Result<ToolResult, ToolError> {
        #[derive(Deserialize)]
        #[serde(deny_unknown_fields)]
        struct Arguments {
            operation: String,
            #[serde(default)]
            revision: Option<String>,
        }
        let arguments: Arguments = parse_arguments("git", arguments)?;
        let argv = match arguments.operation.as_str() {
            "status" => vec!["git", "status", "--short", "--branch"],
            "diff" => vec!["git", "diff", "--no-ext-diff", "--"],
            "show" => {
                let revision = arguments
                    .revision
                    .as_deref()
                    .ok_or_else(|| invalid("git", "show requires revision"))?;
                if revision.starts_with('-') || revision.contains('\0') {
                    return Err(invalid("git", "revision is invalid"));
                }
                vec![
                    "git",
                    "show",
                    "--no-ext-diff",
                    "--format=fuller",
                    revision,
                    "--",
                ]
            }
            _ => return Err(invalid("git", "operation must be status, diff, or show")),
        };
        let argv: Vec<String> = argv.into_iter().map(str::to_owned).collect();
        let outcome = run_command(
            self.workspace.root(),
            &argv,
            &BTreeMap::new(),
            None,
            self.limits.timeout,
            self.limits.max_output_bytes,
        )?;
        Ok(outcome.into_tool_result("git", json!({"operation": arguments.operation})))
    }
}

fn parse_arguments<T: for<'de> Deserialize<'de>>(
    tool: &str,
    value: &Value,
) -> Result<T, ToolError> {
    serde_json::from_value(value.clone()).map_err(|error| ToolError::InvalidArguments {
        tool: tool.to_owned(),
        message: error.to_string(),
    })
}

fn invalid(tool: &str, message: &str) -> ToolError {
    ToolError::InvalidArguments {
        tool: tool.to_owned(),
        message: message.to_owned(),
    }
}

fn success(tool: &str, stdout: String, metadata: Value) -> ToolResult {
    ToolResult {
        tool: tool.to_owned(),
        tool_call_id: None,
        ok: true,
        exit_code: Some(0),
        timed_out: false,
        stdout,
        stderr: String::new(),
        output_truncated: false,
        metadata,
    }
}

fn validate_patch(workspace: &Workspace, patch: &str) -> Result<(), ToolError> {
    if patch.is_empty() || patch.contains('\0') {
        return Err(ToolError::InvalidPatch(
            "patch is empty or contains NUL".to_owned(),
        ));
    }
    let mut saw_old_path = false;
    let mut saw_new_path = false;
    for line in patch.lines() {
        let paths: Vec<&str> = if let Some(rest) = line.strip_prefix("diff --git ") {
            let parts: Vec<&str> = rest.split_whitespace().collect();
            if parts.len() != 2 {
                return Err(ToolError::InvalidPatch(
                    "diff header must contain exactly two paths".to_owned(),
                ));
            }
            parts
        } else if let Some(path) = line.strip_prefix("--- ") {
            saw_old_path = true;
            vec![path.split('\t').next().unwrap_or(path)]
        } else if let Some(path) = line.strip_prefix("+++ ") {
            saw_new_path = true;
            vec![path.split('\t').next().unwrap_or(path)]
        } else {
            continue;
        };
        for raw_path in paths {
            if raw_path == "/dev/null" {
                continue;
            }
            let relative_path = raw_path
                .strip_prefix("a/")
                .or_else(|| raw_path.strip_prefix("b/"))
                .unwrap_or(raw_path);
            workspace.resolve(relative_path)?;
        }
    }
    if !saw_old_path || !saw_new_path {
        return Err(ToolError::InvalidPatch(
            "missing unified diff file headers".to_owned(),
        ));
    }
    Ok(())
}

#[derive(Debug)]
pub(crate) struct CommandOutcome {
    pub(crate) status: ExitStatus,
    pub(crate) timed_out: bool,
    pub(crate) stdout: String,
    pub(crate) stderr: String,
    pub(crate) truncated: bool,
}

impl CommandOutcome {
    fn into_tool_result(self, tool: &str, metadata: Value) -> ToolResult {
        ToolResult {
            tool: tool.to_owned(),
            tool_call_id: None,
            ok: self.status.success() && !self.timed_out,
            exit_code: self.status.code(),
            timed_out: self.timed_out,
            stdout: self.stdout,
            stderr: self.stderr,
            output_truncated: self.truncated,
            metadata,
        }
    }
}

pub(crate) fn run_command(
    cwd: &Path,
    argv: &[String],
    env: &BTreeMap<String, String>,
    stdin: Option<&[u8]>,
    timeout: Duration,
    output_limit: usize,
) -> Result<CommandOutcome, std::io::Error> {
    let mut command = Command::new(&argv[0]);
    command
        .args(&argv[1..])
        .current_dir(cwd)
        .envs(env)
        .stdin(if stdin.is_some() {
            Stdio::piped()
        } else {
            Stdio::null()
        })
        .stdout(Stdio::piped())
        .stderr(Stdio::piped());
    let mut child = command.spawn()?;
    if let Some(input) = stdin {
        let mut child_stdin = child.stdin.take().expect("piped stdin exists");
        child_stdin.write_all(input)?;
    }
    let stdout_reader = bounded_reader(
        child.stdout.take().expect("piped stdout exists"),
        output_limit,
    );
    let stderr_reader = bounded_reader(
        child.stderr.take().expect("piped stderr exists"),
        output_limit,
    );
    let (status, timed_out) = wait_bounded(&mut child, timeout)?;
    let (stdout, stdout_truncated) = stdout_reader.join().expect("stdout reader did not panic")?;
    let (stderr, stderr_truncated) = stderr_reader.join().expect("stderr reader did not panic")?;
    Ok(CommandOutcome {
        status,
        timed_out,
        stdout: String::from_utf8_lossy(&stdout).into_owned(),
        stderr: String::from_utf8_lossy(&stderr).into_owned(),
        truncated: stdout_truncated || stderr_truncated,
    })
}

type ReaderHandle = thread::JoinHandle<std::io::Result<(Vec<u8>, bool)>>;

fn bounded_reader(mut reader: impl Read + Send + 'static, limit: usize) -> ReaderHandle {
    thread::spawn(move || {
        let mut retained = Vec::new();
        let mut buffer = [0_u8; 8192];
        let mut truncated = false;
        loop {
            let count = reader.read(&mut buffer)?;
            if count == 0 {
                break;
            }
            let remaining = limit.saturating_sub(retained.len());
            let keep = count.min(remaining);
            retained.extend_from_slice(&buffer[..keep]);
            truncated |= keep < count;
        }
        Ok((retained, truncated))
    })
}

fn wait_bounded(
    child: &mut Child,
    timeout: Duration,
) -> Result<(ExitStatus, bool), std::io::Error> {
    let started = Instant::now();
    loop {
        if let Some(status) = child.try_wait()? {
            return Ok((status, false));
        }
        if started.elapsed() >= timeout {
            child.kill()?;
            return child.wait().map(|status| (status, true));
        }
        thread::sleep(Duration::from_millis(5));
    }
}

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

    use serde_json::json;

    use crate::inference::ToolCall;
    use crate::workspace::Workspace;
    use crate::workspace::tests::git_fixture;

    use super::{NativeTools, ToolLimits};

    fn fixture() -> (tempfile::TempDir, NativeTools) {
        let directory = git_fixture();
        let workspace = Workspace::open(directory.path()).expect("workspace");
        let tools = NativeTools::new(
            workspace,
            ToolLimits {
                timeout: Duration::from_secs(2),
                max_output_bytes: 4096,
                max_file_bytes: 4096,
            },
        );
        (directory, tools)
    }

    fn call(name: &str, arguments: serde_json::Value) -> ToolCall {
        ToolCall {
            id: None,
            name: name.to_owned(),
            arguments,
        }
    }

    #[test]
    fn reads_allowed_file_and_searches() {
        let (_directory, tools) = fixture();
        let read = tools
            .execute(&call("read_file", json!({"path": "hello.txt"})))
            .expect("read");
        assert_eq!(read.stdout, "old\n");
        let search = tools
            .execute(&call("search", json!({"query": "old"})))
            .expect("search");
        assert!(search.ok);
        assert!(search.stdout.contains("hello.txt:1:old"));
    }

    #[test]
    fn applies_valid_patch_and_rejects_malformed_patch() {
        let (directory, tools) = fixture();
        let patch = "diff --git a/hello.txt b/hello.txt\n--- a/hello.txt\n+++ b/hello.txt\n@@ -1 +1 @@\n-old\n+new\n";
        let result = tools
            .execute(&call("apply_patch", json!({"patch": patch})))
            .expect("patch");
        assert!(result.ok, "{}", result.stderr);
        assert_eq!(
            fs::read_to_string(directory.path().join("hello.txt")).expect("read"),
            "new\n"
        );
        assert!(
            tools
                .execute(&call("apply_patch", json!({"patch": "not a patch"})))
                .is_err()
        );
    }

    #[test]
    fn accepts_standard_unified_diff_without_git_header() {
        let (directory, tools) = fixture();
        let patch = "--- a/hello.txt\n+++ b/hello.txt\n@@ -1 +1 @@\n-old\n+new\n";
        let result = tools
            .execute(&call("apply_patch", json!({"patch": patch})))
            .expect("patch");
        assert!(result.ok, "{}", result.stderr);
        assert_eq!(
            fs::read_to_string(directory.path().join("hello.txt")).expect("read"),
            "new\n"
        );
    }

    #[test]
    fn shell_reports_success_failure_and_timeout() {
        let (_directory, tools) = fixture();
        let success = tools
            .execute(&call("shell", json!({"argv": ["sh", "-c", "printf ok"]})))
            .expect("success");
        assert!(success.ok);
        assert_eq!(success.stdout, "ok");
        let failure = tools
            .execute(&call("shell", json!({"argv": ["sh", "-c", "exit 7"]})))
            .expect("failure");
        assert!(!failure.ok);
        assert_eq!(failure.exit_code, Some(7));
        let timeout = tools
            .execute(&call(
                "shell",
                json!({"argv": ["sh", "-c", "sleep 1"], "timeout_ms": 20}),
            ))
            .expect("timeout");
        assert!(!timeout.ok);
        assert!(timeout.timed_out);
    }

    #[test]
    fn git_tool_reports_state() {
        let (_directory, tools) = fixture();
        let result = tools
            .execute(&call("git", json!({"operation": "status"})))
            .expect("git status");
        assert!(result.ok);
        assert!(result.stdout.starts_with("##"));
    }
}