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

use async_trait::async_trait;
use codex_protocol::ThreadId;
use codex_protocol::models::FunctionCallOutputBody;
use codex_protocol::models::ShellCommandToolCallParams;
use codex_protocol::models::ShellToolCallParams;
use std::sync::Arc;

use crate::codex::TurnContext;
use crate::exec::ExecParams;
use crate::exec_env::create_env;
use crate::exec_policy::ExecApprovalRequest;
use crate::features::Feature;
use crate::function_tool::FunctionCallError;
use crate::is_safe_command::is_known_safe_command;
use crate::protocol::ExecCommandSource;
use crate::shell::Shell;
use crate::shell::ShellType;
use crate::skills::SKILL_APPROVAL_DECLINED_MESSAGE;
use crate::skills::SkillLoadOutcome;
use crate::skills::SkillMetadata;
use crate::skills::detect_implicit_skill_executable_invocation_for_tokens;
use crate::skills::ensure_skill_approval_for_command;
use crate::skills::maybe_emit_implicit_skill_invocation;
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::handlers::apply_patch::intercept_apply_patch;
use crate::tools::handlers::normalize_and_validate_additional_permissions;
use crate::tools::handlers::parse_arguments;
use crate::tools::orchestrator::ToolOrchestrator;
use crate::tools::registry::ToolHandler;
use crate::tools::registry::ToolKind;
use crate::tools::runtimes::shell::ShellRequest;
use crate::tools::runtimes::shell::ShellRuntime;
use crate::tools::runtimes::shell::ShellRuntimeBackend;
use crate::tools::sandboxing::ExecApprovalRequirement;
use crate::tools::sandboxing::ToolCtx;
use crate::tools::spec::ShellCommandBackendConfig;
use codex_protocol::models::PermissionProfile;

pub struct ShellHandler;

#[derive(Clone, Copy, Debug, Eq, PartialEq)]
enum ShellCommandBackend {
    Classic,
    ZshFork,
}

pub struct ShellCommandHandler {
    backend: ShellCommandBackend,
}

const SKILL_SHELL_COMMAND_APPROVAL_REASON: &str =
    "This command runs a skill script and requires approval.";

struct RunExecLikeArgs {
    tool_name: String,
    exec_params: ExecParams,
    additional_permissions: Option<PermissionProfile>,
    prefix_rule: Option<Vec<String>>,
    session: Arc<crate::codex::Session>,
    turn: Arc<TurnContext>,
    tracker: crate::tools::context::SharedTurnDiffTracker,
    call_id: String,
    freeform: bool,
    shell_runtime_backend: ShellRuntimeBackend,
}

impl ShellHandler {
    fn to_exec_params(
        params: &ShellToolCallParams,
        turn_context: &TurnContext,
        thread_id: ThreadId,
    ) -> ExecParams {
        ExecParams {
            command: params.command.clone(),
            original_command: shlex::try_join(params.command.iter().map(String::as_str))
                .unwrap_or_else(|_| params.command.join(" ")),
            cwd: turn_context.resolve_path(params.workdir.clone()),
            expiration: params.timeout_ms.into(),
            env: create_env(&turn_context.shell_environment_policy, Some(thread_id)),
            network: turn_context.network.clone(),
            sandbox_permissions: params.sandbox_permissions.unwrap_or_default(),
            windows_sandbox_level: turn_context.windows_sandbox_level,
            justification: params.justification.clone(),
            arg0: None,
        }
    }
}

impl ShellCommandHandler {
    fn shell_runtime_backend(&self) -> ShellRuntimeBackend {
        match self.backend {
            ShellCommandBackend::Classic => ShellRuntimeBackend::ShellCommandClassic,
            ShellCommandBackend::ZshFork => ShellRuntimeBackend::ShellCommandZshFork,
        }
    }

    fn resolve_use_login_shell(
        login: Option<bool>,
        allow_login_shell: bool,
    ) -> Result<bool, FunctionCallError> {
        if !allow_login_shell && login == Some(true) {
            return Err(FunctionCallError::RespondToModel(
                "login shell is disabled by config; omit `login` or set it to false.".to_string(),
            ));
        }

        Ok(login.unwrap_or(allow_login_shell))
    }

    fn base_command(shell: &Shell, command: &str, use_login_shell: bool) -> Vec<String> {
        shell.derive_exec_args(command, use_login_shell)
    }

