Server(feat): add confirm_before, command_prompt wrapping interactive tmux commands

why: confirm-before and command-prompt were previously untestable because
they block waiting for user input. Using send-keys -K -c (tmux 3.4+) we
can inject key events into the client's prompt handler programmatically.
what:
- Add Server.confirm_before() wrapping confirm-before with -b (always
  non-blocking), prompt (-p), confirm_key (-c), default_yes (-y),
  target_client (-t) parameters
- Add Server.command_prompt() wrapping command-prompt with -b (always
  non-blocking), prompt (-p), inputs (-I), target_client (-t) parameters
- Both use send-keys -K -c <client> for confirmation/input in tests
- ConfirmBeforeCase parametrized tests: confirm_y, default_yes_enter
- CommandPromptCase parametrized tests: type_and_submit, prefill_and_submit
- All tests version-gated to tmux 3.4+

Author: tony

src/libtmux/server.py

@@ -825,6 +825,123 @@ def lock_client(self, *, target_client: str | None = None) -> None:
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
 
+    def confirm_before(
+        self,
+        command: str,
+        *,
+        prompt: str | None = None,
+        confirm_key: str | None = None,
+        default_yes: bool | None = None,
+        target_client: str | None = None,
+    ) -> None:
+        """Run a command after confirmation via ``$ tmux confirm-before``.
+
+        Always uses ``-b`` (background) to avoid blocking the command queue.
+        Use ``send-keys -K -c <client>`` to provide the confirmation key.
+
+        Requires tmux 3.4+ for ``-b`` flag support.
+
+        Parameters
+        ----------
+        command : str
+            Tmux command to run after confirmation.
+        prompt : str, optional
+            Custom prompt text (``-p`` flag).
+        confirm_key : str, optional
+            Key to accept as confirmation (``-c`` flag). Default is ``y``.
+        default_yes : bool, optional
+            Make Enter default to yes (``-y`` flag).
+        target_client : str, optional
+            Target client (``-t`` flag).
+
+        Examples
+        --------
+        >>> with control_mode() as ctl:
+        ...     server.confirm_before(
+        ...         'set -g @cf_test yes',
+        ...         target_client=ctl.client_name,
+        ...     )
+        ...     _ = server.cmd('send-keys', '-K', '-c', ctl.client_name, 'y')
+        ...     server.cmd('show-options', '-gv', '@cf_test').stdout[0]
+        'yes'
+        """
+        tmux_args: tuple[str, ...] = ("-b",)
+
+        if prompt is not None:
+            tmux_args += ("-p", prompt)
+
+        if confirm_key is not None:
+            tmux_args += ("-c", confirm_key)
+
+        if default_yes:
+            tmux_args += ("-y",)
+
+        if target_client is not None:
+            tmux_args += ("-t", target_client)
+
+        tmux_args += (command,)
+
+        proc = self.cmd("confirm-before", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
+    def command_prompt(
+        self,
+        template: str,
+        *,
+        prompt: str | None = None,
+        inputs: str | None = None,
+        target_client: str | None = None,
+    ) -> None:
+        """Open a command prompt via ``$ tmux command-prompt``.
+
+        Always uses ``-b`` (background) to avoid blocking the command queue.
+        Use ``send-keys -K -c <client>`` to type into the prompt and submit.
+
+        Requires tmux 3.4+ for ``-b`` flag support.
+
+        Parameters
+        ----------
+        template : str
+            Tmux command template. Use ``%1``, ``%2`` for prompt values.
+        prompt : str, optional
+            Custom prompt text (``-p`` flag). Commas separate multiple prompts.
+        inputs : str, optional
+            Pre-fill prompt input (``-I`` flag). Commas separate multiple.
+        target_client : str, optional
+            Target client (``-t`` flag).
+
+        Examples
+        --------
+        >>> with control_mode() as ctl:
+        ...     server.command_prompt(
+        ...         "set -g @cp_test '%1'",
+        ...         target_client=ctl.client_name,
+        ...     )
+        ...     for key in ['h', 'i', 'Enter']:
+        ...         _ = server.cmd('send-keys', '-K', '-c', ctl.client_name, key)
+        ...     server.cmd('show-options', '-gv', '@cp_test').stdout[0]
+        'hi'
+        """
+        tmux_args: tuple[str, ...] = ("-b",)
+
+        if prompt is not None:
+            tmux_args += ("-p", prompt)
+
+        if inputs is not None:
+            tmux_args += ("-I", inputs)
+
+        if target_client is not None:
+            tmux_args += ("-t", target_client)
+
+        tmux_args += (template,)
+
+        proc = self.cmd("command-prompt", *tmux_args)
+
+        if proc.stderr:
+            raise exc.LibTmuxException(proc.stderr)
+
     def start_server(self) -> None:
         """Start the tmux server if not already running.
 

tests/test_server.py

@@ -461,6 +461,146 @@ def test_tmux_bin_invalid_path_raise_if_dead() -> None:
         s.raise_if_dead()
 
 
+class ConfirmBeforeCase(t.NamedTuple):
+    """Test case for confirm_before()."""
+
+    test_id: str
+    confirm_key: str
+    use_default_yes: bool
+    custom_confirm_key: str | None
+    option_name: str
+    expected_value: str
+    min_tmux_version: str | None
+
+
+CONFIRM_BEFORE_CASES: list[ConfirmBeforeCase] = [
+    ConfirmBeforeCase(
+        test_id="confirm_y",
+        confirm_key="y",
+        use_default_yes=False,
+        custom_confirm_key=None,
+        option_name="@cf_test_y",
+        expected_value="yes",
+        min_tmux_version="3.4",
+    ),
+    ConfirmBeforeCase(
+        test_id="default_yes_enter",
+        confirm_key="Enter",
+        use_default_yes=True,
+        custom_confirm_key=None,
+        option_name="@cf_test_enter",
+        expected_value="yes",
+        min_tmux_version="3.4",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(ConfirmBeforeCase._fields),
+    CONFIRM_BEFORE_CASES,
+    ids=[c.test_id for c in CONFIRM_BEFORE_CASES],
+)
+def test_confirm_before(
+    test_id: str,
+    confirm_key: str,
+    use_default_yes: bool,
+    custom_confirm_key: str | None,
+    option_name: str,
+    expected_value: str,
+    min_tmux_version: str | None,
+    control_mode: t.Callable[..., t.Any],
+    server: Server,
+) -> None:
+    """Test Server.confirm_before() with send-keys -K confirmation."""
+    from libtmux.common import has_gte_version
+
+    if min_tmux_version and not has_gte_version(min_tmux_version):
+        pytest.skip(f"Requires tmux {min_tmux_version}+")
+
+    with control_mode() as ctl:
+        kwargs: dict[str, t.Any] = {"target_client": ctl.client_name}
+        if use_default_yes:
+            kwargs["default_yes"] = True
+        if custom_confirm_key is not None:
+            kwargs["confirm_key"] = custom_confirm_key
+
+        server.confirm_before(f"set -g {option_name} {expected_value}", **kwargs)
+        server.cmd("send-keys", "-K", "-c", ctl.client_name, confirm_key)
+
+    result = server.cmd("show-options", "-gv", option_name)
+    assert result.stdout[0] == expected_value
+
+
+class CommandPromptCase(t.NamedTuple):
+    """Test case for command_prompt()."""
+
+    test_id: str
+    template: str
+    keys: list[str]
+    inputs: str | None
+    option_name: str
+    expected_value: str
+    min_tmux_version: str | None
+
+
+COMMAND_PROMPT_CASES: list[CommandPromptCase] = [
+    CommandPromptCase(
+        test_id="type_and_submit",
+        template="set -g @cp_typed '%1'",
+        keys=["h", "e", "l", "l", "o", "Enter"],
+        inputs=None,
+        option_name="@cp_typed",
+        expected_value="hello",
+        min_tmux_version="3.4",
+    ),
+    CommandPromptCase(
+        test_id="prefill_and_submit",
+        template="set -g @cp_prefill '%1'",
+        keys=["Enter"],
+        inputs="prefilled",
+        option_name="@cp_prefill",
+        expected_value="prefilled",
+        min_tmux_version="3.4",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(CommandPromptCase._fields),
+    COMMAND_PROMPT_CASES,
+    ids=[c.test_id for c in COMMAND_PROMPT_CASES],
+)
+def test_command_prompt(
+    test_id: str,
+    template: str,
+    keys: list[str],
+    inputs: str | None,
+    option_name: str,
+    expected_value: str,
+    min_tmux_version: str | None,
+    control_mode: t.Callable[..., t.Any],
+    server: Server,
+) -> None:
+    """Test Server.command_prompt() with send-keys -K input."""
+    from libtmux.common import has_gte_version
+
+    if min_tmux_version and not has_gte_version(min_tmux_version):
+        pytest.skip(f"Requires tmux {min_tmux_version}+")
+
+    with control_mode() as ctl:
+        kwargs: dict[str, t.Any] = {"target_client": ctl.client_name}
+        if inputs is not None:
+            kwargs["inputs"] = inputs
+
+        server.command_prompt(template, **kwargs)
+
+        for key in keys:
+            server.cmd("send-keys", "-K", "-c", ctl.client_name, key)
+
+    result = server.cmd("show-options", "-gv", option_name)
+    assert result.stdout[0] == expected_value
+
+
 def test_lock_server(
     control_mode: t.Callable[..., t.Any],
     server: Server,