code-puppy 0.0.169__py3-none-any.whl → 0.0.366__py3-none-any.whl

code_puppy/tools/command_runner.py

@@ -1,26 +1,35 @@
+import asyncio
+import ctypes
 import os
+import select
 import signal
 import subprocess
 import sys
+import tempfile
 import threading
 import time
 import traceback
-from typing import Set
+from concurrent.futures import ThreadPoolExecutor
+from contextlib import contextmanager
+from functools import partial
+from typing import Callable, List, Literal, Optional, Set
 
 from pydantic import BaseModel
 from pydantic_ai import RunContext
-from rich.markdown import Markdown
 from rich.text import Text
 
-from code_puppy.messaging import (
-    emit_divider,
+from code_puppy.messaging import (  # Structured messaging types
+    AgentReasoningMessage,
+    ShellOutputMessage,
+    ShellStartMessage,
     emit_error,
     emit_info,
-    emit_system_message,
+    emit_shell_line,
     emit_warning,
+    get_message_bus,
 )
-from code_puppy.state_management import is_tui_mode
-from code_puppy.tools.common import generate_group_id
+from code_puppy.tools.common import generate_group_id, get_user_approval_async
+from code_puppy.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
@@ -33,6 +42,61 @@ def _truncate_line(line: str) -> str:
         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 = False
 
 _CONFIRMATION_LOCK = threading.Lock()
@@ -42,6 +106,22 @@ _RUNNING_PROCESSES: Set[subprocess.Popen] = set()
 _RUNNING_PROCESSES_LOCK = threading.Lock()
 _USER_KILLED_PROCESSES = set()
 
+# Global state for shell command keyboard handling
+_SHELL_CTRL_X_STOP_EVENT: Optional[threading.Event] = None
+_SHELL_CTRL_X_THREAD: Optional[threading.Thread] = None
+_ORIGINAL_SIGINT_HANDLER = None
+
+# Reference-counted keyboard context - stays active while ANY command is running
+_KEYBOARD_CONTEXT_REFCOUNT = 0
+_KEYBOARD_CONTEXT_LOCK = threading.Lock()
+
+# Stop event to signal reader threads to terminate
+_READER_STOP_EVENT: Optional[threading.Event] = None
+
+# Thread pool for running blocking shell commands without blocking the event loop
+# 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:
@@ -56,25 +136,32 @@ def _unregister_process(proc: subprocess.Popen) -> None:
 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 CTRL_BREAK_EVENT, then terminate().
+    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:
-                # Try a soft break first if the group exists
-                proc.send_signal(signal.CTRL_BREAK_EVENT)  # type: ignore[attr-defined]
-                time.sleep(0.8)
+                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
-            if proc.poll() is None:
-                try:
-                    proc.terminate()
-                    time.sleep(0.8)
-                except Exception:
-                    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
@@ -114,16 +201,33 @@ def _kill_process_group(proc: subprocess.Popen) -> None:
 
 
 def kill_all_running_shell_processes() -> int:
-    """Kill all currently tracked running shell processes.
+    """Kill all currently tracked running shell processes and stop reader threads.
 
     Returns the number of processes signaled.
     """
+    global _READER_STOP_EVENT
+
+    # Signal reader threads to stop
+    if _READER_STOP_EVENT:
+        _READER_STOP_EVENT.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
@@ -133,6 +237,21 @@ def kill_all_running_shell_processes() -> int:
     return count
 
 
+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."""
@@ -175,6 +294,314 @@ class ShellCommandOutput(BaseModel):
     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],