    fn to_exec_params(
        params: &ShellCommandToolCallParams,
        session: &crate::codex::Session,
        turn_context: &TurnContext,
        thread_id: ThreadId,
        allow_login_shell: bool,
    ) -> Result<ExecParams, FunctionCallError> {
        let shell = session.user_shell();
        let use_login_shell = Self::resolve_use_login_shell(params.login, allow_login_shell)?;
        let command = Self::base_command(shell.as_ref(), &params.command, use_login_shell);

        Ok(ExecParams {
            command,
            original_command: params.command.clone(),
            cwd: turn_context.resolve_path(params.workdir.clone()),
            expiration: params.timeout_ms.into(),
            env: create_env(&turn_context.shell_environment_policy, Some(thread_id)),
            network: turn_context.network.clone(),
            sandbox_permissions: params.sandbox_permissions.unwrap_or_default(),
            windows_sandbox_level: turn_context.windows_sandbox_level,
            justification: params.justification.clone(),
            arg0: None,
        })
    }
}

impl From<ShellCommandBackendConfig> for ShellCommandHandler {
    fn from(config: ShellCommandBackendConfig) -> Self {
        let backend = match config {
            ShellCommandBackendConfig::Classic => ShellCommandBackend::Classic,
            ShellCommandBackendConfig::ZshFork => ShellCommandBackend::ZshFork,
        };
        Self { backend }
    }
}

#[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 is_mutating(&self, invocation: &ToolInvocation) -> bool {
        match &invocation.payload {
            ToolPayload::Function { arguments } => {
                serde_json::from_str::<ShellToolCallParams>(arguments)
                    .map(|params| !is_known_safe_command(&params.command))
                    .unwrap_or(true)
            }
            ToolPayload::LocalShell { params } => !is_known_safe_command(&params.command),
            _ => true, // unknown payloads => assume mutating
        }
    }

    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 = parse_arguments(&arguments)?;
                let prefix_rule = params.prefix_rule.clone();
                let exec_params =
                    Self::to_exec_params(&params, turn.as_ref(), session.conversation_id);
                Self::run_exec_like(RunExecLikeArgs {
                    tool_name: tool_name.clone(),
                    exec_params,
                    additional_permissions: params.additional_permissions.clone(),
                    prefix_rule,
                    session,
                    turn,
                    tracker,
                    call_id,
                    freeform: false,
                    shell_runtime_backend: ShellRuntimeBackend::Generic,
                })
                .await
            }
            ToolPayload::LocalShell { params } => {
                let exec_params =
                    Self::to_exec_params(&params, turn.as_ref(), session.conversation_id);
                Self::run_exec_like(RunExecLikeArgs {
                    tool_name: tool_name.clone(),
                    exec_params,
                    additional_permissions: None,
                    prefix_rule: None,
                    session,
                    turn,
                    tracker,
                    call_id,
                    freeform: false,
                    shell_runtime_backend: ShellRuntimeBackend::Generic,
                })
                .await
            }
            _ => Err(FunctionCallError::RespondToModel(format!(
                "unsupported payload for shell handler: {tool_name}"
            ))),
        }
    }
}

#[async_trait]
impl ToolHandler for ShellCommandHandler {
    fn kind(&self) -> ToolKind {
        ToolKind::Function
    }

    fn matches_kind(&self, payload: &ToolPayload) -> bool {
        matches!(payload, ToolPayload::Function { .. })
    }

    async fn is_mutating(&self, invocation: &ToolInvocation) -> bool {
        let ToolPayload::Function { arguments } = &invocation.payload else {
            return true;
        };

        serde_json::from_str::<ShellCommandToolCallParams>(arguments)
            .map(|params| {
                let use_login_shell = match Self::resolve_use_login_shell(
                    params.login,
                    invocation.turn.tools_config.allow_login_shell,
                ) {
                    Ok(use_login_shell) => use_login_shell,
                    Err(_) => return true,
                };
                let shell = invocation.session.user_shell();
                let command = Self::base_command(shell.as_ref(), &params.command, use_login_shell);
                !is_known_safe_command(&command)
            })
            .unwrap_or(true)
    }

