Server(feat[run_shell]): add run_shell() wrapping tmux run-shell

why: run-shell executes shell commands in the tmux server context, useful
for background tasks and capturing command output programmatically.
what:
- Add Server.run_shell() with background (-b), delay (-d), capture (-C),
  target_pane (-t) parameters
- Returns stdout when not in background mode, None otherwise
- Add tests for basic command execution and background mode

Author: tony

src/libtmux/server.py

@@ -423,6 +423,66 @@ def kill_session(self, target_session: str | int) -> Server:
 
         return self
 
+    def run_shell(
+        self,
+        command: str,
+        *,
+        background: bool | None = None,
+        delay: str | None = None,
+        capture: bool | None = None,
+        target_pane: str | None = None,
+    ) -> list[str] | None:
+        """Execute a shell command via ``$ tmux run-shell``.
+
+        Parameters
+        ----------
+        command : str
+            Shell command to execute.
+        background : bool, optional
+            Run in background (``-b`` flag).
+        delay : str, optional
+            Delay before execution (``-d`` flag).
+        capture : bool, optional
+            Capture output to the target pane (``-C`` flag).
+        target_pane : str, optional
+            Target pane for output (``-t`` flag).
+
+        Returns
+        -------
+        list[str] | None
+            Command stdout if not running in background, None otherwise.
+
+        Examples
+        --------
+        >>> result = server.run_shell('echo hello')
+        >>> 'hello' in (result or [])
+        True
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if background:
+            tmux_args += ("-b",)
+
+        if delay is not None:
+            tmux_args += ("-d", delay)
+
+        if capture:
+            tmux_args += ("-C",)
+
+        if target_pane is not None:
+            tmux_args += ("-t", target_pane)
+
+        tmux_args += (command,)
+
+        proc = self.cmd("run-shell", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+        if background:
+            return None
+        return proc.stdout
+
     def switch_client(self, target_session: str) -> None:
         """Switch tmux client.
 

tests/test_server.py

@@ -460,6 +460,21 @@ def test_tmux_bin_invalid_path_raise_if_dead() -> None:
         s.raise_if_dead()
 
 
+def test_run_shell_basic(server: Server) -> None:
+    """Test Server.run_shell() executes command and returns output."""
+    server.new_session(session_name="run_shell_test")
+    result = server.run_shell("echo hello_from_run_shell")
+    assert result is not None
+    assert any("hello_from_run_shell" in line for line in result)
+
+
+def test_run_shell_background(server: Server) -> None:
+    """Test Server.run_shell() in background mode."""
+    server.new_session(session_name="run_shell_bg_test")
+    result = server.run_shell("echo bg_test", background=True)
+    assert result is None
+
+
 def test_new_session_config_file(
     server: Server,
     tmp_path: pathlib.Path,