+) -> Optional[threading.Thread]:
+    """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():
+            try:
+                _SHELL_CTRL_X_THREAD.join(timeout=0.2)
+            except Exception:
+                pass
+
+        # Restore original SIGINT handler
+        if _ORIGINAL_SIGINT_HANDLER is not None:
+            try:
+                signal.signal(signal.SIGINT, _ORIGINAL_SIGINT_HANDLER)
+            except (ValueError, OSError):
+                pass
+
+        # 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():
+        try:
+            _SHELL_CTRL_X_THREAD.join(timeout=0.2)
+        except Exception:
+            pass
+
+    # Restore original SIGINT handler
+    if _ORIGINAL_SIGINT_HANDLER is not None:
+        try:
+            signal.signal(signal.SIGINT, _ORIGINAL_SIGINT_HANDLER)
+        except (ValueError, OSError):
+            pass
+
+    # 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(
@@ -182,7 +609,11 @@ def run_shell_command_streaming(
     timeout: int = 60,
     command: str = "",
     group_id: str = None,
+    silent: bool = False,
 ):
+    global _READER_STOP_EVENT
+    _READER_STOP_EVENT = threading.Event()
+
     start_time = time.time()
     last_output_time = [start_time]
 
@@ -196,27 +627,138 @@ def run_shell_command_streaming(
 
     def read_stdout():
         try:
-            for line in iter(process.stdout.readline, ""):
-                if line:
-                    line = line.rstrip("\n\r")
-                    # Limit line length to prevent massive token usage
-                    line = _truncate_line(line)
-                    stdout_lines.append(line)
-                    emit_system_message(line, message_group=group_id)
-                    last_output_time[0] = time.time()
+            fd = process.stdout.fileno()
+        except (ValueError, OSError):
+            return
+
+        try:
+            while True:
+                # Check stop event first
+                if _READER_STOP_EVENT and _READER_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\r")
+                            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.splitlines():
+                                            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, select.error):
+                        break
+
+                    if ready:
+                        line = process.stdout.readline()
+                        if not line:  # EOF
+                            break
+                        line = line.rstrip("\n\r")
+                        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:
-            for line in iter(process.stderr.readline, ""):
-                if line:
-                    line = line.rstrip("\n\r")
-                    # Limit line length to prevent massive token usage
-                    line = _truncate_line(line)
-                    stderr_lines.append(line)
-                    emit_system_message(line, message_group=group_id)
-                    last_output_time[0] = time.time()
+            fd = process.stderr.fileno()
+        except (ValueError, OSError):
+            return
+
+        try:
+            while True:
+                # Check stop event first
+                if _READER_STOP_EVENT and _READER_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\r")
+                            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.splitlines():
+                                            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, select.error):
+                        break
+
+                    if ready:
+                        line = process.stderr.readline()
+                        if not line:  # EOF
+                            break
+                        line = line.rstrip("\n\r")
+                        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
 
@@ -227,6 +769,10 @@ def run_shell_command_streaming(
             _kill_process_group(proc)
 
         try:
+            # Signal reader threads to stop first
+            if _READER_STOP_EVENT:
+                _READER_STOP_EVENT.set()
+
             if process.poll() is None:
                 nuclear_kill(process)
 
@@ -245,7 +791,7 @@ def run_shell_command_streaming(
 
             if stdout_thread and stdout_thread.is_alive():
                 stdout_thread.join(timeout=3)
-                if stdout_thread.is_alive():
+                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,
@@ -253,14 +799,17 @@ def run_shell_command_streaming(
 
             if stderr_thread and stderr_thread.is_alive():
                 stderr_thread.join(timeout=3)
-                if stderr_thread.is_alive():
+                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:
-            emit_warning(f"Error during process cleanup: {e}", message_group=group_id)
+            if not silent:
+                emit_warning(
+                    f"Error during process cleanup: {e}", message_group=group_id
+                )
 
         execution_time = time.time() - start_time
         return ShellCommandOutput(
@@ -287,19 +836,19 @@ def run_shell_command_streaming(
             current_time = time.time()
 
             if current_time - start_time > ABSOLUTE_TIMEOUT_SECONDS:
-                error_msg = Text()
-                error_msg.append(
-                    "Process killed: inactivity timeout reached", style="bold red"
-                )
-                emit_error(error_msg, message_group=group_id)
+                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:
-                error_msg = Text()
-                error_msg.append(
-                    "Process killed: inactivity timeout reached", style="bold red"
-                )
-                emit_error(error_msg, message_group=group_id)
+                if not silent:
+                    emit_error(
+                        "Process killed: inactivity timeout reached",
+                        message_group=group_id,
+                    )
                 return cleanup_process_and_threads("inactivity")
 
             time.sleep(0.1)
@@ -324,16 +873,26 @@ def run_shell_command_streaming(
 
         _unregister_process(process)
 
-        if exit_code != 0:
-            emit_error(
-                f"Command failed with exit code {exit_code}", message_group=group_id
+        # Apply line length limits to stdout/stderr before returning
+        truncated_stdout = [_truncate_line(line) for line in stdout_lines[-256:]]
+        truncated_stderr = [_truncate_line(line) for line in stderr_lines[-256:]]
+
+        # 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,
             )
-            emit_info(f"Took {execution_time:.2f}s", message_group=group_id)
+            get_message_bus().emit(shell_output_msg)
+
+        # Reset the stop event now that we're done
+        _READER_STOP_EVENT = None
+
+        if exit_code != 0:
             time.sleep(1)
-            # Apply line length limits to stdout/stderr before returning
-            truncated_stdout = [_truncate_line(line) for line in stdout_lines[-256:]]
-            truncated_stderr = [_truncate_line(line) for line in stderr_lines[-256:]]
-                
             return ShellCommandOutput(
                 success=False,
                 command=command,
@@ -346,12 +905,9 @@ def run_shell_command_streaming(
                 timeout=False,
                 user_interrupted=process.pid in _USER_KILLED_PROCESSES,
             )
-        # Apply line length limits to stdout/stderr before returning
-        truncated_stdout = [_truncate_line(line) for line in stdout_lines[-256:]]
-        truncated_stderr = [_truncate_line(line) for line in stderr_lines[-256:]]
-            
+
         return ShellCommandOutput(
-            success=exit_code == 0,
+            success=True,
             command=command,
             stdout="\n".join(truncated_stdout),
             stderr="\n".join(truncated_stderr),
@@ -361,6 +917,8 @@ def run_shell_command_streaming(
         )
 
     except Exception as e:
+        # Reset the stop event on exception too
+        _READER_STOP_EVENT = None
         return ShellCommandOutput(
             success=False,
             command=command,
@@ -372,33 +930,139 @@ def run_shell_command_streaming(
         )
 
 
-def run_shell_command(
-    context: RunContext, command: str, cwd: str = None, timeout: int = 60
+async def run_shell_command(
+    context: RunContext,
+    command: str,
+    cwd: str = None,
+    timeout: int = 60,
+    background: bool = False,
 ) -> ShellCommandOutput:
-    command_displayed = False
+    time.time()
 
     # 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_puppy.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)
+    for result in callback_results:
+        if result and isinstance(result, dict) and 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,
+            )
+
+    # Handle background execution - runs command detached and returns immediately
+    # This happens BEFORE user confirmation since we don't wait for the command
+    if background:
+        # Create temp log file for output
+        log_file = tempfile.NamedTemporaryFile(
+            mode="w",
+            prefix="shell_bg_",
+            suffix=".log",
+            delete=False,  # Keep file so agent can read it later
+        )
+
+        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,
+                )
+            )
+
+            # 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:
+            log_file.close()
+            # 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,
+            )
+
+    # Rest of the existing function continues...
     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"}
         )
 
-    emit_info(
-        f"\n[bold white on blue] SHELL COMMAND [/bold white on blue] 📂 [bold green]$ {command}[/bold green]",
-        message_group=group_id,
-    )
-
     from code_puppy.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 and not in yolo mode.
-    if not yolo_mode and sys.stdin.isatty():
+    # 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)
+    if not yolo_mode and not running_as_subagent and sys.stdin.isatty():
         confirmation_lock_acquired = _CONFIRMATION_LOCK.acquire(blocking=False)
         if not confirmation_lock_acquired:
             return ShellCommandOutput(
@@ -407,87 +1071,188 @@ def run_shell_command(
                 error="Another command is currently awaiting confirmation",
             )
 
-        command_displayed = True
+        # Get puppy name for personalized messages
+        from code_puppy.config import get_puppy_name
 
-        if cwd:
-            emit_info(f"[dim] Working directory: {cwd} [/dim]", message_group=group_id)
+        puppy_name = get_puppy_name().title()
 
-        # Set the flag to indicate we're awaiting user input
-        set_awaiting_user_input(True)
+        # 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")
 
-        time.sleep(0.2)
-        sys.stdout.write("Are you sure you want to run this command? (y(es)/n(o))\n")
-        sys.stdout.flush()
+        if cwd:
+            panel_content.append("\n\n", style="")
+            panel_content.append("📂 Working directory: ", style="dim")
+            panel_content.append(cwd, style="dim cyan")
+
+        # 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",
+            puppy_name=puppy_name,
+        )
 
-        try:
-            user_input = input()
-            confirmed = user_input.strip().lower() in {"yes", "y"}
-        except (KeyboardInterrupt, EOFError):
-            emit_warning("\n Cancelled by user")
-            confirmed = False
-        finally:
-            # Clear the flag regardless of the outcome
-            set_awaiting_user_input(False)
-            if confirmation_lock_acquired:
-                _CONFIRMATION_LOCK.release()
+        # Release lock after approval
+        if confirmation_lock_acquired:
+            _CONFIRMATION_LOCK.release()
 
         if not confirmed:
-            result = ShellCommandOutput(
-                success=False, command=command, error="User rejected the command!"
-            )
+            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
     else:
-        start_time = time.time()
+        time.time()
+
+    # 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,
+    )
 
-    try:
-        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
-
-        process = subprocess.Popen(
-            command,
-            shell=True,
-            stdout=subprocess.PIPE,
-            stderr=subprocess.PIPE,
-            text=True,
+
+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,
-            bufsize=1,
-            universal_newlines=True,
-            preexec_fn=preexec_fn,
-            creationflags=creationflags,
+            timeout=timeout,
         )
-        _register_process(process)
+    )
+
+    # 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()
+
+
+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:
-            return run_shell_command_streaming(
-                process, timeout=timeout, command=command, group_id=group_id
-            )
-        finally:
-            # Ensure unregistration in case streaming returned early or raised
-            _unregister_process(process)
+            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
+
+    process = subprocess.Popen(
+        command,
+        shell=True,
+        stdout=subprocess.PIPE,
+        stderr=subprocess.PIPE,
+        text=True,
+        cwd=cwd,
+        bufsize=1,
+        universal_newlines=True,
+        preexec_fn=preexec_fn,
+        creationflags=creationflags,
+    )
+    _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:
-        emit_error(traceback.format_exc(), message_group=group_id)
+        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_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:]])
-            
+            truncated_stderr = "\n".join(
+                [_truncate_line(line) for line in stderr_lines[-256:]]
+            )
+
         return ShellCommandOutput(
             success=False,
             command=command,
@@ -504,36 +1269,37 @@ class ReasoningOutput(BaseModel):
 
 
 def share_your_reasoning(
-    context: RunContext, reasoning: str, next_steps: str | None = None
+    context: RunContext, reasoning: str, next_steps: str | List[str] | None = None
 ) -> ReasoningOutput:
-    # Generate unique group_id for this reasoning session
-    group_id = generate_group_id(
-        "agent_reasoning", reasoning[:50]
-    )  # Use first 50 chars for context
-
-    if not is_tui_mode():
-        emit_divider(message_group=group_id)
-        emit_info(
-            "\n[bold white on purple] AGENT REASONING [/bold white on purple]",
-            message_group=group_id,
-        )
-    emit_info("[bold cyan]Current reasoning:[/bold cyan]", message_group=group_id)
-    emit_system_message(Markdown(reasoning), message_group=group_id)
-    if next_steps is not None and next_steps.strip():
-        emit_info(
-            "\n[bold cyan]Planned next steps:[/bold cyan]", message_group=group_id
+    # 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_system_message(Markdown(next_steps), message_group=group_id)
-    emit_info("[dim]" + "-" * 60 + "[/dim]\n", message_group=group_id)
-    return ReasoningOutput(**{"success": True})
+
+    # 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
-    def agent_run_shell_command(
-        context: RunContext, command: str = "", cwd: str = None, timeout: int = 60
+    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.
 
@@ -549,6 +1315,14 @@ def register_agent_run_shell_command(agent):
             timeout: Inactivity timeout in seconds. If no output is
                 produced for this duration, the process will be terminated.
                 Defaults to 60 seconds.
+            background: If True, run the command in the background and return immediately.
+                The command output will be written to a temporary log file.
+                Use this for long-running processes like servers (npm run dev, python -m http.server),
+                or any command you don't need to wait for.
+                When background=True, the response includes:
+                - log_file: Path to temp file containing stdout/stderr (read with read_file tool)
+                - pid: Process ID of the background process
+                Defaults to False.
 
         Returns:
             ShellCommandOutput: A structured response containing:
@@ -561,6 +1335,9 @@ def register_agent_run_shell_command(agent):
                 - execution_time (float | None): Total execution time in seconds
                 - timeout (bool | None): True if command was terminated due to timeout
                 - user_interrupted (bool | None): True if user killed the process
+                - background (bool): True if command was run in background mode
+                - log_file (str | None): Path to temp log file for background commands
+                - pid (int | None): Process ID for background commands
 
         Examples:
             >>> # Basic command execution
@@ -577,11 +1354,16 @@ def register_agent_run_shell_command(agent):
             >>> if result.timeout:
             ...     print("Command timed out")
 
+            >>> # Background command for long-running server
+            >>> result = agent_run_shell_command(ctx, "npm run dev", background=True)
+            >>> print(f"Server started with PID {result.pid}")
+            >>> print(f"Logs available at: {result.log_file}")
+
         Warning:
             This tool can execute arbitrary shell commands. Exercise caution when
             running untrusted commands, especially those that modify system state.
         """
