Pane(feat[clear_history]): add clear_history() wrapping tmux clear-history

why: clear-history is useful for clearing pane scrollback buffers,
especially important for test isolation and monitoring workflows.
what:
- Add clear_history() method with clear_pane (-H, 3.4+) parameter
- Version-gate -H flag with has_gte_version("3.4")
- Add test verifying history is cleared after sending commands

Author: tony

src/libtmux/pane.py

@@ -1139,6 +1139,41 @@ def enter(self) -> Pane:
         self.cmd("send-keys", "Enter")
         return self
 
+    def clear_history(self, *, clear_pane: bool | None = None) -> None:
+        """Clear pane history buffer via ``$ tmux clear-history``.
+
+        Parameters
+        ----------
+        clear_pane : bool, optional
+            Also clear the visible pane content (``-H`` flag).
+            Requires tmux 3.4+.
+
+            .. versionadded:: 0.45
+
+        Examples
+        --------
+        >>> pane.clear_history()
+        """
+        import warnings
+
+        from libtmux.common import has_gte_version
+
+        tmux_args: tuple[str, ...] = ()
+
+        if clear_pane:
+            if has_gte_version("3.4", tmux_bin=self.server.tmux_bin):
+                tmux_args += ("-H",)
+            else:
+                warnings.warn(
+                    "clear_pane requires tmux 3.4+, ignoring",
+                    stacklevel=2,
+                )
+
+        proc = self.cmd("clear-history", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def clear(self) -> Pane:
         """Clear pane."""
         self.send_keys("reset")

tests/test_pane.py

@@ -738,3 +738,31 @@ def test_split_percentage_size_mutual_exclusion(session: Session) -> None:
     assert pane is not None
     with pytest.raises(ValueError, match="Cannot specify both"):
         pane.split(size=10, percentage=50)
+
+
+def test_clear_history(session: Session) -> None:
+    """Test Pane.clear_history()."""
+    env = shutil.which("env")
+    assert env is not None
+
+    window = session.new_window(
+        window_name="test_clearhist",
+        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)
+
+    # Send some commands to build up history
+    pane.send_keys("echo line1", enter=True)
+    pane.send_keys("echo line2", enter=True)
+    retry_until(lambda: "line2" in "\n".join(pane.capture_pane()), 3, raises=True)
+
+    # Clear history
+    pane.clear_history()
+
+    # The scrollback should be cleared (visible content may still show current)
+    history = pane.capture_pane(start=-100)
+    # After clearing, scrollback history should be much shorter
+    assert len(history) <= 30  # reasonable bound after clear