code-muse 0.0.1__py3-none-any.whl

code_muse/tools/command_runner.py

@@ -0,0 +1,1401 @@
+import asyncio
+import atexit
+import ctypes
+import os
+import select
+import signal
+import subprocess
+import sys
+import tempfile
+import threading
+import time
+import traceback
+from collections import deque
+from collections.abc import Callable
+
+# FREE-THREADED: ThreadPoolExecutor is compatible with free-threaded Python 3.14 —
+# no GIL contention for I/O-bound shell command work.
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager, suppress
+from functools import partial
+from typing import Literal
+
+from pydantic import BaseModel
+from pydantic_ai import RunContext
+from rich.text import Text
+
+from code_muse.messaging import (  # Structured messaging types
+    AgentReasoningMessage,
+    ShellOutputMessage,
+    ShellStartMessage,
+    emit_error,
+    emit_info,
+    emit_shell_line,
+    emit_warning,
+    get_message_bus,
+)
+from code_muse.tools.background_jobs import register_background_job
+from code_muse.tools.common import generate_group_id, get_user_approval_async
+from code_muse.tools.subagent_context import is_subagent
+
+# Maximum line length for shell command output to prevent massive token usage
+# This helps avoid exceeding model context limits when commands produce very long lines
+MAX_LINE_LENGTH = 256
+
+
+def _truncate_line(line: str) -> str:
+    """Truncate a line to MAX_LINE_LENGTH if it exceeds the limit."""
+    if len(line) > MAX_LINE_LENGTH:
+        return line[:MAX_LINE_LENGTH] + "... [truncated]"
+    return line
+
+
+# Windows-specific: Check if pipe has data available without blocking
+# This is needed because select() doesn't work on pipes on Windows
+if sys.platform.startswith("win"):
+    import msvcrt
+
+    # Load kernel32 for PeekNamedPipe
+    _kernel32 = ctypes.windll.kernel32
+
+    def _win32_pipe_has_data(pipe) -> bool:
+        """Check if a Windows pipe has data available without blocking.
+
+        Uses PeekNamedPipe from kernel32.dll to check if there's data
+        in the pipe buffer without actually reading it.
+
+        Args:
+            pipe: A file object with a fileno() method (e.g., process.stdout)
+
+        Returns:
+            True if data is available, False otherwise (including on error)
+        """
+        try:
+            # Get the Windows handle from the file descriptor
+            handle = msvcrt.get_osfhandle(pipe.fileno())
+
+            # PeekNamedPipe parameters:
+            # - hNamedPipe: handle to the pipe
+            # - lpBuffer: buffer to receive data (NULL = don't read)
+            # - nBufferSize: size of buffer (0 = don't read)
+            # - lpBytesRead: receives bytes read (NULL)
+            # - lpTotalBytesAvail: receives total bytes available
+            # - lpBytesLeftThisMessage: receives bytes left (NULL)
+            bytes_available = ctypes.c_ulong(0)
+
+            result = _kernel32.PeekNamedPipe(
+                handle,
+                None,  # Don't read data
+                0,  # Buffer size 0
+                None,  # Don't care about bytes read
+                ctypes.byref(bytes_available),  # Get bytes available
+                None,  # Don't care about bytes left in message
+            )
+
+            if result:
+                return bytes_available.value > 0
+            return False
+        except ValueError, OSError, ctypes.ArgumentError:
+            # Handle closed, invalid, or other errors
+            return False
+else:
+    # POSIX stub - not used, but keeps the code clean
+    def _win32_pipe_has_data(pipe) -> bool:
+        return False
+
+
+_AWAITING_USER_INPUT = threading.Event()
+
+# FREE-THREADED: _CONFIRMATION_LOCK guards sync shell confirmation prompts.
+_CONFIRMATION_LOCK = threading.Lock()
+
+# Track running shell processes so we can kill them on Ctrl-C from the UI
+_RUNNING_PROCESSES: set[subprocess.Popen] = set()
+# FREE-THREADED: _RUNNING_PROCESSES_LOCK guards sync process set mutations.
+_RUNNING_PROCESSES_LOCK = threading.Lock()
+_USER_KILLED_PROCESSES = set()
+
+# Global state for shell command keyboard handling
+_SHELL_CTRL_X_STOP_EVENT: threading.Event | None = None
+_SHELL_CTRL_X_THREAD: threading.Thread | None = None
+_ORIGINAL_SIGINT_HANDLER = None
+
+# Reference-counted keyboard context - stays active while ANY command is running
+_KEYBOARD_CONTEXT_REFCOUNT = 0
+# FREE-THREADED: _KEYBOARD_CONTEXT_LOCK guards sync keyboard refcount mutations.
+_KEYBOARD_CONTEXT_LOCK = threading.Lock()
+
+# Thread-safe registry of active stop events for concurrent shell commands
+_ACTIVE_STOP_EVENTS: set[threading.Event] = set()
+# FREE-THREADED: _ACTIVE_STOP_EVENTS_LOCK guards sync stop-event registry.
+_ACTIVE_STOP_EVENTS_LOCK = threading.Lock()
+
+# Thread pool for running blocking shell commands without blocking the event loop.
+# FREE-THREADED: ThreadPoolExecutor is compatible with free-threaded Python 3.14 —
+# no GIL contention for I/O-bound subprocess work. This allows multiple
+# sub-agents to run shell commands in parallel.
+_SHELL_EXECUTOR = ThreadPoolExecutor(max_workers=16, thread_name_prefix="shell_cmd_")
+
+
+def _register_process(proc: subprocess.Popen) -> None:
+    with _RUNNING_PROCESSES_LOCK:
+        _RUNNING_PROCESSES.add(proc)
+
+
+def _unregister_process(proc: subprocess.Popen) -> None:
+    with _RUNNING_PROCESSES_LOCK:
+        _RUNNING_PROCESSES.discard(proc)
+
+
+def _kill_process_group(proc: subprocess.Popen) -> None:
+    """Attempt to aggressively terminate a process and its group.
+
+    Cross-platform best-effort. On POSIX, uses process groups. On Windows, tries taskkill with /T flag for tree kill.
+    """
+    try:
+        if sys.platform.startswith("win"):
+            # On Windows, use taskkill to kill the process tree
+            # /F = force, /T = kill tree (children), /PID = process ID
+            try:
+                import subprocess as sp
+
+                # Try taskkill first - more reliable on Windows
+                sp.run(
+                    ["taskkill", "/F", "/T", "/PID", str(proc.pid)],
+                    capture_output=True,
+                    timeout=2,
+                    check=False,
+                )
+                time.sleep(0.3)
+            except Exception:
+                # Fallback to Python's built-in methods
+                pass
+
+            # Double-check it's dead, if not use proc.kill()
+            if proc.poll() is None:
+                try:
+                    proc.kill()
+                    time.sleep(0.3)
+                except Exception:
+                    pass
+            return
+
+        # POSIX
+        pid = proc.pid
+        try:
+            pgid = os.getpgid(pid)
+            os.killpg(pgid, signal.SIGTERM)
+            time.sleep(1.0)
+            if proc.poll() is None:
+                os.killpg(pgid, signal.SIGINT)
+                time.sleep(0.6)
+            if proc.poll() is None:
+                os.killpg(pgid, signal.SIGKILL)
+                time.sleep(0.5)
+        except OSError:
+            # Fall back to direct kill of the process
+            try:
+                if proc.poll() is None:
+                    proc.kill()
+            except OSError:
+                pass
+
+        if proc.poll() is None:
+            # Last ditch attempt; may be unkillable zombie
+            try:
+                for _ in range(3):
+                    os.kill(proc.pid, signal.SIGKILL)
+                    time.sleep(0.2)
+                    if proc.poll() is not None:
+                        break
+            except Exception:
+                pass
+    except Exception as e:
+        emit_error(f"Kill process error: {e}")
+
+
+def kill_all_running_shell_processes() -> int:
+    """Kill all currently tracked running shell processes and stop reader threads.
+
+    Returns the number of processes signaled.
+    """
+    # Signal all active reader threads to stop
+    with _ACTIVE_STOP_EVENTS_LOCK:
+        for evt in _ACTIVE_STOP_EVENTS:
+            evt.set()
+
+    procs: list[subprocess.Popen]
+    with _RUNNING_PROCESSES_LOCK:
+        procs = list(_RUNNING_PROCESSES)
+    count = 0
+    for p in procs:
+        try:
+            # Close pipes first to unblock readline()
+            try:
+                if p.stdout and not p.stdout.closed:
+                    p.stdout.close()
+                if p.stderr and not p.stderr.closed:
+                    p.stderr.close()
+                if p.stdin and not p.stdin.closed:
+                    p.stdin.close()
+            except OSError, ValueError:
+                pass
+
+            if p.poll() is None:
+                _kill_process_group(p)
+                count += 1
+                _USER_KILLED_PROCESSES.add(p.pid)
+        finally:
+            _unregister_process(p)
+    return count
+
+
+def shutdown() -> None:
+    """Gracefully shut down the command runner subsystem.
+
+    Kills any still-running shell processes and shuts down the internal
+    ThreadPoolExecutor.  Called automatically at interpreter exit via
+    ``atexit``; callers may also invoke it explicitly during orderly
+    shutdown (e.g. from ``cli_runner.main_entry()``).
+    """
+    try:
+        killed = kill_all_running_shell_processes()
+        if killed:
+            emit_info(f"Shutdown killed {killed} running shell process(es)")
+    except Exception as exc:
+        emit_warning(f"Process cleanup during shutdown: {exc}")
+
+    try:
+        _SHELL_EXECUTOR.shutdown(wait=True, cancel_futures=True)
+        emit_info("Shell command executor shut down cleanly")
+    except Exception as exc:
+        emit_warning(f"Executor shutdown error: {exc}")
+
+
+atexit.register(shutdown)
+
+
+def get_running_shell_process_count() -> int:
+    """Return the number of currently-active shell processes being tracked."""
+    with _RUNNING_PROCESSES_LOCK:
+        alive = 0
+        stale: set[subprocess.Popen] = set()
+        for proc in _RUNNING_PROCESSES:
+            if proc.poll() is None:
+                alive += 1
+            else:
+                stale.add(proc)
+        for proc in stale:
+            _RUNNING_PROCESSES.discard(proc)
+    return alive
+
+
+# Function to check if user input is awaited
+def is_awaiting_user_input():
+    """Check if command_runner is waiting for user input."""
+    return _AWAITING_USER_INPUT.is_set()
+
+
+# Function to set user input flag
+def set_awaiting_user_input(awaiting=True):
+    """Set the flag indicating if user input is awaited."""
+    if awaiting:
+        _AWAITING_USER_INPUT.set()
+    else:
+        _AWAITING_USER_INPUT.clear()
+
+    # When we're setting this flag, also pause/resume all active spinners
+    if awaiting:
+        # Pause all active spinners (imported here to avoid circular imports)
+        try:
+            from code_muse.messaging.spinner import pause_all_spinners
+
+            pause_all_spinners()
+        except ImportError:
+            pass  # Spinner functionality not available
+    else:
+        # Resume all active spinners
+        try:
+            from code_muse.messaging.spinner import resume_all_spinners
+
+            resume_all_spinners()
+        except ImportError:
+            pass  # Spinner functionality not available
+
+
+class ShellCommandOutput(BaseModel):
+    success: bool
+    command: str | None
+    error: str | None = ""
+    stdout: str | None
+    stderr: str | None
+    exit_code: int | None
+    execution_time: float | None
+    timeout: bool | None = False
+    user_interrupted: bool | None = False
+    user_feedback: str | None = None  # User feedback when command is rejected
+    background: bool = False  # True if command was run in background mode
+    log_file: str | None = None  # Path to temp log file for background commands
+    pid: int | None = None  # Process ID for background commands
+
+
+class ShellSafetyAssessment(BaseModel):
+    """Assessment of shell command safety risks.
+
+    This model represents the structured output from the shell safety checker agent.
+    It provides a risk level classification and reasoning for that assessment.
+
+    Attributes:
+        risk: Risk level classification. Can be one of:
+              'none' (completely safe), 'low' (minimal risk), 'medium' (moderate risk),
+              'high' (significant risk), 'critical' (severe/destructive risk).
+        reasoning: Brief explanation (max 1-2 sentences) of why this risk level
+                   was assigned. Should be concise and actionable.
+        is_fallback: Whether this assessment is a fallback due to parsing failure.
+                     Fallback assessments are not cached to allow retry with fresh LLM responses.
+    """
+
+    risk: Literal["none", "low", "medium", "high", "critical"]
+    reasoning: str
+    is_fallback: bool = False
+
+
+def _listen_for_ctrl_x_windows(
+    stop_event: threading.Event,
+    on_escape: Callable[[], None],
+) -> None:
+    """Windows-specific Ctrl-X listener."""
+    import msvcrt
+    import time
+
+    while not stop_event.is_set():
+        try:
+            if msvcrt.kbhit():
+                try:
+                    # Try to read a character
+                    # Note: msvcrt.getwch() returns unicode string on Windows
+                    key = msvcrt.getwch()
+
+                    # Check for Ctrl+X (\x18) or other interrupt keys
+                    # Some terminals might not send \x18, so also check for 'x' with modifier
+                    if key == "\x18":  # Standard Ctrl+X
+                        try:
+                            on_escape()
+                        except Exception:
+                            emit_warning(
+                                "Ctrl+X handler raised unexpectedly; Ctrl+C still works."
+                            )
+                    # Note: In some Windows terminals, Ctrl+X might not be captured
+                    # Users can use Ctrl+C as alternative, which is handled by signal handler
+                except OSError, ValueError:
+                    # kbhit/getwch can fail on Windows in certain terminal states
+                    # Just continue, user can use Ctrl+C
+                    pass
+        except Exception:
+            # Be silent about Windows listener errors - they're common
+            # User can use Ctrl+C as fallback
+            pass
+        time.sleep(0.05)
+
+
+def _listen_for_ctrl_x_posix(
+    stop_event: threading.Event,
+    on_escape: Callable[[], None],
+) -> None:
+    """POSIX-specific Ctrl-X listener."""
+    import select
+    import sys
+    import termios
+    import tty
+
+    stdin = sys.stdin
+    try:
+        fd = stdin.fileno()
+    except AttributeError, ValueError, OSError:
+        return
+    try:
+        original_attrs = termios.tcgetattr(fd)
+    except Exception:
+        return
+
+    try:
+        tty.setcbreak(fd)
+        while not stop_event.is_set():
+            try:
+                read_ready, _, _ = select.select([stdin], [], [], 0.05)
+            except Exception:
+                break
+            if not read_ready:
+                continue
+            data = stdin.read(1)
+            if not data:
+                break
+            if data == "\x18":  # Ctrl+X
+                try:
+                    on_escape()
+                except Exception:
+                    emit_warning(
+                        "Ctrl+X handler raised unexpectedly; Ctrl+C still works."
+                    )
+    finally:
+        termios.tcsetattr(fd, termios.TCSADRAIN, original_attrs)
+
+
+def _spawn_ctrl_x_key_listener(
+    stop_event: threading.Event,
+    on_escape: Callable[[], None],
+) -> threading.Thread | None:
+    """Start a Ctrl+X key listener thread for CLI sessions."""
+    try:
+        import sys
+    except ImportError:
+        return None
+
+    stdin = getattr(sys, "stdin", None)
+    if stdin is None or not hasattr(stdin, "isatty"):
+        return None
+    try:
+        if not stdin.isatty():
+            return None
+    except Exception:
+        return None
+
+    def listener() -> None:
+        try:
+            if sys.platform.startswith("win"):
+                _listen_for_ctrl_x_windows(stop_event, on_escape)
+            else:
+                _listen_for_ctrl_x_posix(stop_event, on_escape)
+        except Exception:
+            emit_warning(
+                "Ctrl+X key listener stopped unexpectedly; press Ctrl+C to cancel."
+            )
+
+    thread = threading.Thread(
+        target=listener, name="shell-command-ctrl-x-listener", daemon=True
+    )
+    thread.start()
+    return thread
+
+
+@contextmanager
+def _shell_command_keyboard_context():
+    """Context manager to handle keyboard interrupts during shell command execution.
+
+    This context manager:
+    1. Disables the agent's Ctrl-C handler (so it doesn't cancel the agent)
+    2. Enables a Ctrl-X listener to kill the running shell process
+    3. Restores the original Ctrl-C handler when done
+    """
+    global _SHELL_CTRL_X_STOP_EVENT, _SHELL_CTRL_X_THREAD, _ORIGINAL_SIGINT_HANDLER
+
+    # Handler for Ctrl-X: kill all running shell processes
+    def handle_ctrl_x_press() -> None:
+        emit_warning("\n🛑 Ctrl-X detected! Interrupting shell command...")
+        kill_all_running_shell_processes()
+
+    # Handler for Ctrl-C during shell execution: just kill the shell process, don't cancel agent
+    def shell_sigint_handler(_sig, _frame):
+        """During shell execution, Ctrl-C kills the shell but doesn't cancel the agent."""
+        emit_warning("\n🛑 Ctrl-C detected! Interrupting shell command...")
+        kill_all_running_shell_processes()
+
+    # Set up Ctrl-X listener
+    _SHELL_CTRL_X_STOP_EVENT = threading.Event()
+    _SHELL_CTRL_X_THREAD = _spawn_ctrl_x_key_listener(
+        _SHELL_CTRL_X_STOP_EVENT,
+        handle_ctrl_x_press,
+    )
+
+    # Replace SIGINT handler temporarily
+    try:
+        _ORIGINAL_SIGINT_HANDLER = signal.signal(signal.SIGINT, shell_sigint_handler)
+    except ValueError, OSError:
+        # Can't set signal handler (maybe not main thread?)
+        _ORIGINAL_SIGINT_HANDLER = None
+
+    try:
+        yield
+    finally:
+        # Clean up: stop Ctrl-X listener
+        if _SHELL_CTRL_X_STOP_EVENT:
+            _SHELL_CTRL_X_STOP_EVENT.set()
+
+        if _SHELL_CTRL_X_THREAD and _SHELL_CTRL_X_THREAD.is_alive():
+            with suppress(Exception):
+                _SHELL_CTRL_X_THREAD.join(timeout=0.2)
+
+        # Restore original SIGINT handler
+        if _ORIGINAL_SIGINT_HANDLER is not None:
+            with suppress(ValueError, OSError):
+                signal.signal(signal.SIGINT, _ORIGINAL_SIGINT_HANDLER)
+
+        # Clean up global state
+        _SHELL_CTRL_X_STOP_EVENT = None
+        _SHELL_CTRL_X_THREAD = None
+        _ORIGINAL_SIGINT_HANDLER = None
+
+
+def _handle_ctrl_x_press() -> None:
+    """Handler for Ctrl-X: kill all running shell processes."""
+    emit_warning("\n🛑 Ctrl-X detected! Interrupting all shell commands...")
+    kill_all_running_shell_processes()
+
+
+def _shell_sigint_handler(_sig, _frame):
+    """During shell execution, Ctrl-C kills all shells but doesn't cancel agent."""
+    emit_warning("\n🛑 Ctrl-C detected! Interrupting all shell commands...")
+    kill_all_running_shell_processes()
+
+
+def _start_keyboard_listener() -> None:
+    """Start the Ctrl-X listener and install SIGINT handler.
+
+    Called when the first shell command starts.
+    """
+    global _SHELL_CTRL_X_STOP_EVENT, _SHELL_CTRL_X_THREAD, _ORIGINAL_SIGINT_HANDLER
+
+    # Set up Ctrl-X listener
+    _SHELL_CTRL_X_STOP_EVENT = threading.Event()
+    _SHELL_CTRL_X_THREAD = _spawn_ctrl_x_key_listener(
+        _SHELL_CTRL_X_STOP_EVENT,
+        _handle_ctrl_x_press,
+    )
+
+    # Replace SIGINT handler temporarily
+    try:
+        _ORIGINAL_SIGINT_HANDLER = signal.signal(signal.SIGINT, _shell_sigint_handler)
+    except ValueError, OSError:
+        # Can't set signal handler (maybe not main thread?)
+        _ORIGINAL_SIGINT_HANDLER = None
+
+
+def _stop_keyboard_listener() -> None:
+    """Stop the Ctrl-X listener and restore SIGINT handler.
+
+    Called when the last shell command finishes.
+    """
+    global _SHELL_CTRL_X_STOP_EVENT, _SHELL_CTRL_X_THREAD, _ORIGINAL_SIGINT_HANDLER
+
+    # Clean up: stop Ctrl-X listener
+    if _SHELL_CTRL_X_STOP_EVENT:
+        _SHELL_CTRL_X_STOP_EVENT.set()
+
+    if _SHELL_CTRL_X_THREAD and _SHELL_CTRL_X_THREAD.is_alive():
+        with suppress(Exception):
+            _SHELL_CTRL_X_THREAD.join(timeout=0.2)
+
+    # Restore original SIGINT handler
+    if _ORIGINAL_SIGINT_HANDLER is not None:
+        with suppress(ValueError, OSError):
+            signal.signal(signal.SIGINT, _ORIGINAL_SIGINT_HANDLER)
+
+    # Clean up global state
+    _SHELL_CTRL_X_STOP_EVENT = None
+    _SHELL_CTRL_X_THREAD = None
+    _ORIGINAL_SIGINT_HANDLER = None
+
+
+def _acquire_keyboard_context() -> None:
+    """Acquire the shared keyboard context (reference counted).
+
+    Starts the Ctrl-X listener when the first command starts.
+    Safe to call from any thread.
+    """
+    global _KEYBOARD_CONTEXT_REFCOUNT
+
+    should_start = False
+    with _KEYBOARD_CONTEXT_LOCK:
+        _KEYBOARD_CONTEXT_REFCOUNT += 1
+        if _KEYBOARD_CONTEXT_REFCOUNT == 1:
+            should_start = True
+
+    # Start listener OUTSIDE the lock to avoid blocking other commands
+    if should_start:
+        _start_keyboard_listener()
+
+
+def _release_keyboard_context() -> None:
+    """Release the shared keyboard context (reference counted).
+
+    Stops the Ctrl-X listener when the last command finishes.
+    Safe to call from any thread.
+    """
+    global _KEYBOARD_CONTEXT_REFCOUNT
+
+    should_stop = False
+    with _KEYBOARD_CONTEXT_LOCK:
+        _KEYBOARD_CONTEXT_REFCOUNT -= 1
+        if _KEYBOARD_CONTEXT_REFCOUNT <= 0:
+            _KEYBOARD_CONTEXT_REFCOUNT = 0  # Safety clamp
+            should_stop = True
+
+    # Stop listener OUTSIDE the lock to avoid blocking other commands
+    if should_stop:
+        _stop_keyboard_listener()
+
+
+def run_shell_command_streaming(
+    process: subprocess.Popen,
+    timeout: int = 60,
+    command: str = "",
+    group_id: str = None,
+    silent: bool = False,
+):
+    stop_event = threading.Event()
+    with _ACTIVE_STOP_EVENTS_LOCK:
+        _ACTIVE_STOP_EVENTS.add(stop_event)
+
+    start_time = time.time()
+    last_output_time = [start_time]
+
+    ABSOLUTE_TIMEOUT_SECONDS = 270
+
+    stdout_lines: deque[str] = deque(maxlen=256)
+    stderr_lines: deque[str] = deque(maxlen=256)
+
+    stdout_thread = None
+    stderr_thread = None
+
+    def read_stdout():
+        try:
+            fd = process.stdout.fileno()
+        except ValueError, OSError:
+            return
+
+        try:
+            while True:
+                # Check stop event first
+                if stop_event.is_set():
+                    break
+
+                # Use select to check if data is available (with timeout)
+                if sys.platform.startswith("win"):
+                    # Windows doesn't support select on pipes
+                    # Use PeekNamedPipe via _win32_pipe_has_data() to check
+                    # if data is available without blocking
+                    try:
+                        if _win32_pipe_has_data(process.stdout):
+                            line = process.stdout.readline()
+                            if not line:  # EOF
+                                break
+                            line = line.rstrip("\n")
+                            line = _truncate_line(line)
+                            stdout_lines.append(line)
+                            if not silent:
+                                emit_shell_line(line, stream="stdout")
+                            last_output_time[0] = time.time()
+                        else:
+                            # No data available, check if process has exited
+                            if process.poll() is not None:
+                                # Process exited, do one final drain
+                                try:
+                                    remaining = process.stdout.read()
+                                    if remaining:
+                                        for line in remaining.split("\n"):
+                                            line = _truncate_line(line)
+                                            stdout_lines.append(line)
+                                            if not silent:
+                                                emit_shell_line(line, stream="stdout")
+                                except ValueError, OSError:
+                                    pass
+                                break
+                            # Sleep briefly to avoid busy-waiting (100ms like POSIX)
+                            time.sleep(0.1)
+                    except ValueError, OSError:
+                        break
+                else:
+                    # POSIX: use select with timeout
+                    try:
+                        ready, _, _ = select.select([fd], [], [], 0.1)  # 100ms timeout
+                    except ValueError, OSError:
+                        break
+
+                    if ready:
+                        line = process.stdout.readline()
+                        if not line:  # EOF
+                            break
+                        line = line.rstrip("\n")
+                        line = _truncate_line(line)
+                        stdout_lines.append(line)
+                        if not silent:
+                            emit_shell_line(line, stream="stdout")
+                        last_output_time[0] = time.time()
+                    # If not ready, loop continues and checks stop event again
+        except ValueError, OSError:
+            pass
+        except Exception:
+            pass
+
+    def read_stderr():
+        try:
+            fd = process.stderr.fileno()
+        except ValueError, OSError:
+            return
+
+        try:
+            while True:
+                # Check stop event first
+                if stop_event.is_set():
+                    break
+
+                if sys.platform.startswith("win"):
+                    # Windows doesn't support select on pipes
+                    # Use PeekNamedPipe via _win32_pipe_has_data() to check
+                    # if data is available without blocking
+                    try:
+                        if _win32_pipe_has_data(process.stderr):
+                            line = process.stderr.readline()
+                            if not line:  # EOF
+                                break
+                            line = line.rstrip("\n")
+                            line = _truncate_line(line)
+                            stderr_lines.append(line)
+                            if not silent:
+                                emit_shell_line(line, stream="stderr")
+                            last_output_time[0] = time.time()
+                        else:
+                            # No data available, check if process has exited
+                            if process.poll() is not None:
+                                # Process exited, do one final drain
+                                try:
+                                    remaining = process.stderr.read()
+                                    if remaining:
+                                        for line in remaining.split("\n"):
+                                            line = _truncate_line(line)
+                                            stderr_lines.append(line)
+                                            if not silent:
+                                                emit_shell_line(line, stream="stderr")
+                                except ValueError, OSError:
+                                    pass
+                                break
+                            # Sleep briefly to avoid busy-waiting (100ms like POSIX)
+                            time.sleep(0.1)
+                    except ValueError, OSError:
+                        break
+                else:
+                    try:
+                        ready, _, _ = select.select([fd], [], [], 0.1)
+                    except ValueError, OSError:
+                        break
+
+                    if ready:
+                        line = process.stderr.readline()
+                        if not line:  # EOF
+                            break
+                        line = line.rstrip("\n")
+                        line = _truncate_line(line)
+                        stderr_lines.append(line)
+                        if not silent:
+                            emit_shell_line(line, stream="stderr")
+                        last_output_time[0] = time.time()
+        except ValueError, OSError:
+            pass
+        except Exception:
+            pass
+
+    def cleanup_process_and_threads(timeout_type: str = "unknown"):
+        nonlocal stdout_thread, stderr_thread
+
+        def nuclear_kill(proc):
+            _kill_process_group(proc)
+
+        try:
+            # Signal reader threads to stop first
+            stop_event.set()
+
+            if process.poll() is None:
+                nuclear_kill(process)
+
+            try:
+                if process.stdout and not process.stdout.closed:
+                    process.stdout.close()
+                if process.stderr and not process.stderr.closed:
+                    process.stderr.close()
+                if process.stdin and not process.stdin.closed:
+                    process.stdin.close()
+            except OSError, ValueError:
+                pass
+
+            # Unregister once we're done cleaning up
+            _unregister_process(process)
+
+            if stdout_thread and stdout_thread.is_alive():
+                stdout_thread.join(timeout=3)
+                if stdout_thread.is_alive() and not silent:
+                    emit_warning(
+                        f"stdout reader thread failed to terminate after {timeout_type} timeout",
+                        message_group=group_id,
+                    )
+
+            if stderr_thread and stderr_thread.is_alive():
+                stderr_thread.join(timeout=3)
+                if stderr_thread.is_alive() and not silent:
+                    emit_warning(
+                        f"stderr reader thread failed to terminate after {timeout_type} timeout",
+                        message_group=group_id,
+                    )
+
+        except Exception as e:
+            if not silent:
+                emit_warning(
+                    f"Error during process cleanup: {e}", message_group=group_id
+                )
+
+        execution_time = time.time() - start_time
+        return ShellCommandOutput(
+            **{
+                "success": False,
+                "command": command,
+                "stdout": "\n".join(stdout_lines),
+                "stderr": "\n".join(stderr_lines),
+                "exit_code": -9,
+                "execution_time": execution_time,
+                "timeout": True,
+                "error": f"Command timed out after {timeout} seconds",
+            }
+        )
+
+    try:
+        stdout_thread = threading.Thread(target=read_stdout, daemon=True)
+        stderr_thread = threading.Thread(target=read_stderr, daemon=True)
+
+        stdout_thread.start()
+        stderr_thread.start()
+
+        while process.poll() is None:
+            current_time = time.time()
+
+            if current_time - start_time > ABSOLUTE_TIMEOUT_SECONDS:
+                if not silent:
+                    emit_error(
+                        "Process killed: absolute timeout reached",
+                        message_group=group_id,
+                    )
+                return cleanup_process_and_threads("absolute")
+
+            if current_time - last_output_time[0] > timeout:
+                if not silent:
+                    emit_error(
+                        "Process killed: inactivity timeout reached",
+                        message_group=group_id,
+                    )
+                return cleanup_process_and_threads("inactivity")
+
+            time.sleep(0.1)
+
+        if stdout_thread:
+            stdout_thread.join(timeout=5)
+        if stderr_thread:
+            stderr_thread.join(timeout=5)
+
+        exit_code = process.returncode
+        execution_time = time.time() - start_time
+
+        try:
+            if process.stdout and not process.stdout.closed:
+                process.stdout.close()
+            if process.stderr and not process.stderr.closed:
+                process.stderr.close()
+            if process.stdin and not process.stdin.closed:
+                process.stdin.close()
+        except OSError, ValueError:
+            pass
+
+        _unregister_process(process)
+
+        # Apply line length limits to stdout/stderr before returning
+        truncated_stdout = list(stdout_lines)
+        truncated_stderr = list(stderr_lines)
+
+        # Emit structured ShellOutputMessage for the UI (skip for silent sub-agents)
+        if not silent:
+            shell_output_msg = ShellOutputMessage(
+                command=command,
+                stdout="\n".join(truncated_stdout),
+                stderr="\n".join(truncated_stderr),
+                exit_code=exit_code,
+                duration_seconds=execution_time,
+            )
+            get_message_bus().emit(shell_output_msg)
+
+        with _ACTIVE_STOP_EVENTS_LOCK:
+            _ACTIVE_STOP_EVENTS.discard(stop_event)
+
+        if exit_code != 0:
+            return ShellCommandOutput(
+                success=False,
+                command=command,
+                error="""The process didn't exit cleanly! If the user_interrupted flag is true,
+                please stop all execution and ask the user for clarification!""",
+                stdout="\n".join(truncated_stdout),
+                stderr="\n".join(truncated_stderr),
+                exit_code=exit_code,
+                execution_time=execution_time,
+                timeout=False,
+                user_interrupted=process.pid in _USER_KILLED_PROCESSES,
+            )
+
+        return ShellCommandOutput(
+            success=True,
+            command=command,
+            stdout="\n".join(truncated_stdout),
+            stderr="\n".join(truncated_stderr),
+            exit_code=exit_code,
+            execution_time=execution_time,
+            timeout=False,
+        )
+
+    except Exception as e:
+        with _ACTIVE_STOP_EVENTS_LOCK:
+            _ACTIVE_STOP_EVENTS.discard(stop_event)
+        return ShellCommandOutput(
+            success=False,
+            command=command,
+            error=f"Error during streaming execution: {str(e)}",
+            stdout="\n".join(stdout_lines),
+            stderr="\n".join(stderr_lines),
+            exit_code=-1,
+            timeout=False,
+        )
+
+
+async def run_shell_command(
+    context: RunContext,
+    command: str,
+    cwd: str = None,
+    timeout: int = 60,
+    background: bool = False,
+) -> ShellCommandOutput:
+    # Generate unique group_id for this command execution
+    group_id = generate_group_id("shell_command", command)
+
+    # Invoke safety check callbacks (only active in yolo_mode)
+    # This allows plugins to intercept and assess commands before execution
+    from code_muse.callbacks import on_run_shell_command
+
+    callback_results = await on_run_shell_command(context, command, cwd, timeout)
+
+    # Check if any callback blocked the command
+    # Callbacks can return None (allow) or a dict with blocked=True (reject)
+    _auto_approved = False
+    for result in callback_results:
+        if result and isinstance(result, dict):
+            if result.get("blocked"):
+                return ShellCommandOutput(
+                    success=False,
+                    command=command,
+                    error=result.get(
+                        "error_message", "Command blocked by safety check"
+                    ),
+                    user_feedback=result.get("reasoning", ""),
+                    stdout=None,
+                    stderr=None,
+                    exit_code=None,
+                    execution_time=None,
+                )
+            if result.get("pre_executed") and "output" in result:
+                return result["output"]
+            if result.get("auto_approve"):
+                _auto_approved = True
+
+    if not command or not command.strip():
+        emit_error("Command cannot be empty", message_group=group_id)
+        return ShellCommandOutput(
+            **{"success": False, "error": "Command cannot be empty"}
+        )
+
+    from code_muse.config import get_yolo_mode
+
+    yolo_mode = get_yolo_mode()
+
+    # Check if we're running as a sub-agent (skip confirmation and run silently)
+    running_as_subagent = is_subagent()
+
+    confirmation_lock_acquired = False
+
+    # Only ask for confirmation if we're in an interactive TTY, not in yolo mode,
+    # and NOT running as a sub-agent (sub-agents run without user interaction)
+    # and NOT auto-approved by a policy engine callback
+    if (
+        not yolo_mode
+        and not running_as_subagent
+        and not _auto_approved
+        and sys.stdin.isatty()
+    ):
+        confirmation_lock_acquired = _CONFIRMATION_LOCK.acquire(blocking=False)
+        if not confirmation_lock_acquired:
+            return ShellCommandOutput(
+                success=False,
+                command=command,
+                error="Another command is currently awaiting confirmation",
+            )
+
+        # Get agent_name for personalized messages
+        from code_muse.config import get_agent_name
+
+        agent_name = get_agent_name().title()
+
+        # Build panel content
+        panel_content = Text()
+        panel_content.append("⚡ Requesting permission to run:\n", style="bold yellow")
+        panel_content.append("$ ", style="bold green")
+        panel_content.append(command, style="bold white")
+
+        if cwd:
+            panel_content.append("\n\n", style="")
+            panel_content.append("📂 Working directory: ", style="dim")
+            panel_content.append(cwd, style="dim cyan")
+
+        if background:
+            panel_content.append("\n\n", style="")
+            panel_content.append(
+                "⏱️  This command will run in the background with no timeout.\n",
+                style="bold red",
+            )
+            panel_content.append(
+                "The process will continue until it completes or is manually stopped.",
+                style="dim",
+            )
+
+        # Use the common approval function (async version)
+        confirmed, user_feedback = await get_user_approval_async(
+            title="Shell Command",
+            content=panel_content,
+            preview=None,
+            border_style="dim white",
+            agent_name=agent_name,
+        )
+
+        # Release lock after approval
+        if confirmation_lock_acquired:
+            _CONFIRMATION_LOCK.release()
+
+        if not confirmed:
+            if user_feedback:
+                result = ShellCommandOutput(
+                    success=False,
+                    command=command,
+                    error=f"USER REJECTED: {user_feedback}",
+                    user_feedback=user_feedback,
+                    stdout=None,
+                    stderr=None,
+                    exit_code=None,
+                    execution_time=None,
+                )
+            else:
+                result = ShellCommandOutput(
+                    success=False,
+                    command=command,
+                    error="User rejected the command!",
+                    stdout=None,
+                    stderr=None,
+                    exit_code=None,
+                    execution_time=None,
+                )
+            return result
+
+    # Handle background execution - runs command detached and returns immediately.
+    # Approval has already been obtained above (or skipped in yolo/sub-agent mode).
+    if background:
+        # Create temp log file for output
+        log_file = tempfile.NamedTemporaryFile(  # noqa: SIM115
+            mode="w",
+            prefix="shell_bg_",
+            suffix=".log",
+            delete=False,  # Keep file so agent can read it later
+        )
+        log_file_path = log_file.name
+
+        try:
+            # Platform-specific process detachment
+            if sys.platform.startswith("win"):
+                creationflags = subprocess.CREATE_NEW_PROCESS_GROUP
+                process = subprocess.Popen(
+                    command,
+                    shell=True,
+                    stdout=log_file,
+                    stderr=subprocess.STDOUT,
+                    stdin=subprocess.DEVNULL,
+                    cwd=cwd,
+                    creationflags=creationflags,
+                )
+            else:
+                process = subprocess.Popen(
+                    command,
+                    shell=True,
+                    stdout=log_file,
+                    stderr=subprocess.STDOUT,
+                    stdin=subprocess.DEVNULL,
+                    cwd=cwd,
+                    start_new_session=True,  # Fully detach on POSIX
+                )
+
+            log_file.close()  # Close our handle, process keeps writing
+
+            # Emit UI messages so user sees what happened
+            bus = get_message_bus()
+            bus.emit(
+                ShellStartMessage(
+                    command=command,
+                    cwd=cwd,
+                    timeout=0,  # No timeout for background processes
+                    background=True,
+                )
+            )
+
+            # Register the job so it can be listed/stopped later
+            register_background_job(
+                pid=process.pid,
+                command=command,
+                cwd=cwd,
+                log_file=log_file.name,
+            )
+
+            # Emit info about background execution
+            emit_info(
+                f"🚀 Background process started (PID: {process.pid}) - no timeout, runs until complete"
+            )
+            emit_info(f"📄 Output logging to: {log_file.name}")
+
+            # Return immediately - don't wait, don't block
+            return ShellCommandOutput(
+                success=True,
+                command=command,
+                stdout=None,
+                stderr=None,
+                exit_code=None,
+                execution_time=0.0,
+                background=True,
+                log_file=log_file.name,
+                pid=process.pid,
+            )
+        except Exception as e:
+            with suppress(Exception):
+                log_file.close()
+            # Clean up the temp file on error since no process will write to it
+            with suppress(OSError):
+                os.unlink(log_file_path)
+            # Emit error message so user sees what happened
+            emit_error(f"❌ Failed to start background process: {e}")
+            return ShellCommandOutput(
+                success=False,
+                command=command,
+                error=f"Failed to start background process: {e}",
+                stdout=None,
+                stderr=None,
+                exit_code=None,
+                execution_time=None,
+                background=True,
+            )
+
+    # Execute the command - sub-agents run silently without keyboard context
+    return await _execute_shell_command(
+        command=command,
+        cwd=cwd,
+        timeout=timeout,
+        group_id=group_id,
+        silent=running_as_subagent,
+    )
+
+
+async def _execute_shell_command(
+    command: str,
+    cwd: str | None,
+    timeout: int,
+    group_id: str,
+    silent: bool = False,
+) -> ShellCommandOutput:
+    """Internal helper to execute a shell command.
+
+    Args:
+        command: The shell command to execute
+        cwd: Working directory for command execution
+        timeout: Inactivity timeout in seconds
+        group_id: Unique group ID for message grouping
+        silent: If True, suppress streaming output (for sub-agents)
+
+    Returns:
+        ShellCommandOutput with execution results
+    """
+    # Always emit the ShellStartMessage banner (even for sub-agents)
+    bus = get_message_bus()
+    bus.emit(
+        ShellStartMessage(
+            command=command,
+            cwd=cwd,
+            timeout=timeout,
+        )
+    )
+
+    # Pause spinner during shell command so \r output can work properly
+    from code_muse.messaging.spinner import pause_all_spinners, resume_all_spinners
+
+    pause_all_spinners()
+
+    # Acquire shared keyboard context - Ctrl-X/Ctrl-C will kill ALL running commands
+    # This is reference-counted: listener starts on first command, stops on last
+    _acquire_keyboard_context()
+    try:
+        return await _run_command_inner(command, cwd, timeout, group_id, silent=silent)
+    finally:
+        _release_keyboard_context()
+        resume_all_spinners()
+
+
+def _run_command_sync(
+    command: str,
+    cwd: str | None,
+    timeout: int,
+    group_id: str,
+    silent: bool = False,
+) -> ShellCommandOutput:
+    """Synchronous command execution - runs in thread pool."""
+    creationflags = 0
+    preexec_fn = None
+    if sys.platform.startswith("win"):
+        try:
+            creationflags = subprocess.CREATE_NEW_PROCESS_GROUP  # type: ignore[attr-defined]
+        except Exception:
+            creationflags = 0
+    else:
+        preexec_fn = os.setsid if hasattr(os, "setsid") else None
+
+    import io
+
+    process = subprocess.Popen(
+        command,
+        shell=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        cwd=cwd,
+        bufsize=0,  # Unbuffered for real-time output
+        preexec_fn=preexec_fn,
+        creationflags=creationflags,
+    )
+
+    # Wrap pipes with TextIOWrapper that preserves \r (newline='' disables translation)
+    process.stdout = io.TextIOWrapper(
+        process.stdout, newline="", encoding="utf-8", errors="replace"
+    )
+    process.stderr = io.TextIOWrapper(
+        process.stderr, newline="", encoding="utf-8", errors="replace"
+    )
+    _register_process(process)
+    try:
+        return run_shell_command_streaming(
+            process, timeout=timeout, command=command, group_id=group_id, silent=silent
+        )
+    finally:
+        # Ensure unregistration in case streaming returned early or raised
+        _unregister_process(process)
+
+
+async def _run_command_inner(
+    command: str,
+    cwd: str | None,
+    timeout: int,
+    group_id: str,
+    silent: bool = False,
+) -> ShellCommandOutput:
+    """Inner command execution logic - runs blocking code in thread pool."""
+    loop = asyncio.get_running_loop()
+    try:
+        # Run the blocking shell command in a thread pool to avoid blocking the event loop
+        # This allows multiple sub-agents to run shell commands in parallel
+        return await loop.run_in_executor(
+            _SHELL_EXECUTOR,
+            partial(_run_command_sync, command, cwd, timeout, group_id, silent),
+        )
+    except Exception as e:
+        if not silent:
+            emit_error(traceback.format_exc(), message_group=group_id)
+        if "stdout" not in locals():
+            stdout = None
+        if "stderr" not in locals():
+            stderr = None
+
+        # Apply line length limits to stdout/stderr if they exist
+        truncated_stdout = None
+        if stdout:
+            stdout_lines = stdout.split("\n")
+            truncated_stdout = "\n".join(
+                [_truncate_line(line) for line in stdout_lines[-256:]]
+            )
+
+        truncated_stderr = None
+        if stderr:
+            stderr_lines = stderr.split("\n")
+            truncated_stderr = "\n".join(
+                [_truncate_line(line) for line in stderr_lines[-256:]]
+            )
+
+        return ShellCommandOutput(
+            success=False,
+            command=command,
+            error=f"Error executing command {str(e)}",
+            stdout=truncated_stdout,
+            stderr=truncated_stderr,
+            exit_code=-1,
+            timeout=False,
+        )
+
+
+class ReasoningOutput(BaseModel):
+    success: bool = True
+
+
+def share_your_reasoning(
+    context: RunContext, reasoning: str, next_steps: str | list[str] | None = None
+) -> ReasoningOutput:
+    # Handle list of next steps by formatting them
+    formatted_next_steps = next_steps
+    if isinstance(next_steps, list):
+        formatted_next_steps = "\n".join(
+            [f"{i + 1}. {step}" for i, step in enumerate(next_steps)]
+        )
+
+    # Emit structured AgentReasoningMessage for the UI
+    reasoning_msg = AgentReasoningMessage(
+        reasoning=reasoning,
+        next_steps=formatted_next_steps
+        if formatted_next_steps and formatted_next_steps.strip()
+        else None,
+    )
+    get_message_bus().emit(reasoning_msg)
+
+    return ReasoningOutput(success=True)
+
+
+def register_agent_run_shell_command(agent):
+    """Register only the agent_run_shell_command tool."""
+
+    @agent.tool
+    async def agent_run_shell_command(
+        context: RunContext,
+        command: str = "",
+        cwd: str = None,
+        timeout: int = 60,
+        background: bool = False,
+    ) -> ShellCommandOutput:
+        """Execute a shell command with comprehensive monitoring and safety features.
+
+        Supports streaming output, timeout handling, and background execution.
+        """
+        return await run_shell_command(context, command, cwd, timeout, background)
+
+
+def register_agent_share_your_reasoning(agent):
+    """Register only the agent_share_your_reasoning tool."""
+
+    @agent.tool
+    def agent_share_your_reasoning(
+        context: RunContext,
+        reasoning: str = "",
+        next_steps: str | list[str] | None = None,
+    ) -> ReasoningOutput:
+        """Share the agent's current reasoning and planned next steps with the user.
+
+        Displays reasoning and upcoming actions in a formatted panel for transparency.
+        """
+        return share_your_reasoning(context, reasoning, next_steps)