    async fn handle(&self, invocation: ToolInvocation) -> Result<ToolOutput, FunctionCallError> {
        let ToolInvocation {
            session,
            turn,
            tracker,
            call_id,
            tool_name,
            payload,
            ..
        } = invocation;

        let ToolPayload::Function { arguments } = payload else {
            return Err(FunctionCallError::RespondToModel(format!(
                "unsupported payload for shell_command handler: {tool_name}"
            )));
        };

        let params: ShellCommandToolCallParams = parse_arguments(&arguments)?;
        let prefix_rule = params.prefix_rule.clone();
        let exec_params = Self::to_exec_params(
            &params,
            session.as_ref(),
            turn.as_ref(),
            session.conversation_id,
            turn.tools_config.allow_login_shell,
        )?;
        ShellHandler::run_exec_like(RunExecLikeArgs {
            tool_name,
            exec_params,
            additional_permissions: params.additional_permissions.clone(),
            prefix_rule,
            session,
            turn,
            tracker,
            call_id,
            freeform: true,
            shell_runtime_backend: self.shell_runtime_backend(),
        })
        .await
    }
}

impl ShellHandler {
    fn detect_skill_shell_command(
        outcome: &SkillLoadOutcome,
        shell: &Shell,
        command: &[String],
        shell_runtime_backend: ShellRuntimeBackend,
    ) -> Option<SkillMetadata> {
        if shell_runtime_backend != ShellRuntimeBackend::ShellCommandClassic
            || shell.shell_type != ShellType::Zsh
        {
            return None;
        }

        let commands = crate::bash::parse_shell_lc_plain_commands(command)?;
        let [inner_command] = commands.as_slice() else {
            return None;
        };
        let (skill, _path) =
            detect_implicit_skill_executable_invocation_for_tokens(outcome, inner_command)?;
        Some(skill)
    }

