hanzo-mcp 0.8.11__py3-none-any.whl → 0.9.0__py3-none-any.whl

hanzo_mcp/tools/shell/bash_session_executor.py

@@ -44,9 +44,7 @@ class BashSessionExecutor:
         self.fast_test_mode: bool = fast_test_mode
 
         # If no session manager is provided, create a non-singleton instance to avoid shared state
-        self.session_manager: SessionManager = session_manager or SessionManager(
-            use_singleton=False
-        )
+        self.session_manager: SessionManager = session_manager or SessionManager(use_singleton=False)
 
         # Excluded commands or patterns (for compatibility)
         self.excluded_commands: list[str] = ["rm"]
@@ -146,9 +144,7 @@ class BashSessionExecutor:
         Returns:
             CommandResult containing execution results
         """
-        self._log(
-            f"Executing command: {command} (is_input={is_input}, blocking={blocking})"
-        )
+        self._log(f"Executing command: {command} (is_input={is_input}, blocking={blocking})")
 
         # Check if the command is allowed (skip for input to running processes)
         if not is_input and not self.is_command_allowed(command):
@@ -183,9 +179,7 @@ class BashSessionExecutor:
             if session is None:
                 # Use faster timeouts and polling for tests
                 if self.fast_test_mode:
-                    timeout_seconds = (
-                        10  # Faster timeout for tests but not too aggressive
-                    )
+                    timeout_seconds = 10  # Faster timeout for tests but not too aggressive
                     poll_interval = 0.2  # Faster polling for tests but still reasonable
                 else:
                     timeout_seconds = 30  # Default timeout
@@ -206,9 +200,7 @@ class BashSessionExecutor:
                         self._log(f"Failed to set environment variable {key}")
 
             # Execute the command with enhanced parameters
-            result = session.execute(
-                command=command, is_input=is_input, blocking=blocking, timeout=timeout
-            )
+            result = session.execute(command=command, is_input=is_input, blocking=blocking, timeout=timeout)
 
             # Add session_id to the result
             result.session_id = effective_session_id
@@ -257,9 +249,7 @@ class BashSessionExecutor:
 
             # Wait for completion with timeout
             try:
-                stdout, stderr = await asyncio.wait_for(
-                    process.communicate(), timeout=timeout
-                )
+                stdout, stderr = await asyncio.wait_for(process.communicate(), timeout=timeout)
             except asyncio.TimeoutError:
                 # Kill the process if it times out
                 process.kill()

hanzo_mcp/tools/shell/bash_tool.py

@@ -28,9 +28,7 @@ class BashTool(BaseScriptTool):
             env: Optional[dict[str, str]] = None,
             timeout: Optional[int] = None,
         ) -> str:
-            return await tool_self.run(
-                ctx, command=command, cwd=cwd, env=env, timeout=timeout
-            )
+            return await tool_self.run(ctx, command=command, cwd=cwd, env=env, timeout=timeout)
 
     async def call(self, ctx: MCPContext, **params) -> str:
         """Call the tool with arguments."""
@@ -71,7 +69,7 @@ bash "npm run dev" --cwd ./frontend  # Auto-backgrounds if needed"""
                 if Path(path).exists():
                     return path
             return "cmd.exe"  # Fall back to cmd if no bash found
-        
+
         # On Unix-like systems, always use bash
         return "bash"
 
@@ -112,9 +110,7 @@ bash "npm run dev" --cwd ./frontend  # Auto-backgrounds if needed"""
         work_dir = Path(cwd).resolve() if cwd else Path.cwd()
 
         # Always use execute_sync which now has auto-backgrounding
-        output = await self.execute_sync(
-            command, cwd=work_dir, env=env, timeout=timeout
-        )
+        output = await self.execute_sync(command, cwd=work_dir, env=env, timeout=timeout)
         return output if output else "Command completed successfully (no output)"
 
 

hanzo_mcp/tools/shell/command_executor.py

@@ -27,9 +27,7 @@ class CommandExecutor:
     comprehensive error handling, permissions checking, and progress tracking.
     """
 
-    def __init__(
-        self, permission_manager: PermissionManager, verbose: bool = False
-    ) -> None:
+    def __init__(self, permission_manager: PermissionManager, verbose: bool = False) -> None:
         """Initialize command execution.
 
         Args:
@@ -94,9 +92,7 @@ class CommandExecutor:
             user_shell = os.environ.get("SHELL", "/bin/bash")
             return os.path.basename(user_shell).lower(), user_shell
 
