Pane(feat[pipe]): add pipe() wrapping tmux pipe-pane

why: pipe-pane is needed for monitoring, logging, and capturing pane output
to external commands or files programmatically.
what:
- Add pipe() method with command, output_only (-O), input_only (-I),
  toggle (-o) parameters wrapping pipe-pane
- Calling with no command stops piping
- Add test piping to file via cat, verifying output captured

Author: tony

src/libtmux/pane.py

@@ -1139,6 +1139,54 @@ def enter(self) -> Pane:
         self.cmd("send-keys", "Enter")
         return self
 
+    def pipe(
+        self,
+        command: str | None = None,
+        *,
+        output_only: bool | None = None,
+        input_only: bool | None = None,
+        toggle: bool | None = None,
+    ) -> None:
+        """Pipe pane output to a shell command via ``$ tmux pipe-pane``.
+
+        Parameters
+        ----------
+        command : str, optional
+            Shell command to pipe to. If None, stops piping.
+        output_only : bool, optional
+            Only pipe output from the pane (``-O`` flag).
+        input_only : bool, optional
+            Only pipe input to the pane (``-I`` flag).
+        toggle : bool, optional
+            Toggle piping on/off (``-o`` flag).
+
+        Examples
+        --------
+        >>> pane.pipe('cat >> /tmp/output.txt')
+
+        Stop piping:
+
+        >>> pane.pipe()
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if output_only:
+            tmux_args += ("-O",)
+
+        if input_only:
+            tmux_args += ("-I",)
+
+        if toggle:
+            tmux_args += ("-o",)
+
+        if command is not None:
+            tmux_args += (command,)
+
+        proc = self.cmd("pipe-pane", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def respawn(
         self,
         *,

tests/test_pane.py

@@ -740,6 +740,42 @@ def test_split_percentage_size_mutual_exclusion(session: Session) -> None:
         pane.split(size=10, percentage=50)
 
 
+def test_pipe_pane(session: Session, tmp_path: pathlib.Path) -> None:
+    """Test Pane.pipe() pipes output to a file."""
+    env = shutil.which("env")
+    assert env is not None
+
+    window = session.new_window(
+        window_name="test_pipe",
+        window_shell=f"{env} PS1='$ ' sh",
+    )
+    pane = window.active_pane
+    assert pane is not None
+
+    retry_until(lambda: "$" in "\n".join(pane.capture_pane()), 2, raises=True)
+
+    pipe_file = tmp_path / "pipe_output.txt"
+
+    # Start piping
+    pane.pipe(f"cat >> {pipe_file}")
+
+    # Send some text
+    pane.send_keys("echo pipe_test_ok", enter=True)
+    retry_until(
+        lambda: "pipe_test_ok" in "\n".join(pane.capture_pane()), 3, raises=True
+    )
+
+    # Stop piping
+    pane.pipe()
+
+    # Verify file has content
+    retry_until(
+        lambda: pipe_file.exists() and pipe_file.stat().st_size > 0, 3, raises=True
+    )
+    content = pipe_file.read_text()
+    assert "pipe_test_ok" in content
+
+
 def test_respawn_pane_kill(session: Session) -> None:
     """Test Pane.respawn() with kill flag on active pane."""
     window = session.new_window(window_name="test_respawn")