    async fn run_exec_like(args: RunExecLikeArgs) -> Result<ToolOutput, FunctionCallError> {
        let RunExecLikeArgs {
            tool_name,
            exec_params,
            additional_permissions,
            prefix_rule,
            session,
            turn,
            tracker,
            call_id,
            freeform,
            shell_runtime_backend,
        } = args;

        let mut exec_params = exec_params;
        let dependency_env = session.dependency_env().await;
        if !dependency_env.is_empty() {
            exec_params.env.extend(dependency_env.clone());
        }

        let mut explicit_env_overrides = turn.shell_environment_policy.r#set.clone();
        for key in dependency_env.keys() {
            if let Some(value) = exec_params.env.get(key) {
                explicit_env_overrides.insert(key.clone(), value.clone());
            }
        }

        let request_permission_enabled = session.features().enabled(Feature::RequestPermissions);
        let normalized_additional_permissions = normalize_and_validate_additional_permissions(
            request_permission_enabled,
            turn.approval_policy.value(),
            exec_params.sandbox_permissions,
            additional_permissions,
            &exec_params.cwd,
        )
        .map_err(FunctionCallError::RespondToModel)?;

        // Approval policy guard for explicit escalation in non-OnRequest modes.
        if exec_params
            .sandbox_permissions
            .requires_additional_permissions()
            && !matches!(
                turn.approval_policy.value(),
                codex_protocol::protocol::AskForApproval::OnRequest
            )
        {
            let approval_policy = turn.approval_policy.value();
            return Err(FunctionCallError::RespondToModel(format!(
                "approval policy is {approval_policy:?}; reject command — you should not ask for escalated permissions if the approval policy is {approval_policy:?}"
            )));
        }
        let original_command = exec_params.original_command.as_str();
        if !ensure_skill_approval_for_command(
            session.as_ref(),
            turn.as_ref(),
            &call_id,
            original_command,
            exec_params.cwd.as_path(),
        )
        .await
        {
            return Err(FunctionCallError::RespondToModel(
                SKILL_APPROVAL_DECLINED_MESSAGE.to_string(),
            ));
        }
        let workdir = exec_params.cwd.to_string_lossy().into_owned();
        maybe_emit_implicit_skill_invocation(
            session.as_ref(),
            turn.as_ref(),
            original_command,
            Some(workdir.as_str()),
        )
        .await;

        // Intercept apply_patch if present.
        if let Some(output) = intercept_apply_patch(
            &exec_params.command,
            &exec_params.cwd,
            exec_params.expiration.timeout_ms(),
            session.clone(),
            turn.clone(),
            Some(&tracker),
            &call_id,
            tool_name.as_str(),
        )
        .await?
        {
            return Ok(output);
        }

        let source = ExecCommandSource::Agent;
        let emitter = ToolEmitter::shell(
            exec_params.command.clone(),
            exec_params.cwd.clone(),
            source,
            freeform,
        );
        let event_ctx = ToolEventCtx::new(session.as_ref(), turn.as_ref(), &call_id, None);
        emitter.begin(event_ctx).await;

        let (effective_sandbox_policy, exec_approval_requirement, additional_permissions) =
            if turn.features.enabled(Feature::SkillShellCommandSandbox) {
                let user_shell = session.user_shell();
                let matched_skill = Self::detect_skill_shell_command(
                    turn.turn_skills.outcome.as_ref(),
                    user_shell.as_ref(),
                    &exec_params.command,
                    shell_runtime_backend,
                );
                let additional_permissions = matched_skill
                    .as_ref()
                    .and_then(|skill| skill.permission_profile.clone());
                let effective_sandbox_policy = matched_skill
                    .as_ref()
                    .and_then(|skill| skill.permissions.as_ref())
                    .map(|permissions| permissions.sandbox_policy.get().clone())
                    .unwrap_or_else(|| turn.sandbox_policy.get().clone());
                let exec_approval_requirement = if matched_skill.is_some() {
                    ExecApprovalRequirement::NeedsApproval {
                        reason: Some(SKILL_SHELL_COMMAND_APPROVAL_REASON.to_string()),
                        proposed_execpolicy_amendment: None,
                    }
                } else {
                    session
                        .services
                        .exec_policy
                        .create_exec_approval_requirement_for_command(ExecApprovalRequest {
                            command: &exec_params.command,
                            approval_policy: turn.approval_policy.value(),
                            sandbox_policy: &effective_sandbox_policy,
                            sandbox_permissions: exec_params.sandbox_permissions,
                            prefix_rule,
                        })
                        .await
                };
                (
                    effective_sandbox_policy,
                    exec_approval_requirement,
                    additional_permissions,
                )
            } else {
                let effective_sandbox_policy = turn.sandbox_policy.get().clone();
                let exec_approval_requirement = session
                    .services
                    .exec_policy
                    .create_exec_approval_requirement_for_command(ExecApprovalRequest {
                        command: &exec_params.command,
                        approval_policy: turn.approval_policy.value(),
                        sandbox_policy: &effective_sandbox_policy,
                        sandbox_permissions: exec_params.sandbox_permissions,
                        prefix_rule,
                    })
                    .await;
                (
                    effective_sandbox_policy,
                    exec_approval_requirement,
                    normalized_additional_permissions,
                )
            };

        let req = ShellRequest {
            command: exec_params.command.clone(),
            cwd: exec_params.cwd.clone(),
            timeout_ms: exec_params.expiration.timeout_ms(),
            env: exec_params.env.clone(),
            explicit_env_overrides,
            network: exec_params.network.clone(),
            sandbox_permissions: exec_params.sandbox_permissions,
            additional_permissions,
            justification: exec_params.justification.clone(),
            exec_approval_requirement,
            effective_sandbox_policy,
        };
        let mut orchestrator = ToolOrchestrator::new();
        let mut runtime = {
            use ShellRuntimeBackend::*;
            match shell_runtime_backend {
                Generic => ShellRuntime::new(),
                backend @ (ShellCommandClassic | ShellCommandZshFork) => {
                    ShellRuntime::for_shell_command(backend)
                }
            }
        };
        let tool_ctx = ToolCtx {
            session: session.clone(),
            turn: turn.clone(),
            call_id: call_id.clone(),
            tool_name,
        };
        let out = orchestrator
            .run(
                &mut runtime,
                &req,
                &tool_ctx,
                &turn,
                turn.approval_policy.value(),
            )
            .await
            .map(|result| result.output);
        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 {
            body: FunctionCallOutputBody::Text(content),
            success: Some(true),
        })
    }
}

#[cfg(test)]
mod tests {
    use std::collections::HashMap;
    use std::path::PathBuf;
    use std::sync::Arc;

    use codex_protocol::models::ShellCommandToolCallParams;
    use codex_protocol::protocol::SkillScope;
    use pretty_assertions::assert_eq;

    use crate::codex::make_session_and_context;
    use crate::exec_env::create_env;
    use crate::is_safe_command::is_known_safe_command;
    use crate::powershell::try_find_powershell_executable_blocking;
    use crate::powershell::try_find_pwsh_executable_blocking;
    use crate::sandboxing::SandboxPermissions;
    use crate::shell::Shell;
    use crate::shell::ShellType;
    use crate::shell_snapshot::ShellSnapshot;
    use crate::skills::SkillLoadOutcome;
    use crate::skills::SkillMetadata;
    use crate::tools::handlers::ShellCommandHandler;
    use crate::tools::handlers::ShellHandler;
    use crate::tools::runtimes::shell::ShellRuntimeBackend;
    use tokio::sync::watch;