-    def _format_win32_shell_command(
-        self, shell_basename, user_shell, command, use_login_shell=True
-    ):
+    def _format_win32_shell_command(self, shell_basename, user_shell, command, use_login_shell=True):
         """Format a command for execution with the appropriate Windows shell.
 
         Args:
@@ -250,9 +246,7 @@ class CommandExecutor:
 
         # Check if the command is allowed
         if not self.is_command_allowed(command):
-            return CommandResult(
-                return_code=1, error_message=f"Command not allowed: {command}"
-            )
+            return CommandResult(return_code=1, error_message=f"Command not allowed: {command}")
 
         # Check working directory permissions if specified
         if cwd:
@@ -263,9 +257,7 @@ class CommandExecutor:
                 )
 
             if not self.permission_manager.is_path_allowed(cwd):
-                return CommandResult(
-                    return_code=1, error_message=f"Working directory not allowed: {cwd}"
-                )
+                return CommandResult(return_code=1, error_message=f"Working directory not allowed: {cwd}")
 
         # Set up environment
         command_env: dict[str, str] = os.environ.copy()
@@ -281,9 +273,7 @@ class CommandExecutor:
                 self._log(f"Using shell on Windows: {user_shell} ({shell_basename})")
 
                 # Format command using helper method
-                shell_cmd = self._format_win32_shell_command(
-                    shell_basename, user_shell, command, use_login_shell
-                )
+                shell_cmd = self._format_win32_shell_command(shell_basename, user_shell, command, use_login_shell)
 
                 # Use shell for command execution
                 process = await asyncio.create_subprocess_shell(
@@ -312,19 +302,13 @@ class CommandExecutor:
                         self._log(f"Escaped command: {escaped_command}")
 
                         # Wrap command with appropriate shell invocation
-                        if (
-                            shell_basename == "zsh"
-                            or shell_basename == "bash"
-                            or shell_basename == "fish"
-                        ):
+                        if shell_basename == "zsh" or shell_basename == "bash" or shell_basename == "fish":
                             shell_cmd = f"{user_shell} -l -c '{escaped_command}'"
                         else:
                             # Default fallback
                             shell_cmd = f"{user_shell} -c '{escaped_command}'"
                     else:
-                        self._log(
-                            f"Using shell for command with shell operators: {command}"
-                        )
+                        self._log(f"Using shell for command with shell operators: {command}")
                         # Escape single quotes in command for shell execution
                         escaped_command = command.replace("'", "'\\''")
                         self._log(f"Original command: {command}")
@@ -354,9 +338,7 @@ class CommandExecutor:
 
             # Wait for the process to complete with timeout
             try:
-                stdout_bytes, stderr_bytes = await asyncio.wait_for(
-                    process.communicate(), timeout=timeout
-                )
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(process.communicate(), timeout=timeout)
 
                 return CommandResult(
                     return_code=process.returncode or 0,
@@ -376,9 +358,7 @@ class CommandExecutor:
                 )
         except Exception as e:
             self._log(f"Command execution error: {str(e)}")
-            return CommandResult(
-                return_code=1, error_message=f"Error executing command: {str(e)}"
-            )
+            return CommandResult(return_code=1, error_message=f"Error executing command: {str(e)}")
 
     async def execute_script(
         self,
@@ -415,9 +395,7 @@ class CommandExecutor:
                 )
 
             if not self.permission_manager.is_path_allowed(cwd):
-                return CommandResult(
-                    return_code=1, error_message=f"Working directory not allowed: {cwd}"
-                )
+                return CommandResult(return_code=1, error_message=f"Working directory not allowed: {cwd}")
 
         # Check if we need special handling for this interpreter
         interpreter_name = interpreter.split()[0].lower()
@@ -469,9 +447,7 @@ class CommandExecutor:
                 self._log(f"Using shell on Windows for interpreter: {user_shell}")
 
                 # Format command using helper method for the interpreter
-                shell_cmd = self._format_win32_shell_command(
-                    shell_basename, user_shell, interpreter, use_login_shell
-                )
+                shell_cmd = self._format_win32_shell_command(shell_basename, user_shell, interpreter, use_login_shell)
 
                 # Create and run the process with shell
                 process = await asyncio.create_subprocess_shell(
@@ -516,9 +492,7 @@ class CommandExecutor:
             # Wait for the process to complete with timeout
             try:
                 script_bytes: bytes = script.encode("utf-8")
-                stdout_bytes, stderr_bytes = await asyncio.wait_for(
-                    process.communicate(script_bytes), timeout=timeout
-                )
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(process.communicate(script_bytes), timeout=timeout)
 
                 return CommandResult(
                     return_code=process.returncode or 0,
@@ -538,9 +512,7 @@ class CommandExecutor:
                 )
         except Exception as e:
             self._log(f"Script execution error: {str(e)}")
-            return CommandResult(
-                return_code=1, error_message=f"Error executing script: {str(e)}"
-            )
+            return CommandResult(return_code=1, error_message=f"Error executing script: {str(e)}")
 
     async def _handle_fish_script(
         self,
@@ -591,9 +563,7 @@ class CommandExecutor:
 
             # Wait for the process to complete with timeout
             try:
-                stdout_bytes, stderr_bytes = await asyncio.wait_for(
-                    process.communicate(), timeout=timeout
-                )
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(process.communicate(), timeout=timeout)
 
                 return CommandResult(
                     return_code=process.returncode or 0,
@@ -613,9 +583,7 @@ class CommandExecutor:
                 )
         except Exception as e:
             self._log(f"Fish script execution error: {str(e)}")
-            return CommandResult(
-                return_code=1, error_message=f"Error executing Fish script: {str(e)}"
-            )
+            return CommandResult(return_code=1, error_message=f"Error executing Fish script: {str(e)}")
 
     async def execute_script_from_file(
         self,
@@ -671,9 +639,7 @@ class CommandExecutor:
             command_env.update(env)
 
         # Create a temporary file for the script
-        with tempfile.NamedTemporaryFile(
-            suffix=extension, mode="w", delete=False
-        ) as temp:
+        with tempfile.NamedTemporaryFile(suffix=extension, mode="w", delete=False) as temp:
             temp_path = temp.name
             _ = temp.write(script)  # Explicitly ignore the return value
 
@@ -696,9 +662,7 @@ class CommandExecutor:
                         wsl_path = temp_path.replace("\\", "/")
                         self._log(f"WSL path conversion may be incomplete: {wsl_path}")
 
-                    self._log(
-                        f"Converted Windows path '{temp_path}' to WSL path '{wsl_path}'"
-                    )
+                    self._log(f"Converted Windows path '{temp_path}' to WSL path '{wsl_path}'")
                     temp_path = wsl_path
 
                 # Build the command including args
@@ -709,13 +673,9 @@ class CommandExecutor:
                     cmd += " " + " ".join(args)
 
                 # Format command using helper method
-                shell_cmd = self._format_win32_shell_command(
-                    shell_basename, user_shell, cmd, use_login_shell
-                )
+                shell_cmd = self._format_win32_shell_command(shell_basename, user_shell, cmd, use_login_shell)
 
-                self._log(
-                    f"Executing script from file on Windows with shell: {shell_cmd}"
-                )
+                self._log(f"Executing script from file on Windows with shell: {shell_cmd}")
 
                 # Create and run the process with shell
                 process = await asyncio.create_subprocess_shell(
@@ -741,9 +701,7 @@ class CommandExecutor:
                     # Create command that runs script through login shell
                     shell_cmd = f"{user_shell} -l -c '{cmd}'"
 
-                    self._log(
-                        f"Executing script from file with login shell: {shell_cmd}"
-                    )
+                    self._log(f"Executing script from file with login shell: {shell_cmd}")
 
                     # Create and run the process with shell
                     process = await asyncio.create_subprocess_shell(
@@ -772,9 +730,7 @@ class CommandExecutor:
 
             # Wait for the process to complete with timeout
             try:
-                stdout_bytes, stderr_bytes = await asyncio.wait_for(
-                    process.communicate(), timeout=timeout
-                )
+                stdout_bytes, stderr_bytes = await asyncio.wait_for(process.communicate(), timeout=timeout)
 
                 return CommandResult(
                     return_code=process.returncode or 0,
@@ -794,9 +750,7 @@ class CommandExecutor:
                 )
         except Exception as e:
             self._log(f"Script file execution error: {str(e)}")
-            return CommandResult(
-                return_code=1, error_message=f"Error executing script: {str(e)}"
-            )
+            return CommandResult(return_code=1, error_message=f"Error executing script: {str(e)}")
         finally:
             # Clean up temporary file
             try:
@@ -863,9 +817,7 @@ class CommandExecutor:
             },
         }
 
-    def _get_interpreter_path(
-        self, language: str, shell_type: str | None = None
-    ) -> tuple[str, list[str]]:
+    def _get_interpreter_path(self, language: str, shell_type: str | None = None) -> tuple[str, list[str]]:
         """Get the full path to the interpreter for the given language.
 
         Attempts to find the full path to the interpreter command, but only for
