Session(feat[detach_client]): add detach_client() wrapping tmux detach-client

why: detach-client is needed for programmatically disconnecting clients
from sessions, useful for session management and automation.
what:
- Add Session.detach_client() with target_client (-t) and all_clients (-a)
- Use -s for session targeting since -t targets clients in detach-client
- Test uses ControlMode context manager to create a real client, then
  verifies list-clients count drops after detach

Author: tony

src/libtmux/session.py

@@ -245,6 +245,43 @@ def cmd(
     Commands (tmux-like)
     """
 
+    def detach_client(
+        self,
+        *,
+        target_client: str | None = None,
+        all_clients: bool | None = None,
+    ) -> None:
+        """Detach clients from this session via ``$ tmux detach-client``.
+
+        Parameters
+        ----------
+        target_client : str, optional
+            Target client to detach (``-t`` flag). If omitted, detaches
+            the most recently active client.
+        all_clients : bool, optional
+            Detach all clients attached to this session (``-a`` flag).
+
+        Examples
+        --------
+        >>> with control_mode() as ctl:
+        ...     session.detach_client()
+        """
+        tmux_args: tuple[str, ...] = ()
+
+        if all_clients:
+            tmux_args += ("-a",)
+
+        if target_client is not None:
+            tmux_args += ("-t", target_client)
+
+        # Use -s for session targeting (not -t, which targets clients)
+        tmux_args += ("-s", str(self.session_id))
+
+        proc = self.server.cmd("detach-client", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def last_window(self) -> Window:
         """Select the last (previously selected) window.
 

tests/test_session.py

@@ -576,6 +576,20 @@ def patched_cmd(cmd_name: str, *args: t.Any, **kwargs: t.Any) -> tmux_cmd:
         test_session.attach()
 
 
+def test_detach_client(
+    control_mode: t.Callable[..., t.Any],
+    session: Session,
+    server: Server,
+) -> None:
+    """Test Session.detach_client() detaches the control-mode client."""
+    with control_mode():
+        before = len(server.list_clients())
+        assert before > 0
+        session.detach_client()
+        after = len(server.list_clients())
+        assert after == before - 1
+
+
 def test_last_window(session: Session) -> None:
     """Test Session.last_window() selects previous window."""
     w1 = session.new_window(window_name="last_a", attach=True)