    fn test_skill_metadata(path_to_skills_md: PathBuf) -> SkillMetadata {
        SkillMetadata {
            name: "test-skill".to_string(),
            description: "test".to_string(),
            short_description: None,
            interface: None,
            dependencies: None,
            policy: None,
            permission_profile: None,
            permissions: None,
            path_to_skills_md,
            scope: SkillScope::User,
        }
    }

    /// The logic for is_known_safe_command() has heuristics for known shells,
    /// so we must ensure the commands generated by [ShellCommandHandler] can be
    /// recognized as safe if the `command` is safe.
    #[test]
    fn commands_generated_by_shell_command_handler_can_be_matched_by_is_known_safe_command() {
        let bash_shell = Shell {
            shell_type: ShellType::Bash,
            shell_path: PathBuf::from("/bin/bash"),
            shell_snapshot: crate::shell::empty_shell_snapshot_receiver(),
        };
        assert_safe(&bash_shell, "ls -la");

        let zsh_shell = Shell {
            shell_type: ShellType::Zsh,
            shell_path: PathBuf::from("/bin/zsh"),
            shell_snapshot: crate::shell::empty_shell_snapshot_receiver(),
        };
        assert_safe(&zsh_shell, "ls -la");

        if let Some(path) = try_find_powershell_executable_blocking() {
            let powershell = Shell {
                shell_type: ShellType::PowerShell,
                shell_path: path.to_path_buf(),
                shell_snapshot: crate::shell::empty_shell_snapshot_receiver(),
            };
            assert_safe(&powershell, "ls -Name");
        }

        if let Some(path) = try_find_pwsh_executable_blocking() {
            let pwsh = Shell {
                shell_type: ShellType::PowerShell,
                shell_path: path.to_path_buf(),
                shell_snapshot: crate::shell::empty_shell_snapshot_receiver(),
            };
            assert_safe(&pwsh, "ls -Name");
        }
    }

    fn assert_safe(shell: &Shell, command: &str) {
        assert!(is_known_safe_command(
            &shell.derive_exec_args(command, /* use_login_shell */ true)
        ));
        assert!(is_known_safe_command(
            &shell.derive_exec_args(command, /* use_login_shell */ false)
        ));
    }

    #[tokio::test]
    async fn shell_command_handler_to_exec_params_uses_session_shell_and_turn_context() {
        let (session, turn_context) = make_session_and_context().await;

        let command = "echo hello".to_string();
        let workdir = Some("subdir".to_string());
        let login = None;
        let timeout_ms = Some(1234);
        let sandbox_permissions = SandboxPermissions::RequireEscalated;
        let justification = Some("because tests".to_string());

        let expected_command = session.user_shell().derive_exec_args(&command, true);
        let expected_cwd = turn_context.resolve_path(workdir.clone());
        let expected_env = create_env(
            &turn_context.shell_environment_policy,
            Some(session.conversation_id),
        );

        let params = ShellCommandToolCallParams {
            command,
            workdir,
            login,
            timeout_ms,
            sandbox_permissions: Some(sandbox_permissions),
            additional_permissions: None,
            prefix_rule: None,
            justification: justification.clone(),
        };

        let exec_params = ShellCommandHandler::to_exec_params(
            &params,
            &session,
            &turn_context,
            session.conversation_id,
            true,
        )
        .expect("login shells should be allowed");

        // ExecParams cannot derive Eq due to the CancellationToken field, so we manually compare the fields.
        assert_eq!(exec_params.command, expected_command);
        assert_eq!(exec_params.cwd, expected_cwd);
        assert_eq!(exec_params.env, expected_env);
        assert_eq!(exec_params.network, turn_context.network);
        assert_eq!(exec_params.expiration.timeout_ms(), timeout_ms);
        assert_eq!(exec_params.sandbox_permissions, sandbox_permissions);
        assert_eq!(exec_params.justification, justification);
        assert_eq!(exec_params.arg0, None);
    }