@@ -901,25 +853,20 @@ class CommandExecutor:
 
         # For Windows shell types, try to find the full path
         if sys.platform == "win32" and (
-            not shell_type
-            or shell_type.lower() in ["cmd", "powershell", "cmd.exe", "powershell.exe"]
+            not shell_type or shell_type.lower() in ["cmd", "powershell", "cmd.exe", "powershell.exe"]
         ):
             try:
                 # Try to find the full path to the command
                 full_path = shutil.which(command)
                 if full_path:
-                    self._log(
-                        f"Found full path for {language} interpreter: {full_path}"
-                    )
+                    self._log(f"Found full path for {language} interpreter: {full_path}")
                     return full_path, args
 
                 # If primary command not found, try alternatives
                 for alt_command in alternatives:
                     alt_path = shutil.which(alt_command)
                     if alt_path:
-                        self._log(
-                            f"Found alternative path for {language} interpreter: {alt_path}"
-                        )
+                        self._log(f"Found alternative path for {language} interpreter: {alt_path}")
                         return alt_path, args
             except Exception as e:
                 self._log(f"Error finding path for {language} interpreter: {str(e)}")

hanzo_mcp/tools/shell/logs.py

@@ -167,9 +167,7 @@ Use run_command with 'tail -f' for continuous monitoring.
 
             # Note about follow mode
             if follow:
-                await tool_ctx.warning(
-                    "Follow mode not supported in MCP. Showing latest lines instead."
-                )
+                await tool_ctx.warning("Follow mode not supported in MCP. Showing latest lines instead.")
 
             # Read log file
             await tool_ctx.info(f"Reading log file: {log_path}")
@@ -197,11 +195,7 @@ Use run_command with 'tail -f' for continuous monitoring.
                     if process:
                         header += f"Process: {process.name} (ID: {process_id})\n"
                         header += f"Command: {process.command}\n"
-                        status = (
-                            "running"
-                            if process.is_running
-                            else f"finished (code: {process.return_code})"
-                        )
+                        status = "running" if process.is_running else f"finished (code: {process.return_code})"
                         header += f"Status: {status}\n"
                 header += f"{'=' * 50}\n"
 
@@ -232,11 +226,7 @@ Use run_command with 'tail -f' for continuous monitoring.
 
         # Check which logs belong to active processes
         active_processes = RunBackgroundTool.get_processes()
-        active_log_files = {
-            str(p.log_file): (pid, p)
-            for pid, p in active_processes.items()
-            if p.log_file
-        }
+        active_log_files = {str(p.log_file): (pid, p) for pid, p in active_processes.items() if p.log_file}
 
         # Build output
         output = []
@@ -250,9 +240,7 @@ Use run_command with 'tail -f' for continuous monitoring.
             if str(log_file) in active_log_files:
                 pid, process = active_log_files[str(log_file)]
                 status = "active" if process.is_running else "finished"
-                output.append(
-                    f"{log_file.name:<50} {size_str:>10} [{status}] (ID: {pid})"
-                )
+                output.append(f"{log_file.name:<50} {size_str:>10} [{status}] (ID: {pid})")
             else:
                 output.append(f"{log_file.name:<50} {size_str:>10}")
 

hanzo_mcp/tools/shell/npx.py

@@ -160,9 +160,7 @@ Or download from: https://nodejs.org/"""
 
         try:
             # Execute command
-            result = subprocess.run(
-                cmd, capture_output=True, text=True, timeout=timeout, check=True
-            )
+            result = subprocess.run(cmd, capture_output=True, text=True, timeout=timeout, check=True)
 
             output = []
             if result.stdout:
@@ -170,11 +168,7 @@ Or download from: https://nodejs.org/"""
             if result.stderr:
                 output.append(f"\nSTDERR:\n{result.stderr}")
 
-            return (
-                "\n".join(output)
-                if output
-                else "Command completed successfully with no output."
-            )
+            return "\n".join(output) if output else "Command completed successfully with no output."
 
         except subprocess.TimeoutExpired:
             return f"Error: Command timed out after {timeout} seconds. Use npx_background for long-running processes."