-        return run_shell_command(context, command, cwd, timeout)
+        return await run_shell_command(context, command, cwd, timeout, background)
 
 
 def register_agent_share_your_reasoning(agent):
@@ -589,7 +1371,9 @@ def register_agent_share_your_reasoning(agent):
 
     @agent.tool
     def agent_share_your_reasoning(
-        context: RunContext, reasoning: str = "", next_steps: str | None = None
+        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.
 
@@ -603,8 +1387,8 @@ def register_agent_share_your_reasoning(agent):
                 reasoning for the current situation. This should be clear,
                 comprehensive, and explain the 'why' behind decisions.
             next_steps: Planned upcoming actions or steps
-                the agent intends to take. Can be None if no specific next steps
-                are determined. Defaults to None.
+                the agent intends to take. Can be a string or a list of strings.
+                Can be None if no specific next steps are determined. Defaults to None.
 
         Returns:
             ReasoningOutput: A simple response object containing:
@@ -615,6 +1399,10 @@ def register_agent_share_your_reasoning(agent):
             >>> next_steps = "First, I'll list the directory contents, then read key files"
             >>> result = agent_share_your_reasoning(ctx, reasoning, next_steps)
 
+            >>> # Using a list for next steps
+            >>> next_steps_list = ["List files", "Read README.md", "Run tests"]
+            >>> result = agent_share_your_reasoning(ctx, reasoning, next_steps_list)
+
         Best Practice:
             Use this tool frequently to maintain transparency. Call it:
             - Before starting complex operations