    #[test]
    fn shell_command_handler_respects_explicit_login_flag() {
        let (_tx, shell_snapshot) = watch::channel(Some(Arc::new(ShellSnapshot {
            path: PathBuf::from("/tmp/snapshot.sh"),
            cwd: PathBuf::from("/tmp"),
        })));
        let shell = Shell {
            shell_type: ShellType::Bash,
            shell_path: PathBuf::from("/bin/bash"),
            shell_snapshot,
        };

        let login_command = ShellCommandHandler::base_command(&shell, "echo login shell", true);
        assert_eq!(
            login_command,
            shell.derive_exec_args("echo login shell", true)
        );

        let non_login_command =
            ShellCommandHandler::base_command(&shell, "echo non login shell", false);
        assert_eq!(
            non_login_command,
            shell.derive_exec_args("echo non login shell", false)
        );
    }

    #[tokio::test]
    async fn shell_command_handler_defaults_to_non_login_when_disallowed() {
        let (session, turn_context) = make_session_and_context().await;
        let params = ShellCommandToolCallParams {
            command: "echo hello".to_string(),
            workdir: None,
            login: None,
            timeout_ms: None,
            sandbox_permissions: None,
            additional_permissions: None,
            prefix_rule: None,
            justification: None,
        };

        let exec_params = ShellCommandHandler::to_exec_params(
            &params,
            &session,
            &turn_context,
            session.conversation_id,
            false,
        )
        .expect("non-login shells should still be allowed");

        assert_eq!(
            exec_params.command,
            session.user_shell().derive_exec_args("echo hello", false)
        );
    }

    #[test]
    fn shell_command_handler_rejects_login_when_disallowed() {
        let err = ShellCommandHandler::resolve_use_login_shell(Some(true), false)
            .expect_err("explicit login should be rejected");

        assert!(
            err.to_string()
                .contains("login shell is disabled by config"),
            "unexpected error: {err}"
        );
    }

    #[test]
    fn detect_skill_shell_command_matches_direct_absolute_executable() {
        let shell = Shell {
            shell_type: ShellType::Zsh,
            shell_path: PathBuf::from("/bin/zsh"),
            shell_snapshot: crate::shell::empty_shell_snapshot_receiver(),
        };
        let skill = test_skill_metadata(PathBuf::from("/tmp/skill-test/SKILL.md"));
        let outcome = SkillLoadOutcome {
            implicit_skills_by_scripts_dir: Arc::new(HashMap::from([(
                PathBuf::from("/tmp/skill-test/scripts"),
                skill,
            )])),
            ..Default::default()
        };
        let command = shell.derive_exec_args("/tmp/skill-test/scripts/run-tool", true);

        let found = ShellHandler::detect_skill_shell_command(
            &outcome,
            &shell,
            &command,
            ShellRuntimeBackend::ShellCommandClassic,
        );

        assert_eq!(
            found.map(|skill| skill.name),
            Some("test-skill".to_string())
        );
    }

    #[test]
    fn detect_skill_shell_command_ignores_multi_command_shell_script() {
        let shell = Shell {
            shell_type: ShellType::Zsh,
            shell_path: PathBuf::from("/bin/zsh"),
            shell_snapshot: crate::shell::empty_shell_snapshot_receiver(),
        };
        let skill = test_skill_metadata(PathBuf::from("/tmp/skill-test/SKILL.md"));
        let outcome = SkillLoadOutcome {
            implicit_skills_by_scripts_dir: Arc::new(HashMap::from([(
                PathBuf::from("/tmp/skill-test/scripts"),
                skill,
            )])),
            ..Default::default()
        };
        let command = shell.derive_exec_args("/tmp/skill-test/scripts/run-tool && echo done", true);

        let found = ShellHandler::detect_skill_shell_command(
            &outcome,
            &shell,
            &command,
            ShellRuntimeBackend::ShellCommandClassic,
        );

        assert_eq!(found, None);
    }

    #[test]
    fn detect_skill_shell_command_requires_classic_backend() {
        let shell = Shell {
            shell_type: ShellType::Zsh,
            shell_path: PathBuf::from("/bin/zsh"),
            shell_snapshot: crate::shell::empty_shell_snapshot_receiver(),
        };
        let skill = test_skill_metadata(PathBuf::from("/tmp/skill-test/SKILL.md"));
        let outcome = SkillLoadOutcome {
            implicit_skills_by_scripts_dir: Arc::new(HashMap::from([(
                PathBuf::from("/tmp/skill-test/scripts"),
                skill,
            )])),
            ..Default::default()
        };
        let command = shell.derive_exec_args("/tmp/skill-test/scripts/run-tool", true);

        let found = ShellHandler::detect_skill_shell_command(
            &outcome,
            &shell,
            &command,
            ShellRuntimeBackend::ShellCommandZshFork,
        );

        assert_eq!(found, None);
    }
}