hanzo_mcp/tools/shell/npx_tool.py

@@ -86,9 +86,7 @@ npx json-server db.json  # Auto-backgrounds if needed"""
             cwd: Optional[str] = None,
             yes: bool = True,
         ) -> str:
-            return await tool_self.run(
-                ctx, package=package, args=args, cwd=cwd, yes=yes
-            )
+            return await tool_self.run(ctx, package=package, args=args, cwd=cwd, yes=yes)
 
     async def call(self, ctx: MCPContext, **params) -> str:
         """Call the tool with arguments."""

hanzo_mcp/tools/shell/pkill.py

@@ -151,9 +151,7 @@ Examples:
                             else:
                                 process.terminate()
                             killed_count += 1
-                            await tool_ctx.info(
-                                f"Killed process {proc_id} ({process.name})"
-                            )
+                            await tool_ctx.info(f"Killed process {proc_id} ({process.name})")
                         except Exception as e:
                             errors.append(f"Failed to kill {proc_id}: {str(e)}")
 
@@ -222,9 +220,7 @@ Examples:
                             else:
                                 process.terminate()
                             killed_count += 1
-                            await tool_ctx.info(
-                                f"Killed background process {proc_id} ({process.name})"
-                            )
+                            await tool_ctx.info(f"Killed background process {proc_id} ({process.name})")
                         except Exception as e:
                             errors.append(f"Failed to kill {proc_id}: {str(e)}")
 
@@ -237,15 +233,11 @@ Examples:
                             else:
                                 proc.terminate()
                             killed_count += 1
-                            await tool_ctx.info(
-                                f"Killed {proc.info['name']} (PID: {proc.info['pid']})"
-                            )
+                            await tool_ctx.info(f"Killed {proc.info['name']} (PID: {proc.info['pid']})")
                     except (psutil.NoSuchProcess, psutil.AccessDenied):
                         continue
                     except Exception as e:
-                        errors.append(
-                            f"Failed to kill PID {proc.info['pid']}: {str(e)}"
-                        )
+                        errors.append(f"Failed to kill PID {proc.info['pid']}: {str(e)}")
 
             # Build result message
             if killed_count > 0:

hanzo_mcp/tools/shell/process_tool.py

@@ -61,11 +61,7 @@ process --action logs --id bash_ghi789 --lines 50"""
 
             output = ["Background processes:"]
             for proc_id, info in processes.items():
-                status = (
-                    "running"
-                    if info["running"]
-                    else f"stopped (exit code: {info.get('return_code', 'unknown')})"
-                )
+                status = "running" if info["running"] else f"stopped (exit code: {info.get('return_code', 'unknown')})"
                 output.append(f"- {proc_id}: PID {info['pid']} - {status}")
                 if info.get("log_file"):
                     output.append(f"  Log: {info['log_file']}")
@@ -134,9 +130,7 @@ process --action logs --id bash_ghi789 --lines 50"""
             signal_type: str = "TERM",
             lines: int = 100,
         ) -> str:
-            return await tool_self.run(
-                ctx, action=action, id=id, signal_type=signal_type, lines=lines
-            )
+            return await tool_self.run(ctx, action=action, id=id, signal_type=signal_type, lines=lines)
 
     async def call(self, ctx: MCPContext, **params) -> str:
         """Call the tool with arguments."""

hanzo_mcp/tools/shell/processes.py

@@ -126,9 +126,7 @@ Examples:
             await tool_ctx.error(f"Failed to list processes: {str(e)}")
             return f"Error listing processes: {str(e)}"
 
-    def _list_background_processes(
-        self, filter_name: Optional[str], show_details: bool
-    ) -> str:
+    def _list_background_processes(self, filter_name: Optional[str], show_details: bool) -> str:
         """List background processes started with run_background."""
         processes = RunBackgroundTool.get_processes()
 
@@ -154,11 +152,7 @@ Examples:
         filtered_processes.sort(key=lambda x: x[1].start_time, reverse=True)
 
         for proc_id, process in filtered_processes:
-            status = (
-                "running"
-                if process.is_running
-                else f"finished (code: {process.return_code})"
-            )
+            status = "running" if process.is_running else f"finished (code: {process.return_code})"
             runtime = datetime.now() - process.start_time
             runtime_str = str(runtime).split(".")[0]  # Remove microseconds
 
@@ -191,9 +185,7 @@ Examples:
 
         return "\n".join(output)
 
-    def _list_system_processes(
-        self, filter_name: Optional[str], show_details: bool
-    ) -> str:
+    def _list_system_processes(self, filter_name: Optional[str], show_details: bool) -> str:
         """List all system processes."""
         try:
             processes = []
@@ -229,9 +221,7 @@ Examples:
 
                     if show_details:
                         process_info["cpu"] = proc.cpu_percent(interval=0.1)
-                        process_info["memory"] = (
-                            proc.memory_info().rss / 1024 / 1024
-                        )  # MB
+                        process_info["memory"] = proc.memory_info().rss / 1024 / 1024  # MB
 
                     processes.append(process_info)
 
@@ -250,9 +240,7 @@ Examples:
 
             # Header
             if show_details:
-                output.append(
-                    f"{'PID':>7} {'CPU%':>5} {'MEM(MB)':>8} {'NAME':<20} COMMAND"
-                )
+                output.append(f"{'PID':>7} {'CPU%':>5} {'MEM(MB)':>8} {'NAME':<20} COMMAND")
                 output.append("-" * 80)
 
                 for proc in processes:

hanzo_mcp/tools/shell/run_background.py

@@ -273,9 +273,7 @@ Examples:
             # Clean up finished processes
             self._cleanup_finished_processes()
 
-            await tool_ctx.info(
-                f"Process started with ID: {process_id}, PID: {process.pid}"
-            )
+            await tool_ctx.info(f"Process started with ID: {process_id}, PID: {process.pid}")
 
             # Return process information
             return f"""Background process started successfully!

hanzo_mcp/tools/shell/run_command.py

@@ -77,9 +77,7 @@ class RunCommandToolParams(TypedDict):
 class RunCommandTool(ShellBaseTool):
     """Tool for executing shell commands."""
 
-    def __init__(
-        self, permission_manager: Any, command_executor: BashSessionExecutor
-    ) -> None:
+    def __init__(self, permission_manager: Any, command_executor: BashSessionExecutor) -> None:
         """Initialize the run command tool.
 
         Args:

hanzo_mcp/tools/shell/run_command_windows.py

@@ -20,9 +20,7 @@ from hanzo_mcp.tools.shell.command_executor import CommandExecutor
 class RunCommandTool(ShellBaseTool):
     """Tool for executing shell commands."""
 
-    def __init__(
-        self, permission_manager: Any, command_executor: CommandExecutor
-    ) -> None:
+    def __init__(self, permission_manager: Any, command_executor: CommandExecutor) -> None:
         """Initialize the run command tool.
 
         Args:

hanzo_mcp/tools/shell/run_tool.py

@@ -0,0 +1,56 @@
+"""Run tool for command execution with automatic backgrounding."""
+
+from typing import Optional, override
+from mcp.server import FastMCP
+from mcp.server.fastmcp import Context as MCPContext
+
+from hanzo_mcp.tools.shell.zsh_tool import ShellTool
+
+
+class RunTool(ShellTool):
+    """Tool for running commands with automatic backgrounding (alias of shell tool)."""
+
+    name = "run"
+
+    def register(self, server: FastMCP) -> None:
+        """Register the tool with the MCP server."""
+        tool_self = self
+
+        @server.tool(name=self.name, description=self.description)
+        async def run(
+            ctx: MCPContext,
+            command: str,
+            cwd: Optional[str] = None,
+            env: Optional[dict[str, str]] = None,
+            timeout: Optional[int] = None,
+        ) -> str:
+            return await tool_self.run(ctx, command=command, cwd=cwd, env=env, timeout=timeout)
+
+    @property
+    @override
+    def description(self) -> str:
+        """Get the tool description."""
+        return """Execute shell commands with automatic backgrounding for long-running processes.
+
+Automatically selects the best available shell:
+- Zsh if available (with .zshrc)
+- User's preferred shell ($SHELL)  
+- Bash as fallback
+
+Commands that run for more than 2 minutes will automatically continue in the background.
+You can check their status and logs using the 'process' tool.
+
+Usage:
+run "ls -la"
+run "python server.py"  # Auto-backgrounds after 2 minutes
+run "git status && git diff"
+run "npm run dev" --cwd ./frontend  # Auto-backgrounds if needed"""
+
+    @override
+    def get_tool_name(self) -> str:
+        """Get the tool name."""
+        return "run"
+
+
+# Create instance
+run_tool = RunTool()