From 13f0ccda228dd69c339c38460e0eea0dbaa67d9e Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Mon, 5 Feb 2024 15:00:51 -0600
Subject: [PATCH 001/136] feat!(Window): Set option flags

---
 src/libtmux/window.py | 43 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 42 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index df63e19b6..25d62fe35 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -434,7 +434,18 @@ def select_layout(self, layout: str | None = None) -> Window:
 
         return self
 
-    def set_window_option(self, option: str, value: int | str) -> Window:
+    def set_window_option(
+        self,
+        option: str,
+        value: int | str,
+        format: bool | None = None,
+        unset: bool | None = None,
+        unset_panes: bool | None = None,
+        prevent_overwrite: bool | None = None,
+        suppress_warnings: bool | None = None,
+        append: bool | None = None,
+        g: bool | None = None,
+    ) -> Window:
         """Set option for tmux window.
 
         Wraps ``$ tmux set-window-option <option> <value>``.
@@ -452,15 +463,45 @@ def set_window_option(self, option: str, value: int | str) -> Window:
         :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
         :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
         """
+        flags: list[str] = []
         if isinstance(value, bool) and value:
             value = "on"
         elif isinstance(value, bool) and not value:
             value = "off"
 
+        if unset is not None and unset:
+            assert isinstance(unset, bool)
+            flags.append("-u")
+
+        if unset_panes is not None and unset_panes:
+            assert isinstance(unset_panes, bool)
+            flags.append("-U")
+
+        if format is not None and format:
+            assert isinstance(format, bool)
+            flags.append("-F")
+
+        if prevent_overwrite is not None and prevent_overwrite:
+            assert isinstance(prevent_overwrite, bool)
+            flags.append("-o")
+
+        if suppress_warnings is not None and suppress_warnings:
+            assert isinstance(suppress_warnings, bool)
+            flags.append("-q")
+
+        if append is not None and append:
+            assert isinstance(append, bool)
+            flags.append("-a")
+
+        if g is not None and g:
+            assert isinstance(g, bool)
+            flags.append("-g")
+
         cmd = self.cmd(
             "set-window-option",
             option,
             value,
+            *flags,
         )
 
         if isinstance(cmd.stderr, list) and len(cmd.stderr):

From fba6d9138aa78628cc9aada00fa4672450ac7678 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Mon, 5 Feb 2024 16:56:37 -0600
Subject: [PATCH 002/136] refactor!(Window): Deprecate set_window_option ->
 set_option

---
 src/libtmux/window.py | 27 +++++++++++++++++++++++----
 1 file changed, 23 insertions(+), 4 deletions(-)

diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index 25d62fe35..365bef7de 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -434,11 +434,11 @@ def select_layout(self, layout: str | None = None) -> Window:
 
         return self
 
-    def set_window_option(
+    def set_option(
         self,
         option: str,
         value: int | str,
-        format: bool | None = None,
+        _format: bool | None = None,
         unset: bool | None = None,
         unset_panes: bool | None = None,
         prevent_overwrite: bool | None = None,
@@ -477,8 +477,8 @@ def set_window_option(
             assert isinstance(unset_panes, bool)
             flags.append("-U")
 
-        if format is not None and format:
-            assert isinstance(format, bool)
+        if _format is not None and _format:
+            assert isinstance(_format, bool)
             flags.append("-F")
 
         if prevent_overwrite is not None and prevent_overwrite:
@@ -1005,6 +1005,25 @@ def kill_window(self) -> None:
         if proc.stderr:
             raise exc.LibTmuxException(proc.stderr)
 
+    def set_window_option(
+        self,
+        option: str,
+        value: int | str,
+    ) -> Window:
+        """Set option for tmux window. Deprecated by :meth:`Window.set_option()`.
+
+        .. deprecated:: 0.26
+
+           Deprecated by :meth:`Window.set_option()`.
+
+        """
+        warnings.warn(
+            "Window.set_window_option() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.set_option(option=option, value=value)
+
     def get(self, key: str, default: t.Any | None = None) -> t.Any:
         """Return key-based lookup. Deprecated by attributes.
 

From 5a905eb62b66fa8910a35947ea854874ef8422b2 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Mon, 5 Feb 2024 18:32:15 -0600
Subject: [PATCH 003/136] tests(Window): Rename test for show_window_options()

---
 tests/legacy_api/test_window.py | 4 ++--
 tests/test_window.py            | 6 +++---
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index 7b2b2d130..b1bbcd175 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -52,7 +52,7 @@ def test_fresh_window_data(session: Session) -> None:
     """Verify window data is fresh."""
     attached_window = session.attached_window
     assert attached_window is not None
-    pane_base_idx = attached_window.show_window_option("pane-base-index", g=True)
+    pane_base_idx = attached_window.show_option("pane-base-index", _global=True)
     assert pane_base_idx is not None
     pane_base_index = int(pane_base_idx)
 
@@ -252,7 +252,7 @@ def test_show_window_options(session: Session) -> None:
     assert isinstance(options, dict)
 
 
-def test_set_show_window_options(session: Session) -> None:
+def test_set_window_and_show_window_options(session: Session) -> None:
     """Set option then Window.show_window_options(key)."""
     window = session.new_window(window_name="test_window")
 
diff --git a/tests/test_window.py b/tests/test_window.py
index 70fffa36e..a9181ccf7 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -59,7 +59,7 @@ def test_fresh_window_data(session: Session) -> None:
     """Verify window data is fresh."""
     active_window = session.active_window
     assert active_window is not None
-    pane_base_idx = active_window.show_window_option("pane-base-index", g=True)
+    pane_base_idx = active_window.show_option("pane-base-index", _global=True)
     assert pane_base_idx is not None
     pane_base_index = int(pane_base_idx)
 
@@ -268,8 +268,8 @@ def test_show_window_options(session: Session) -> None:
     assert isinstance(options, dict)
 
 
-def test_set_show_window_options(session: Session) -> None:
-    """Set option then Window.show_window_options(key)."""
+def test_set_window_and_show_window_options(session: Session) -> None:
+    """Window.set_window_option() then Window.show_window_options(key)."""
     window = session.new_window(window_name="test_window")
 
     window.set_window_option("main-pane-height", 20)

From 3c86458573f6dab0910facb92285c54ce6ccb547 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Mon, 5 Feb 2024 18:41:17 -0600
Subject: [PATCH 004/136] tests(Window): set_option

---
 tests/legacy_api/test_window.py | 18 +++++++++++++++++-
 tests/test_window.py            | 16 ++++++++++++++++
 2 files changed, 33 insertions(+), 1 deletion(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index b1bbcd175..5095646d6 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -253,7 +253,7 @@ def test_show_window_options(session: Session) -> None:
 
 
 def test_set_window_and_show_window_options(session: Session) -> None:
-    """Set option then Window.show_window_options(key)."""
+    """Window.set_window_option() then Window.show_window_options(key)."""
     window = session.new_window(window_name="test_window")
 
     window.set_window_option("main-pane-height", 20)
@@ -267,6 +267,22 @@ def test_set_window_and_show_window_options(session: Session) -> None:
     assert window.show_window_option("pane-border-format") == " #P "
 
 
+def test_set_and_show_window_options(session: Session) -> None:
+    """Window.set_option() then Window.show_window_options(key)."""
+    window = session.new_window(window_name="test_window")
+
+    window.set_option("main-pane-height", 20)
+    assert window.show_window_option("main-pane-height") == 20
+
+    window.set_option("main-pane-height", 40)
+    assert window.show_window_option("main-pane-height") == 40
+    assert window.show_window_options()["main-pane-height"] == 40
+
+    if has_gte_version("2.3"):
+        window.set_option("pane-border-format", " #P ")
+        assert window.show_window_option("pane-border-format") == " #P "
+
+
 def test_empty_window_option_returns_None(session: Session) -> None:
     """Verify unset window option returns None."""
     window = session.new_window(window_name="test_window")
diff --git a/tests/test_window.py b/tests/test_window.py
index a9181ccf7..789b76bed 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -283,6 +283,22 @@ def test_set_window_and_show_window_options(session: Session) -> None:
     assert window.show_window_option("pane-border-format") == " #P "
 
 
+def test_set_and_show_window_options(session: Session) -> None:
+    """Window.set_option() then Window.show_window_options(key)."""
+    window = session.new_window(window_name="test_window")
+
+    window.set_option("main-pane-height", 20)
+    assert window.show_window_option("main-pane-height") == 20
+
+    window.set_option("main-pane-height", 40)
+    assert window.show_window_option("main-pane-height") == 40
+    assert window.show_window_options()["main-pane-height"] == 40
+
+    if has_gte_version("2.3"):
+        window.set_option("pane-border-format", " #P ")
+        assert window.show_window_option("pane-border-format") == " #P "
+
+
 def test_empty_window_option_returns_None(session: Session) -> None:
     """Verify unset window option returns None."""
     window = session.new_window(window_name="test_window")

From d47023b108e292d3c8c32fb3ac799b8838a1b319 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Mon, 5 Feb 2024 20:30:45 -0600
Subject: [PATCH 005/136] Window: Add show_option(), deprecate
 show_window_option()

---
 src/libtmux/window.py | 44 ++++++++++++++++++++++++++++++++++++-------
 1 file changed, 37 insertions(+), 7 deletions(-)

diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index 365bef7de..4f8bca45f 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -509,12 +509,8 @@ def set_option(
 
         return self
 
-    def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
-        """Return dict of options for window.
-
-        .. versionchanged:: 0.13.0
-
-           ``option`` removed, use show_window_option to return an individual option.
+    def show_options(self, g: bool | None = False) -> WindowOptionDict:
+        """Return a dict of options for the window.
 
         Parameters
         ----------
@@ -549,7 +545,7 @@ def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
 
         return window_options
 
-    def show_window_option(
+    def show_option(
         self,
         option: str,
         g: bool = False,
@@ -1024,6 +1020,40 @@ def set_window_option(
         )
         return self.set_option(option=option, value=value)
 
+    def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
+        """Show options for tmux window. Deprecated by :meth:`Window.show_options()`.
+
+        .. deprecated:: 0.26
+
+           Deprecated by :meth:`Window.show_options()`.
+
+        """
+        warnings.warn(
+            "Window.show_window_options() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.show_options(g=g)
+
+    def show_window_option(
+        self,
+        option: str,
+        g: bool = False,
+    ) -> str | int | None:
+        """Return option for target window. Deprecated by :meth:`Window.show_option()`.
+
+        .. deprecated:: 0.26
+
+           Deprecated by :meth:`Window.show_option()`.
+
+        """
+        warnings.warn(
+            "Window.show_window_option() is deprecated",
+            category=DeprecationWarning,
+            stacklevel=2,
+        )
+        return self.show_option(option=option, g=g)
+
     def get(self, key: str, default: t.Any | None = None) -> t.Any:
         """Return key-based lookup. Deprecated by attributes.
 

From cfd4763c3d8d998304cd69629b54a15339e98e54 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Tue, 6 Feb 2024 04:13:35 -0600
Subject: [PATCH 006/136] chore(Window): {set,show}-window-option ->
 {set,show}-option -w

---
 src/libtmux/window.py | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index 4f8bca45f..14ce5d657 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -448,7 +448,7 @@ def set_option(
     ) -> Window:
         """Set option for tmux window.
 
-        Wraps ``$ tmux set-window-option <option> <value>``.
+        Wraps ``$ tmux set-option <option> <value>``.
 
         Parameters
         ----------
@@ -498,7 +498,8 @@ def set_option(
             flags.append("-g")
 
         cmd = self.cmd(
-            "set-window-option",
+            "set-option",
+            "-w",
             option,
             value,
             *flags,
@@ -522,7 +523,10 @@ def show_options(self, g: bool | None = False) -> WindowOptionDict:
         if g:
             tmux_args += ("-g",)
 
-        tmux_args += ("show-window-options",)
+        tmux_args += (
+            "show-options",
+            "-w",
+        )
         cmd = self.cmd(*tmux_args)
 
         output = cmd.stdout
@@ -572,7 +576,7 @@ def show_option(
 
         tmux_args += (option,)
 
-        cmd = self.cmd("show-window-options", *tmux_args)
+        cmd = self.cmd("show-options", "-w", *tmux_args)
 
         if len(cmd.stderr):
             handle_option_error(cmd.stderr[0])

From 9b69ac7d6ca2207b75eb74cfa4d24d4861c66dd7 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Tue, 6 Feb 2024 04:38:57 -0600
Subject: [PATCH 007/136] libtmux.constants: Add OptionScope and
 OPTION_SCOPE_FLAG_MAP

---
 src/libtmux/constants.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/libtmux/constants.py b/src/libtmux/constants.py
index b4c23ee64..0e98203c3 100644
--- a/src/libtmux/constants.py
+++ b/src/libtmux/constants.py
@@ -51,3 +51,28 @@ class PaneDirection(enum.Enum):
     PaneDirection.Right: ["-h"],
     PaneDirection.Left: ["-h", "-b"],
 }
+
+
+class _DefaultOptionScope:
+    # Sentinel value for default scope
+    ...
+
+
+DEFAULT_OPTION_SCOPE: _DefaultOptionScope = _DefaultOptionScope()
+
+
+class OptionScope(enum.Enum):
+    """Scope used with ``set-option`` and ``show-option(s)`` commands."""
+
+    Server = "SERVER"
+    Session = "SESSION"
+    Window = "WINDOW"
+    Pane = "PANE"
+
+
+OPTION_SCOPE_FLAG_MAP: dict[OptionScope, str] = {
+    OptionScope.Server: "-s",
+    OptionScope.Session: "",
+    OptionScope.Window: "-w",
+    OptionScope.Pane: "-p",
+}

From ebbacec2f58e278fb4fe2dd77390f8edab80c6cc Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Tue, 6 Feb 2024 04:43:43 -0600
Subject: [PATCH 008/136] feat(Window): scope param for
 Window.{set,show}_option

---
 src/libtmux/window.py | 95 ++++++++++++++++++++++++++++++++++++++-----
 1 file changed, 85 insertions(+), 10 deletions(-)

diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index 14ce5d657..c22e221f0 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -16,7 +16,9 @@
 from libtmux._internal.query_list import QueryList
 from libtmux.common import tmux_cmd
 from libtmux.constants import (
+    OPTION_SCOPE_FLAG_MAP,
     RESIZE_ADJUSTMENT_DIRECTION_FLAG_MAP,
+    OptionScope,
     PaneDirection,
     ResizeAdjustmentDirection,
     WindowDirection,
@@ -445,6 +447,7 @@ def set_option(
         suppress_warnings: bool | None = None,
         append: bool | None = None,
         g: bool | None = None,
+        scope: OptionScope | None = None,
     ) -> Window:
         """Set option for tmux window.
 
@@ -497,12 +500,18 @@ def set_option(
             assert isinstance(g, bool)
             flags.append("-g")
 
+        if scope is not None:
+            assert scope in OPTION_SCOPE_FLAG_MAP
+            flags.append(
+                OPTION_SCOPE_FLAG_MAP[scope],
+            )
+
         cmd = self.cmd(
             "set-option",
             "-w",
+            *flags,
             option,
             value,
-            *flags,
         )
 
         if isinstance(cmd.stderr, list) and len(cmd.stderr):
@@ -510,7 +519,44 @@ def set_option(
 
         return self
 
-    def show_options(self, g: bool | None = False) -> WindowOptionDict:
+    @t.overload
+    def show_options(
+        self,
+        g: bool | None,
+        scope: OptionScope | None,
+        include_hooks: bool | None,
+        include_parents: bool | None,
+        values_only: t.Literal[True],
+    ) -> list[str]: ...
+
+    @t.overload
+    def show_options(
+        self,
+        g: bool | None,
+        scope: OptionScope | None,
+        include_hooks: bool | None,
+        include_parents: bool | None,
+        values_only: None = None,
+    ) -> WindowOptionDict: ...
+
+    @t.overload
+    def show_options(
+        self,
+        g: bool | None = None,
+        scope: OptionScope | None = None,
+        include_hooks: bool | None = None,
+        include_parents: bool | None = None,
+        values_only: t.Literal[False] = False,
+    ) -> WindowOptionDict: ...
+
+    def show_options(
+        self,
+        g: bool | None = False,
+        scope: OptionScope | None = OptionScope.Window,
+        include_hooks: bool | None = None,
+        include_parents: bool | None = None,
+        values_only: bool | None = False,
+    ) -> WindowOptionDict | list[str]:
         """Return a dict of options for the window.
 
         Parameters
@@ -523,11 +569,20 @@ def show_options(self, g: bool | None = False) -> WindowOptionDict:
         if g:
             tmux_args += ("-g",)
 
-        tmux_args += (
-            "show-options",
-            "-w",
-        )
-        cmd = self.cmd(*tmux_args)
+        if scope is not None:
+            assert scope in OPTION_SCOPE_FLAG_MAP
+            tmux_args += (OPTION_SCOPE_FLAG_MAP[scope],)
+
+        if include_parents is not None and include_parents:
+            tmux_args += ("-A",)
+
+        if include_hooks is not None and include_hooks:
+            tmux_args += ("-H",)
+
+        if values_only is not None and values_only:
+            tmux_args += ("-v",)
+
+        cmd = self.cmd("show-options", *tmux_args)
 
         output = cmd.stdout
 
@@ -553,6 +608,9 @@ def show_option(
         self,
         option: str,
         g: bool = False,
+        scope: OptionScope | None = OptionScope.Window,
+        include_hooks: bool | None = None,
+        include_parents: bool | None = None,
     ) -> str | int | None:
         """Return option value for the target window.
 
@@ -574,9 +632,19 @@ def show_option(
         if g:
             tmux_args += ("-g",)
 
+        if scope is not None:
+            assert scope in OPTION_SCOPE_FLAG_MAP
+            tmux_args += (OPTION_SCOPE_FLAG_MAP[scope],)
+
+        if include_parents is not None and include_parents:
+            tmux_args += ("-A",)
+
+        if include_hooks is not None and include_hooks:
+            tmux_args += ("-H",)
+
         tmux_args += (option,)
 
-        cmd = self.cmd("show-options", "-w", *tmux_args)
+        cmd = self.cmd("show-options", *tmux_args)
 
         if len(cmd.stderr):
             handle_option_error(cmd.stderr[0])
@@ -1037,7 +1105,10 @@ def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
             category=DeprecationWarning,
             stacklevel=2,
         )
-        return self.show_options(g=g)
+        return self.show_options(
+            g=g,
+            scope=OptionScope.Window,
+        )
 
     def show_window_option(
         self,
@@ -1056,7 +1127,11 @@ def show_window_option(
             category=DeprecationWarning,
             stacklevel=2,
         )
-        return self.show_option(option=option, g=g)
+        return self.show_option(
+            option=option,
+            g=g,
+            scope=OptionScope.Window,
+        )
 
     def get(self, key: str, default: t.Any | None = None) -> t.Any:
         """Return key-based lookup. Deprecated by attributes.

From 34316304c03f61fbbd4b6c06821422a642a78fb5 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Tue, 6 Feb 2024 05:12:48 -0600
Subject: [PATCH 009/136] tests(Window): show_options w/ scope

---
 tests/legacy_api/test_window.py |  2 +-
 tests/test_window.py            | 24 +++++++++++++++++++++++-
 2 files changed, 24 insertions(+), 2 deletions(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index 5095646d6..8c8ae0b1b 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -52,7 +52,7 @@ def test_fresh_window_data(session: Session) -> None:
     """Verify window data is fresh."""
     attached_window = session.attached_window
     assert attached_window is not None
-    pane_base_idx = attached_window.show_option("pane-base-index", _global=True)
+    pane_base_idx = attached_window.show_option("pane-base-index", global_=True)
     assert pane_base_idx is not None
     pane_base_index = int(pane_base_idx)
 
diff --git a/tests/test_window.py b/tests/test_window.py
index 789b76bed..9d15d71d0 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -13,6 +13,7 @@
 from libtmux import exc
 from libtmux._internal.query_list import ObjectDoesNotExist
 from libtmux.constants import (
+    OptionScope,
     PaneDirection,
     ResizeAdjustmentDirection,
     WindowDirection,
@@ -59,7 +60,7 @@ def test_fresh_window_data(session: Session) -> None:
     """Verify window data is fresh."""
     active_window = session.active_window
     assert active_window is not None
-    pane_base_idx = active_window.show_option("pane-base-index", _global=True)
+    pane_base_idx = active_window.show_option("pane-base-index", global_=True)
     assert pane_base_idx is not None
     pane_base_index = int(pane_base_idx)
 
@@ -267,6 +268,27 @@ def test_show_window_options(session: Session) -> None:
     options = window.show_window_options()
     assert isinstance(options, dict)
 
+    options_2 = window.show_options()
+    assert isinstance(options_2, dict)
+
+    pane_options = window.show_options(scope=OptionScope.Pane)
+    assert isinstance(pane_options, dict)
+
+    pane_options_global = window.show_options(scope=OptionScope.Pane, global_=True)
+    assert isinstance(pane_options_global, dict)
+
+    window_options = window.show_options(scope=OptionScope.Window)
+    assert isinstance(window_options, dict)
+
+    window_options_global = window.show_options(scope=OptionScope.Window, global_=True)
+    assert isinstance(window_options_global, dict)
+
+    server_options = window.show_options(scope=OptionScope.Server)
+    assert isinstance(server_options, dict)
+
+    server_options_global = window.show_options(scope=OptionScope.Server, global_=True)
+    assert isinstance(server_options_global, dict)
+
 
 def test_set_window_and_show_window_options(session: Session) -> None:
     """Window.set_window_option() then Window.show_window_options(key)."""

From 4d2fd59c10c325a3be0e8a8c2798f74a0fe7665f Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Tue, 6 Feb 2024 05:46:33 -0600
Subject: [PATCH 010/136] tests: show_window_option() -> show_option()

---
 tests/legacy_api/test_window.py | 12 ++++++------
 tests/test_window.py            | 10 +++++-----
 2 files changed, 11 insertions(+), 11 deletions(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index 8c8ae0b1b..c7ceb86dd 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -267,20 +267,20 @@ def test_set_window_and_show_window_options(session: Session) -> None:
     assert window.show_window_option("pane-border-format") == " #P "
 
 
-def test_set_and_show_window_options(session: Session) -> None:
-    """Window.set_option() then Window.show_window_options(key)."""
+def test_set_and_show_options(session: Session) -> None:
+    """Window.set_option() then Window.show_options(key)."""
     window = session.new_window(window_name="test_window")
 
     window.set_option("main-pane-height", 20)
-    assert window.show_window_option("main-pane-height") == 20
+    assert window.show_option("main-pane-height") == 20
 
     window.set_option("main-pane-height", 40)
-    assert window.show_window_option("main-pane-height") == 40
-    assert window.show_window_options()["main-pane-height"] == 40
+    assert window.show_option("main-pane-height") == 40
+    assert window.show_options()["main-pane-height"] == 40
 
     if has_gte_version("2.3"):
         window.set_option("pane-border-format", " #P ")
-        assert window.show_window_option("pane-border-format") == " #P "
+        assert window.show_option("pane-border-format") == " #P "
 
 
 def test_empty_window_option_returns_None(session: Session) -> None:
diff --git a/tests/test_window.py b/tests/test_window.py
index 9d15d71d0..7bce74636 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -306,19 +306,19 @@ def test_set_window_and_show_window_options(session: Session) -> None:
 
 
 def test_set_and_show_window_options(session: Session) -> None:
-    """Window.set_option() then Window.show_window_options(key)."""
+    """Window.set_option() then Window.show_options(key)."""
     window = session.new_window(window_name="test_window")
 
     window.set_option("main-pane-height", 20)
-    assert window.show_window_option("main-pane-height") == 20
+    assert window.show_option("main-pane-height") == 20
 
     window.set_option("main-pane-height", 40)
-    assert window.show_window_option("main-pane-height") == 40
-    assert window.show_window_options()["main-pane-height"] == 40
+    assert window.show_option("main-pane-height") == 40
+    assert window.show_options()["main-pane-height"] == 40
 
     if has_gte_version("2.3"):
         window.set_option("pane-border-format", " #P ")
-        assert window.show_window_option("pane-border-format") == " #P "
+        assert window.show_option("pane-border-format") == " #P "
 
 
 def test_empty_window_option_returns_None(session: Session) -> None:

From c7ddb03ce3710e5c94a0da9f8ec5c1cb2d6522b1 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 8 Feb 2024 12:56:45 -0600
Subject: [PATCH 011/136] feat(common): Add CmdMixin, CmdProtocol

---
 src/libtmux/common.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/libtmux/common.py b/src/libtmux/common.py
index 056c888fc..b10d46f24 100644
--- a/src/libtmux/common.py
+++ b/src/libtmux/common.py
@@ -35,6 +35,20 @@
 PaneDict = dict[str, t.Any]
 
 
+class CmdProtocol(t.Protocol):
+    """Command protocol for tmux command."""
+
+    def __call__(self, cmd: str, *args: t.Any, **kwargs: t.Any) -> tmux_cmd:
+        """Wrap tmux_cmd."""
+        ...
+
+
+class CmdMixin:
+    """Command mixin for tmux command."""
+
+    cmd: CmdProtocol
+
+
 class EnvironmentMixin:
     """Mixin for manager session and server level environment variables in tmux."""
 

From 273c31f3546d89fa9c651d7b73fc427d86f59cbb Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 8 Feb 2024 12:50:04 -0600
Subject: [PATCH 012/136] refactor!(options): Move handle_options_error ->
 options

---
 src/libtmux/common.py  | 31 -----------------------------
 src/libtmux/options.py | 45 ++++++++++++++++++++++++++++++++++++++++++
 src/libtmux/session.py |  2 +-
 src/libtmux/window.py  |  3 ++-
 4 files changed, 48 insertions(+), 33 deletions(-)
 create mode 100644 src/libtmux/options.py

diff --git a/src/libtmux/common.py b/src/libtmux/common.py
index b10d46f24..7da066eb7 100644
--- a/src/libtmux/common.py
+++ b/src/libtmux/common.py
@@ -467,37 +467,6 @@ def session_check_name(session_name: str | None) -> None:
         raise exc.BadSessionName(reason="contains colons", session_name=session_name)
 
 
-def handle_option_error(error: str) -> type[exc.OptionError]:
-    """Raise exception if error in option command found.
-
-    There are 3 different types of option errors:
-
-    - unknown option
-    - invalid option
-    - ambiguous option
-
-    All errors raised will have the base error of :exc:`exc.OptionError`. So to
-    catch any option error, use ``except exc.OptionError``.
-
-    Parameters
-    ----------
-    error : str
-        Error response from subprocess call.
-
-    Raises
-    ------
-    :exc:`exc.OptionError`, :exc:`exc.UnknownOption`, :exc:`exc.InvalidOption`,
-    :exc:`exc.AmbiguousOption`
-    """
-    if "unknown option" in error:
-        raise exc.UnknownOption(error)
-    if "invalid option" in error:
-        raise exc.InvalidOption(error)
-    if "ambiguous option" in error:
-        raise exc.AmbiguousOption(error)
-    raise exc.OptionError(error)  # Raise generic option error
-
-
 def get_libtmux_version() -> LooseVersion:
     """Return libtmux version is a PEP386 compliant format.
 
diff --git a/src/libtmux/options.py b/src/libtmux/options.py
new file mode 100644
index 000000000..0e10abe00
--- /dev/null
+++ b/src/libtmux/options.py
@@ -0,0 +1,45 @@
+"""Helpers for tmux options."""
+
+from __future__ import annotations
+
+import logging
+
+from . import exc
+
+logger = logging.getLogger(__name__)
+
+
+def handle_option_error(error: str) -> type[exc.OptionError]:
+    """Raise exception if error in option command found.
+
+    In tmux 3.0, show-option and show-window-option return invalid option instead of
+    unknown option. See https://github.com/tmux/tmux/blob/3.0/cmd-show-options.c.
+
+    In tmux >2.4, there are 3 different types of option errors:
+
+    - unknown option
+    - invalid option
+    - ambiguous option
+
+    In tmux <2.4, unknown option was the only option.
+
+    All errors raised will have the base error of :exc:`exc.OptionError`. So to
+    catch any option error, use ``except exc.OptionError``.
+
+    Parameters
+    ----------
+    error : str
+        Error response from subprocess call.
+
+    Raises
+    ------
+    :exc:`exc.OptionError`, :exc:`exc.UnknownOption`, :exc:`exc.InvalidOption`,
+    :exc:`exc.AmbiguousOption`
+    """
+    if "unknown option" in error:
+        raise exc.UnknownOption(error)
+    if "invalid option" in error:
+        raise exc.InvalidOption(error)
+    if "ambiguous option" in error:
+        raise exc.AmbiguousOption(error)
+    raise exc.OptionError(error)  # Raise generic option error
diff --git a/src/libtmux/session.py b/src/libtmux/session.py
index 20696538c..60e4039da 100644
--- a/src/libtmux/session.py
+++ b/src/libtmux/session.py
@@ -24,9 +24,9 @@
 from .common import (
     EnvironmentMixin,
     WindowDict,
-    handle_option_error,
     session_check_name,
 )
+from .options import handle_option_error
 
 if t.TYPE_CHECKING:
     import sys
diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index c22e221f0..b2f767b60 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -27,7 +27,7 @@
 from libtmux.pane import Pane
 
 from . import exc
-from .common import PaneDict, WindowOptionDict, handle_option_error
+from .options import handle_option_error
 
 if t.TYPE_CHECKING:
     import sys
@@ -35,6 +35,7 @@
 
     from libtmux._internal.types import StrPath
 
+    from .common import PaneDict, WindowOptionDict
     from .server import Server
     from .session import Session
 

From 75de0b6399a0675758d197271f2ad6e9f83920d1 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 20 Jun 2024 05:21:47 -0500
Subject: [PATCH 013/136] feat(internal[sparse_array]): Add SparseArray

---
 src/libtmux/_internal/sparse_array.py | 56 +++++++++++++++++++++++++++
 1 file changed, 56 insertions(+)
 create mode 100644 src/libtmux/_internal/sparse_array.py

diff --git a/src/libtmux/_internal/sparse_array.py b/src/libtmux/_internal/sparse_array.py
new file mode 100644
index 000000000..c5c8bedff
--- /dev/null
+++ b/src/libtmux/_internal/sparse_array.py
@@ -0,0 +1,56 @@
+"""Sparse array for libtmux options and hooks."""
+
+from __future__ import annotations
+
+import typing as t
+
+if t.TYPE_CHECKING:
+    from typing import TypeAlias, TypeGuard
+
+    from libtmux.options import ExplodedComplexUntypedOptionsDict
+
+
+T = t.TypeVar("T")
+HookArray: TypeAlias = "dict[str, SparseArray[str]]"
+
+
+def is_sparse_array_list(
+    items: ExplodedComplexUntypedOptionsDict,
+) -> TypeGuard[HookArray]:
+    return all(
+        isinstance(
+            v,
+            SparseArray,
+        )
+        for k, v in items.items()
+    )
+
+
+class SparseArray(dict[int, T], t.Generic[T]):
+    """Support non-sequential indexes while maintaining :class:`list`-like behavior.
+
+    A normal :class:`list` would raise :exc:`IndexError`.
+
+    There are no native sparse arrays in python that contain non-sequential indexes and
+    maintain list-like behavior. This is useful for handling libtmux options and hooks:
+
+    ``command-alias[1] split-pane=split-window`` to
+    ``{'command-alias[1]': {'split-pane=split-window'}}``
+
+    :class:`list` would lose indice info, and :class:`dict` would lose list-like
+    behavior.
+    """
+
+    def add(self, index: int, value: T) -> None:
+        self[index] = value
+
+    def append(self, value: T) -> None:
+        index = max(self.keys()) + 1
+        self[index] = value
+
+    def iter_values(self) -> t.Iterator[T]:
+        for index in sorted(self.keys()):
+            yield self[index]
+
+    def as_list(self) -> list[T]:
+        return [self[index] for index in sorted(self.keys())]

From beac94b2963abf56d254922f13337675a6fca0ba Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 8 Feb 2024 12:43:40 -0600
Subject: [PATCH 014/136] feat(options): Add OptionsMixin

---
 src/libtmux/options.py           | 1087 +++++++++++++++++++++++++++++-
 src/libtmux/window.py            |   12 +-
 tests/legacy_api/test_session.py |   26 +-
 tests/legacy_api/test_window.py  |   12 +-
 tests/test_session.py            |   26 +-
 tests/test_window.py             |   26 +-
 6 files changed, 1137 insertions(+), 52 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index 0e10abe00..89ced4f50 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -1,11 +1,117 @@
-"""Helpers for tmux options."""
+# ruff: NOQA: E501
+"""Helpers for tmux options.
+
+Option parsing function trade testability and clarity for performance.
+
+Tmux options
+------------
+
+Options in tmux consist of empty values, strings, integers, arrays, and complex shapes.
+
+Marshalling types from text:
+
+Integers: ``buffer-limit 50`` to ``{'buffer-limit': 50}``
+Booleans: ``exit-unattached on`` to ``{'exit-unattached': True}``
+
+Exploding arrays:
+
+``command-alias[1] split-pane=split-window`` to
+``{'command-alias[1]': {'split-pane=split-window'}}``
+
+However, there is no equivalent to the above type of object in Python (a sparse array),
+so a SparseArray is used.
+
+Exploding complex shapes:
+
+``"choose-session=choose-tree -s"`` to ``{'choose-session': 'choose-tree -s'}``
+
+Finally, we need to convert hyphenated keys to underscored attribute names and assign
+values, as python does not allow hyphens in attribute names.
+
+``command-alias`` is ``command_alias`` in python.
+
+Options object
+--------------
+Dataclasses are used to provide typed access to tmux' option shape.
+
+Extra data gleaned from the options, such as user options (custom data) and an option
+being inherited,
+
+User options
+------------
+There are also custom user options, preceded with @, which exist are stored to
+`Options.context.user_options` as a dictionary.
+
+> tmux set-option -w my-custom-variable my-value
+invalid option: my-custom-option
+
+> tmux set-option -w @my-custom-option my-value
+> tmux show-option -w
+@my-custom-optione my-value
+
+Inherited options
+-----------------
+
+`tmux show-options` -A can include inherited options. The raw output of an inherited
+option is detected by the key having a *:
+
+```
+visual-activity* on
+visual-bell* off
+```
+
+A list of options that are inherited is kept at `Options.context._inherited_options` and
+`Options.context.inherited_options`.
+
+They are mixed with the normal options,
+to differentiate them, run `show_options()` without ``include_inherited=True``.
+"""
 
 from __future__ import annotations
 
+import io
 import logging
+import re
+import shlex
+import typing as t
+import warnings
+
+from libtmux._internal.sparse_array import SparseArray
+from libtmux.common import CmdMixin
+from libtmux.constants import (
+    DEFAULT_OPTION_SCOPE,
+    OPTION_SCOPE_FLAG_MAP,
+    OptionScope,
+    _DefaultOptionScope,
+)
 
 from . import exc
 
+if t.TYPE_CHECKING:
+    from typing import TypeAlias
+
+    from typing_extensions import Self
+
+    from libtmux._internal.constants import TerminalFeatures
+    from libtmux.common import tmux_cmd
+
+
+TerminalOverride = dict[str, str | None]
+TerminalOverrides = dict[str, TerminalOverride]
+CommandAliases = dict[str, str]
+
+OptionDict: TypeAlias = dict[str, t.Any]
+UntypedOptionsDict: TypeAlias = dict[str, str | None]
+ExplodedUntypedOptionsDict: TypeAlias = dict[
+    str,
+    str | int | list[str] | dict[str, list[str]],
+]
+ExplodedComplexUntypedOptionsDict: TypeAlias = dict[
+    str,
+    t.Union[str, int, list[str | int], dict[str, list[str | int]], "SparseArray[str]"]
+    | None,
+]
+
 logger = logging.getLogger(__name__)
 
 
@@ -35,6 +141,22 @@ def handle_option_error(error: str) -> type[exc.OptionError]:
     ------
     :exc:`exc.OptionError`, :exc:`exc.UnknownOption`, :exc:`exc.InvalidOption`,
     :exc:`exc.AmbiguousOption`
+
+    Examples
+    --------
+    >>> result = server.cmd(
+    ...     'set-option',
+    ...     'unknown-option-name',
+    ... )
+
+    >>> bool(isinstance(result.stderr, list) and len(result.stderr))
+    True
+
+    >>> import pytest
+    >>> from libtmux import exc
+
+    >>> with pytest.raises(exc.OptionError):
+    ...     handle_option_error(result.stderr[0])
     """
     if "unknown option" in error:
         raise exc.UnknownOption(error)
@@ -43,3 +165,966 @@ def handle_option_error(error: str) -> type[exc.OptionError]:
     if "ambiguous option" in error:
         raise exc.AmbiguousOption(error)
     raise exc.OptionError(error)  # Raise generic option error
+
+
+_V = t.TypeVar("_V")
+ConvertedValue: TypeAlias = str | int | bool | None
+ConvertedValues: TypeAlias = (
+    ConvertedValue
+    | list[ConvertedValue]
+    | dict[str, ConvertedValue]
+    | SparseArray[ConvertedValue]
+)
+
+
+def convert_value(
+    value: _V | None,
+) -> ConvertedValue | _V | None:
+    """Convert raw option strings to python types.
+
+    Examples
+    --------
+    >>> convert_value("on")
+    True
+    >>> convert_value("off")
+    False
+
+    >>> convert_value("1")
+    1
+    >>> convert_value("50")
+    50
+
+    >>> convert_value("%50")
+    '%50'
+    """
+    if not isinstance(value, str):
+        return value
+
+    if value.isdigit():
+        return int(value)
+
+    if value == "on":
+        return True
+
+    if value == "off":
+        return False
+
+    return value
+
+
+def convert_values(
+    value: _V | None,
+) -> ConvertedValues | _V | None:
+    """Recursively convert values to python types via :func:`convert_value`.
+
+    >>> convert_values(None)
+
+    >>> convert_values("on")
+    True
+    >>> convert_values("off")
+    False
+
+    >>> convert_values(["on"])
+    [True]
+    >>> convert_values(["off"])
+    [False]
+
+    >>> convert_values({"window_index": "1"})
+    {'window_index': 1}
+
+    >>> convert_values({"visual-bell": "on"})
+    {'visual-bell': True}
+    """
+    if value is None:
+        return None
+    if isinstance(value, dict):
+        for k, v in value.items():
+            value[k] = convert_value(v)
+        return value
+    if isinstance(value, SparseArray):
+        for v in value.iter_values():
+            value[v] = convert_value(v)
+        return value
+    if isinstance(value, list):
+        for idx, v in enumerate(value):
+            value[idx] = convert_value(v)
+        return value
+    return convert_value(value)
+
+
+def parse_options_to_dict(
+    stdout: t.IO[str],
+) -> UntypedOptionsDict:
+    r"""Process subprocess.stdout options or hook output to flat, naive, untyped dict.
+
+    Does not explode arrays or deep values.
+
+    Examples
+    --------
+    >>> import io
+
+    >>> raw_options = io.StringIO("status-keys vi")
+    >>> parse_options_to_dict(raw_options) == {"status-keys": "vi"}
+    True
+
+    >>> int_options = io.StringIO("message-limit 50")
+    >>> parse_options_to_dict(int_options) == {"message-limit": "50"}
+    True
+
+    >>> empty_option = io.StringIO("user-keys")
+    >>> parse_options_to_dict(empty_option) == {"user-keys": None}
+    True
+
+    >>> array_option = io.StringIO("command-alias[0] split-pane=split-window")
+    >>> parse_options_to_dict(array_option) == {
+    ... "command-alias[0]": "split-pane=split-window"}
+    True
+
+    >>> array_option = io.StringIO("command-alias[40] split-pane=split-window")
+    >>> parse_options_to_dict(array_option) == {
+    ... "command-alias[40]": "split-pane=split-window"}
+    True
+
+    >>> many_options = io.StringIO(r'''status-keys
+    ... command-alias[0] split-pane=split-window
+    ... ''')
+    >>> parse_options_to_dict(many_options) == {
+    ... "command-alias[0]": "split-pane=split-window",
+    ... "status-keys": None,}
+    True
+
+    >>> many_more_options = io.StringIO(r'''
+    ... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
+    ... terminal-features[1] screen*:title
+    ... ''')
+    >>> parse_options_to_dict(many_more_options) == {
+    ... "terminal-features[0]": "xterm*:clipboard:ccolour:cstyle:focus",
+    ... "terminal-features[1]": "screen*:title",}
+    True
+
+    >>> quoted_option = io.StringIO(r'''
+    ... command-alias[0] "choose-session=choose-tree -s"
+    ... ''')
+    >>> parse_options_to_dict(quoted_option) == {
+    ... "command-alias[0]": "choose-session=choose-tree -s",
+    ... }
+    True
+    """
+    output: UntypedOptionsDict = {}
+
+    val: ConvertedValue | None = None
+
+    for item in stdout.readlines():
+        if " " in item:
+            try:
+                key, val = shlex.split(item)
+            except ValueError:
+                key, val = item.split(" ", maxsplit=1)
+        else:
+            key, val = item, None
+        key = key.strip()
+
+        if key:
+            if isinstance(val, str) and val.endswith("\n"):
+                val = val.rstrip("\n")
+
+            output[key] = val
+    return output
+
+
+def explode_arrays(
+    _dict: UntypedOptionsDict,
+    force_array: bool = False,
+) -> ExplodedUntypedOptionsDict:
+    """Explode flat, naive options dict's option arrays.
+
+    Examples
+    --------
+    >>> import io
+
+    >>> many_more_options = io.StringIO(r'''
+    ... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
+    ... terminal-features[1] screen*:title
+    ... ''')
+    >>> many_more_flat_dict = parse_options_to_dict(many_more_options)
+    >>> many_more_flat_dict == {
+    ... "terminal-features[0]": "xterm*:clipboard:ccolour:cstyle:focus",
+    ... "terminal-features[1]": "screen*:title",}
+    True
+    >>> explode_arrays(many_more_flat_dict) == {
+    ... "terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
+    ... 1: "screen*:title"}}
+    True
+
+    tmux arrays allow non-sequential indexes, so we need to support that:
+
+    >>> explode_arrays(parse_options_to_dict(io.StringIO(r'''
+    ... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
+    ... terminal-features[5] screen*:title
+    ... '''))) == {
+    ... "terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
+    ... 5: "screen*:title"}}
+    True
+    """
+    options: dict[str, t.Any] = {}
+    for key, val in _dict.items():
+        Default: type[dict[t.Any, t.Any] | SparseArray[str]] = (
+            dict if isinstance(key, str) and key == "terminal-features" else SparseArray
+        )
+        if "[" not in key:
+            if force_array:
+                options[key] = Default()
+                if val is not None:
+                    options[key][0] = val
+            else:
+                options[key] = val
+            continue
+
+        try:
+            matchgroup = re.match(
+                r"(?P<hook>[\w-]+)(\[(?P<index>\d+)\])?",
+                key,
+            )
+            if matchgroup is not None:
+                match = matchgroup.groupdict()
+                if match.get("hook") and match.get("index"):
+                    key = match["hook"]
+                    index = int(match["index"])
+
+                    if options.get(key) is None:
+                        options[key] = Default()
+                    options[key][index] = val
+        except Exception:
+            if force_array and val:
+                options[key] = Default()
+                if isinstance(options[key], SparseArray):
+                    options[key][0] = val
+            else:
+                options[key] = val
+            logger.exception("Error parsing options")
+    return options
+
+
+def explode_complex(
+    _dict: ExplodedUntypedOptionsDict,
+) -> ExplodedComplexUntypedOptionsDict:
+    r"""Explode arrayed option's complex values.
+
+    Examples
+    --------
+    >>> import io
+
+    >>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
+    ... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
+    ... terminal-features[5] screen*:title
+    ... '''))))
+    {'terminal-features': {'xterm*': ['clipboard', 'ccolour', 'cstyle', 'focus'], 'screen*': ['title']}}
+
+    >>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
+    ... terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
+    ... terminal-features[5] screen*:title
+    ... ''')))) == {
+    ... "terminal-features": {"xterm*": ["clipboard", "ccolour", "cstyle", "focus"],
+    ... "screen*": ["title"]}}
+    True
+
+    >>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
+    ... command-alias[0] split-pane=split-window
+    ... command-alias[1] splitp=split-window
+    ... command-alias[2] "server-info=show-messages -JT"
+    ... ''')))) == {
+    ... "command-alias": {"split-pane": "split-window",
+    ... "splitp": "split-window",
+    ... "server-info": "show-messages -JT"}}
+    True
+
+    >>> explode_complex(explode_arrays({"terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
+    ... 1: "screen*:title"}}))
+    {'terminal-features': {0: 'xterm*:clipboard:ccolour:cstyle:focus', 1: 'screen*:title'}}
+
+    >>> explode_complex(explode_arrays({"terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
+    ... 8: "screen*:title"}})) == SparseArray({'terminal-features': {0:
+    ... 'xterm*:clipboard:ccolour:cstyle:focus', 8: 'screen*:title'}})
+    True
+
+    >>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
+    ... terminal-overrides[0] xterm-256color:Tc
+    ... terminal-overrides[1] *:U8=0
+    ... ''')))) == {
+    ... "terminal-overrides": {"xterm-256color": {"Tc": None},
+    ... "*": {"U8": 0}}}
+    True
+
+    >>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
+    ... user-keys[100] "\e[test"
+    ... user-keys[6] "\e\n"
+    ... user-keys[0] "\e[5;30012~"
+    ... ''')))) == {
+    ... "user-keys": {0: "\\e[5;30012~",
+    ... 6: "\\e\\n",
+    ... 100: "\\e[test"}}
+    True
+
+    >>> explode_complex(explode_arrays(parse_options_to_dict(io.StringIO(r'''
+    ... status-format[0] "#[align=left range=left #{E:status-left-style}]#[push-default]#{T;=/#{status-left-length}:status-left}#[pop-default]#[norange default]#[list=on align=#{status-justify}]#[list=left-marker]<#[list=right-marker]>#[list=on]#{W:#[range=window|#{window_index} #{E:window-status-style}#{?#{&&:#{window_last_flag},#{!=:#{E:window-status-last-style},default}}, #{E:window-status-last-style},}#{?#{&&:#{window_bell_flag},#{!=:#{E:window-status-bell-style},default}}, #{E:window-status-bell-style},#{?#{&&:#{||:#{window_activity_flag},#{window_silence_flag}},#{!=:#{E:window-status-activity-style},default}}, #{E:window-status-activity-style},}}]#[push-default]#{T:window-status-format}#[pop-default]#[norange default]#{?window_end_flag,,#{window-status-separator}},#[range=window|#{window_index} list=focus #{?#{!=:#{E:window-status-current-style},default},#{E:window-status-current-style},#{E:window-status-style}}#{?#{&&:#{window_last_flag},#{!=:#{E:window-status-last-style},default}}, #{E:window-status-last-style},}#{?#{&&:#{window_bell_flag},#{!=:#{E:window-status-bell-style},default}}, #{E:window-status-bell-style},#{?#{&&:#{||:#{window_activity_flag},#{window_silence_flag}},#{!=:#{E:window-status-activity-style},default}}, #{E:window-status-activity-style},}}]#[push-default]#{T:window-status-current-format}#[pop-default]#[norange list=on default]#{?window_end_flag,,#{window-status-separator}}}#[nolist align=right range=right #{E:status-right-style}]#[push-default]#{T;=/#{status-right-length}:status-right}#[pop-default]#[norange default]"
+    ... status-format[1] "#[align=centre]#{P:#{?pane_active,#[reverse],}#{pane_index}[#{pane_width}x#{pane_height}]#[default] }"
+    ... ''')))) == {
+    ... "status-format": {0: "#[align=left range=left #{E:status-left-style}]#[push-default]#{T;=/#{status-left-length}:status-left}#[pop-default]#[norange default]#[list=on align=#{status-justify}]#[list=left-marker]<#[list=right-marker]>#[list=on]#{W:#[range=window|#{window_index} #{E:window-status-style}#{?#{&&:#{window_last_flag},#{!=:#{E:window-status-last-style},default}}, #{E:window-status-last-style},}#{?#{&&:#{window_bell_flag},#{!=:#{E:window-status-bell-style},default}}, #{E:window-status-bell-style},#{?#{&&:#{||:#{window_activity_flag},#{window_silence_flag}},#{!=:#{E:window-status-activity-style},default}}, #{E:window-status-activity-style},}}]#[push-default]#{T:window-status-format}#[pop-default]#[norange default]#{?window_end_flag,,#{window-status-separator}},#[range=window|#{window_index} list=focus #{?#{!=:#{E:window-status-current-style},default},#{E:window-status-current-style},#{E:window-status-style}}#{?#{&&:#{window_last_flag},#{!=:#{E:window-status-last-style},default}}, #{E:window-status-last-style},}#{?#{&&:#{window_bell_flag},#{!=:#{E:window-status-bell-style},default}}, #{E:window-status-bell-style},#{?#{&&:#{||:#{window_activity_flag},#{window_silence_flag}},#{!=:#{E:window-status-activity-style},default}}, #{E:window-status-activity-style},}}]#[push-default]#{T:window-status-current-format}#[pop-default]#[norange list=on default]#{?window_end_flag,,#{window-status-separator}}}#[nolist align=right range=right #{E:status-right-style}]#[push-default]#{T;=/#{status-right-length}:status-right}#[pop-default]#[norange default]",
+    ... 1: "#[align=centre]#{P:#{?pane_active,#[reverse],}#{pane_index}[#{pane_width}x#{pane_height}]#[default] }",
+    ... }}
+    True
+    """
+    options: dict[str, t.Any] = {}
+    for key, val in _dict.items():
+        try:
+            if isinstance(val, SparseArray) and key == "terminal-features":
+                new_val: TerminalFeatures = {}
+
+                for item in val.iter_values():
+                    try:
+                        term, features = item.split(":", maxsplit=1)
+                        new_val[term] = features.split(":")
+                    except Exception:  # NOQA: PERF203
+                        logger.exception("Error parsing options")
+                options[key] = new_val
+                continue
+            if isinstance(val, SparseArray) and key == "terminal-overrides":
+                new_overrides: TerminalOverrides = {}
+
+                for item in val.iter_values():
+                    try:
+                        term, features = item.split(":", maxsplit=1)
+                        if term not in new_overrides:
+                            new_overrides[term] = {}
+                        if features and "=" in features:
+                            k, v = features.split("=")
+
+                            if v.isdigit():
+                                v = int(v)
+
+                            new_overrides[term][k] = v
+                        else:
+                            new_overrides[term][features] = None
+                    except Exception:  # NOQA: PERF203
+                        logger.exception("Error parsing options")
+                options[key] = new_overrides
+                continue
+            if isinstance(val, SparseArray) and key == "command-alias":
+                new_aliases: CommandAliases = {}
+
+                for item in val.iter_values():
+                    try:
+                        alias, command = item.split("=", maxsplit=1)
+                        if options.get(key) is None or not isinstance(
+                            options.get(key),
+                            dict,
+                        ):
+                            options[key] = {}
+                        new_aliases[alias] = command
+                    except Exception:  # NOQA: PERF203
+                        logger.exception("Error parsing options")
+                options[key] = new_aliases
+                continue
+            options[key] = val
+            continue
+
+        except Exception:
+            options[key] = val
+            logger.exception("Error parsing options")
+    return options
+
+
+class OptionsMixin(CmdMixin):
+    """Mixin for managing tmux options based on scope."""
+
+    default_option_scope: OptionScope | None
+
+    def __init__(self, default_option_scope: OptionScope | None = None) -> None:
+        """When not a user (custom) option, scope can be implied."""
+        if default_option_scope is not None:
+            self.default_option_scope = default_option_scope
+
+    def set_option(
+        self,
+        option: str,
+        value: int | str,
+        _format: bool | None = None,
+        prevent_overwrite: bool | None = None,
+        ignore_errors: bool | None = None,
+        append: bool | None = None,
+        g: bool | None = None,
+        global_: bool | None = None,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+    ) -> Self:
+        """Set option for tmux target.
+
+        Wraps ``$ tmux set-option <option> <value>``.
+
+        Parameters
+        ----------
+        option : str
+            option to set, e.g. 'aggressive-resize'
+        value : str
+            option value. True/False will turn in 'on' and 'off',
+            also accepts string of 'on' or 'off' directly.
+
+        .. deprecated:: 0.28
+
+           Deprecated by ``g`` for global, use `global_`` instead.
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+
+        Examples
+        --------
+        >>> import typing as t
+        >>> from libtmux.common import tmux_cmd
+        >>> from libtmux.constants import OptionScope
+        >>> from libtmux._internal.sparse_array import SparseArray
+
+        >>> class MyServer(OptionsMixin):
+        ...     socket_name = server.socket_name
+        ...     def cmd(self, cmd: str, *args: object):
+        ...         cmd_args: t.List[t.Union[str, int]] = [cmd]
+        ...         if self.socket_name:
+        ...             cmd_args.insert(0, f"-L{self.socket_name}")
+        ...         cmd_args.insert(0, "-f/dev/null")
+        ...         return tmux_cmd(*cmd_args, *args)
+        ...
+        ...     default_option_scope = OptionScope.Server
+
+        >>> MyServer()._show_option('escape-time')
+        500
+
+        >>> MyServer().set_option('escape-time', 1250)
+        <libtmux.options.MyServer object at ...>
+
+        >>> MyServer()._show_option('escape-time')
+        1250
+
+        >>> MyServer().set_option('escape-time', 495)
+        <libtmux.options.MyServer object at ...>
+
+        >>> MyServer()._show_option('escape-time')
+        495
+        """
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_option_scope
+
+        flags: list[str] = []
+        if isinstance(value, bool) and value:
+            value = "on"
+        elif isinstance(value, bool) and not value:
+            value = "off"
+
+        if _format is not None and _format:
+            assert isinstance(_format, bool)
+            flags.append("-F")
+
+        if prevent_overwrite is not None and prevent_overwrite:
+            assert isinstance(prevent_overwrite, bool)
+            flags.append("-o")
+
+        if ignore_errors is not None and ignore_errors:
+            assert isinstance(ignore_errors, bool)
+            flags.append("-q")
+
+        if append is not None and append:
+            assert isinstance(append, bool)
+            flags.append("-a")
+
+        if g is not None:
+            warnings.warn("g argument is deprecated in favor of global_", stacklevel=2)
+            global_ = g
+
+        if global_ is not None and global_:
+            assert isinstance(global_, bool)
+            flags.append("-g")
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in OPTION_SCOPE_FLAG_MAP
+            flags.append(
+                OPTION_SCOPE_FLAG_MAP[scope],
+            )
+
+        cmd = self.cmd(
+            "set-option",
+            *flags,
+            option,
+            value,
+        )
+
+        if isinstance(cmd.stderr, list) and len(cmd.stderr):
+            handle_option_error(cmd.stderr[0])
+
+        return self
+
+    def unset_option(
+        self,
+        option: str,
+        unset_panes: bool | None = None,
+        global_: bool | None = None,
+        ignore_errors: bool | None = None,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+    ) -> Self:
+        """Unset option for tmux target.
+
+        Wraps ``$ tmux set-option -u <option>`` / ``$ tmux set-option -U <option>``
+
+        Parameters
+        ----------
+        option : str
+            option to unset, e.g. 'aggressive-resize'
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+
+        Examples
+        --------
+        >>> import typing as t
+        >>> from libtmux.common import tmux_cmd
+        >>> from libtmux.constants import OptionScope
+
+        >>> class MyServer(OptionsMixin):
+        ...     socket_name = server.socket_name
+        ...     def cmd(self, cmd: str, *args: object):
+        ...         cmd_args: t.List[t.Union[str, int]] = [cmd]
+        ...         if self.socket_name:
+        ...             cmd_args.insert(0, f"-L{self.socket_name}")
+        ...         cmd_args.insert(0, "-f/dev/null")
+        ...         return tmux_cmd(*cmd_args, *args)
+        ...
+        ...     default_option_scope = OptionScope.Server
+
+        >>> MyServer().set_option('escape-time', 1250)
+        <libtmux.options.MyServer object at ...>
+
+        >>> MyServer()._show_option('escape-time')
+        1250
+
+        >>> MyServer().unset_option('escape-time')
+        <libtmux.options.MyServer object at ...>
+
+        >>> MyServer()._show_option('escape-time')
+        500
+        """
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_option_scope
+
+        flags: list[str] = []
+
+        if unset_panes is not None and unset_panes:
+            assert isinstance(unset_panes, bool)
+            flags.append("-U")
+        else:
+            flags.append("-u")
+
+        if ignore_errors is not None and ignore_errors:
+            assert isinstance(ignore_errors, bool)
+            flags.append("-q")
+
+        if global_ is not None and global_:
+            assert isinstance(global_, bool)
+            flags.append("-g")
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in OPTION_SCOPE_FLAG_MAP
+            flags.append(
+                OPTION_SCOPE_FLAG_MAP[scope],
+            )
+
+        cmd = self.cmd(
+            "set-option",
+            *flags,
+            option,
+        )
+
+        if isinstance(cmd.stderr, list) and len(cmd.stderr):
+            handle_option_error(cmd.stderr[0])
+
+        return self
+
+    def _show_options_raw(
+        self,
+        g: bool | None = False,
+        global_: bool | None = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        include_hooks: bool | None = None,
+        include_inherited: bool | None = None,
+    ) -> tmux_cmd:
+        """Return a dict of options for the target.
+
+        Parameters
+        ----------
+        g : str, optional
+            Pass ``-g`` flag for global variable, default False.
+
+        Examples
+        --------
+        >>> import typing as t
+        >>> from libtmux.common import tmux_cmd
+        >>> from libtmux.constants import OptionScope
+
+        >>> class MyServer(OptionsMixin):
+        ...     socket_name = server.socket_name
+        ...     def cmd(self, cmd: str, *args: object):
+        ...         cmd_args: t.List[t.Union[str, int]] = [cmd]
+        ...         if self.socket_name:
+        ...             cmd_args.insert(0, f"-L{self.socket_name}")
+        ...         cmd_args.insert(0, "-f/dev/null")
+        ...         return tmux_cmd(*cmd_args, *args)
+        ...
+        ...     default_option_scope = OptionScope.Server
+
+        >>> MyServer()._show_options_raw()
+        <libtmux.common.tmux_cmd object at ...>
+
+        >>> MyServer()._show_options_raw().stdout
+        [...]
+        """
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_option_scope
+
+        flags: tuple[str, ...] = ()
+
+        if g:
+            warnings.warn("g argument is deprecated in favor of global_", stacklevel=2)
+            flags += ("-g",)
+        elif global_:
+            flags += ("-g",)
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in OPTION_SCOPE_FLAG_MAP
+            flags += (OPTION_SCOPE_FLAG_MAP[scope],)
+
+        if include_inherited is not None and include_inherited:
+            flags += ("-A",)
+
+        if include_hooks is not None and include_hooks:
+            flags += ("-H",)
+
+        return self.cmd("show-options", *flags)
+
+    def _show_options_dict(
+        self,
+        g: bool | None = False,
+        global_: bool | None = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        include_hooks: bool | None = None,
+        include_inherited: bool | None = None,
+    ) -> UntypedOptionsDict:
+        """Return dict of options for the target.
+
+        Parameters
+        ----------
+        g : str, optional
+            Pass ``-g`` flag for global variable, default False.
+
+        Examples
+        --------
+        >>> import typing as t
+        >>> from libtmux.common import tmux_cmd
+        >>> from libtmux.constants import OptionScope
+
+        >>> class MyServer(OptionsMixin):
+        ...     socket_name = server.socket_name
+        ...     def cmd(self, cmd: str, *args: object):
+        ...         cmd_args: t.List[t.Union[str, int]] = [cmd]
+        ...         if self.socket_name:
+        ...             cmd_args.insert(0, f"-L{self.socket_name}")
+        ...         cmd_args.insert(0, "-f/dev/null")
+        ...         return tmux_cmd(*cmd_args, *args)
+        ...
+        ...     default_option_scope = OptionScope.Server
+
+        >>> MyServer()._show_options_dict()
+        {...}
+
+        >>> isinstance(MyServer()._show_options_dict(), dict)
+        True
+        """
+        cmd = self._show_options_raw(
+            global_=global_,
+            scope=scope,
+            include_hooks=include_hooks,
+            include_inherited=include_inherited,
+        )
+
+        return parse_options_to_dict(
+            io.StringIO("\n".join(cmd.stdout)),
+        )
+
+    def _show_options(
+        self,
+        g: bool | None = False,
+        global_: bool | None = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        include_hooks: bool | None = None,
+        include_inherited: bool | None = None,
+    ) -> ExplodedComplexUntypedOptionsDict:
+        """Return a dict of options for the target.
+
+        Parameters
+        ----------
+        g : str, optional
+            Pass ``-g`` flag for global variable, default False.
+
+        Examples
+        --------
+        >>> import typing as t
+        >>> from libtmux.common import tmux_cmd
+        >>> from libtmux.constants import OptionScope
+
+        >>> class MyServer(OptionsMixin):
+        ...     socket_name = server.socket_name
+        ...     def cmd(self, cmd: str, *args: object):
+        ...         cmd_args: t.List[t.Union[str, int]] = [cmd]
+        ...         if self.socket_name:
+        ...             cmd_args.insert(0, f"-L{self.socket_name}")
+        ...         cmd_args.insert(0, "-f/dev/null")
+        ...         return tmux_cmd(*cmd_args, *args)
+        ...
+        ...     default_option_scope = OptionScope.Server
+
+        >>> MyServer()._show_options()
+        {...}
+        """
+        dict_output = self._show_options_dict(
+            global_=global_,
+            scope=scope,
+            include_hooks=include_hooks,
+            include_inherited=include_inherited,
+        )
+
+        output_exploded = convert_values(
+            explode_complex(
+                explode_arrays(dict_output),
+            ),
+        )
+
+        return t.cast("ExplodedComplexUntypedOptionsDict", output_exploded)
+
+    def _show_option_raw(
+        self,
+        option: str,
+        global_: bool = False,
+        g: bool = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+        include_hooks: bool | None = None,
+        include_inherited: bool | None = None,
+    ) -> tmux_cmd:
+        """Return raw option output for target.
+
+        Parameters
+        ----------
+        option : str
+        g : bool, optional
+            Pass ``-g`` flag, global. Default False.
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+
+        Examples
+        --------
+        >>> import typing as t
+        >>> from libtmux.common import tmux_cmd
+        >>> from libtmux.constants import OptionScope
+
+        >>> class MyServer(OptionsMixin):
+        ...     socket_name = server.socket_name
+        ...     def cmd(self, cmd: str, *args: object):
+        ...         cmd_args: t.List[t.Union[str, int]] = [cmd]
+        ...         if self.socket_name:
+        ...             cmd_args.insert(0, f"-L{self.socket_name}")
+        ...         cmd_args.insert(0, "-f/dev/null")
+        ...         return tmux_cmd(*cmd_args, *args)
+        ...
+        ...     default_option_scope = OptionScope.Server
+
+        >>> MyServer().cmd('new-session', '-d')
+        <libtmux.common.tmux_cmd object at ...>
+
+        >>> MyServer()._show_option_raw('exit-unattached', global_=True)
+        <libtmux.common.tmux_cmd object at ...>
+
+        >>> MyServer()._show_option_raw('exit-unattached', global_=True).stdout
+        ['exit-unattached off']
+
+        >>> isinstance(MyServer()._show_option_raw('exit-unattached', global_=True).stdout, list)
+        True
+
+        >>> isinstance(MyServer()._show_option_raw('exit-unattached', global_=True).stdout[0], str)
+        True
+        """
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_option_scope
+
+        flags: tuple[str | int, ...] = ()
+
+        if g:
+            warnings.warn("g argument is deprecated in favor of global_", stacklevel=2)
+            flags += ("-g",)
+        elif global_:
+            flags += ("-g",)
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in OPTION_SCOPE_FLAG_MAP
+            flags += (OPTION_SCOPE_FLAG_MAP[scope],)
+
+        if ignore_errors is not None and ignore_errors:
+            flags += ("-q",)
+
+        if include_inherited is not None and include_inherited:
+            flags += ("-A",)
+
+        if include_hooks is not None and include_hooks:
+            flags += ("-H",)
+
+        flags += (option,)
+
+        return self.cmd("show-options", *flags)
+
+    def _show_option(
+        self,
+        option: str,
+        global_: bool = False,
+        g: bool = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+        include_hooks: bool | None = None,
+        include_inherited: bool | None = None,
+    ) -> ConvertedValue | None:
+        """Return option value for the target.
+
+        todo: test and return True/False for on/off string
+
+        Parameters
+        ----------
+        option : str
+        g : bool, optional
+            Pass ``-g`` flag, global. Default False.
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+
+        Examples
+        --------
+        >>> import typing as t
+        >>> from libtmux.common import tmux_cmd
+        >>> from libtmux.constants import OptionScope
+
+        >>> class MyServer(OptionsMixin):
+        ...     socket_name = server.socket_name
+        ...     def cmd(self, cmd: str, *args: object):
+        ...         cmd_args: t.List[t.Union[str, int]] = [cmd]
+        ...         if self.socket_name:
+        ...             cmd_args.insert(0, f"-L{self.socket_name}")
+        ...         cmd_args.insert(0, "-f/dev/null")
+        ...         return tmux_cmd(*cmd_args, *args)
+        ...
+        ...     default_option_scope = OptionScope.Server
+
+        >>> MyServer().cmd('new-session', '-d')
+        <libtmux.common.tmux_cmd object at ...>
+
+        >>> MyServer()._show_option('exit-unattached', global_=True)
+        False
+        """
+        cmd = self._show_option_raw(
+            option=option,
+            global_=global_,
+            scope=scope,
+            ignore_errors=ignore_errors,
+            include_hooks=include_hooks,
+            include_inherited=include_inherited,
+        )
+
+        if cmd.stderr is not None and len(cmd.stderr):
+            handle_option_error(cmd.stderr[0])
+
+        options_output = cmd.stdout
+
+        if not len(options_output):
+            return None
+
+        output_exploded = convert_values(
+            explode_complex(
+                explode_arrays(
+                    parse_options_to_dict(
+                        io.StringIO("\n".join(cmd.stdout)),
+                    ),
+                ),
+            ),
+        )
+
+        if not isinstance(output_exploded, dict):
+            return output_exploded
+
+        if option not in output_exploded:
+            return None
+
+        return t.cast("ConvertedValue | None", output_exploded[option])
+
+    def show_option(
+        self,
+        option: str,
+        global_: bool = False,
+        g: bool = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+        include_hooks: bool | None = None,
+        include_inherited: bool | None = None,
+    ) -> t.Any | None:
+        """Return option value for the target.
+
+        Parameters
+        ----------
+        option : str
+        g : bool, optional
+            Pass ``-g`` flag, global. Default False.
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+
+        Examples
+        --------
+        >>> import typing as t
+        >>> from libtmux.common import tmux_cmd
+        >>> from libtmux.constants import OptionScope
+
+        >>> class MyServer(OptionsMixin):
+        ...     socket_name = server.socket_name
+        ...     def cmd(self, cmd: str, *args: object):
+        ...         cmd_args: t.List[t.Union[str, int]] = [cmd]
+        ...         if self.socket_name:
+        ...             cmd_args.insert(0, f"-L{self.socket_name}")
+        ...         cmd_args.insert(0, "-f/dev/null")
+        ...         return tmux_cmd(*cmd_args, *args)
+        ...
+        ...     default_option_scope = OptionScope.Server
+
+        >>> MyServer().cmd('new-session', '-d')
+        <libtmux.common.tmux_cmd object at ...>
+
+        >>> MyServer().show_option('exit-unattached', global_=True)
+        False
+        """
+        return self._show_option(
+            option=option,
+            global_=global_,
+            scope=scope,
+            ignore_errors=ignore_errors,
+            include_hooks=include_hooks,
+            include_inherited=include_inherited,
+        )
diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index b2f767b60..04db5daee 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -1094,11 +1094,11 @@ def set_window_option(
         return self.set_option(option=option, value=value)
 
     def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
-        """Show options for tmux window. Deprecated by :meth:`Window.show_options()`.
+        """Show options for tmux window. Deprecated by :meth:`Window._show_options()`.
 
         .. deprecated:: 0.26
 
-           Deprecated by :meth:`Window.show_options()`.
+           Deprecated by :meth:`Window._show_options()`.
 
         """
         warnings.warn(
@@ -1106,7 +1106,7 @@ def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
             category=DeprecationWarning,
             stacklevel=2,
         )
-        return self.show_options(
+        return self._show_options(
             g=g,
             scope=OptionScope.Window,
         )
@@ -1116,11 +1116,11 @@ def show_window_option(
         option: str,
         g: bool = False,
     ) -> str | int | None:
-        """Return option for target window. Deprecated by :meth:`Window.show_option()`.
+        """Return option for target window. Deprecated by :meth:`Window._show_option()`.
 
         .. deprecated:: 0.26
 
-           Deprecated by :meth:`Window.show_option()`.
+           Deprecated by :meth:`Window._show_option()`.
 
         """
         warnings.warn(
@@ -1128,7 +1128,7 @@ def show_window_option(
             category=DeprecationWarning,
             stacklevel=2,
         )
-        return self.show_option(
+        return self._show_option(
             option=option,
             g=g,
             scope=OptionScope.Window,
diff --git a/tests/legacy_api/test_session.py b/tests/legacy_api/test_session.py
index e565983e6..a9560824e 100644
--- a/tests/legacy_api/test_session.py
+++ b/tests/legacy_api/test_session.py
@@ -114,35 +114,35 @@ def test_new_session(server: Server) -> None:
 
 
 def test_show_options(session: Session) -> None:
-    """Session.show_options() returns dict."""
-    options = session.show_options()
+    """Session._show_options() returns dict."""
+    options = session._show_options()
     assert isinstance(options, dict)
 
 
 def test_set_show_options_single(session: Session) -> None:
-    """Set option then Session.show_options(key)."""
+    """Set option then Session._show_options(key)."""
     session.set_option("history-limit", 20)
-    assert session.show_option("history-limit") == 20
+    assert session._show_option("history-limit") == 20
 
     session.set_option("history-limit", 40)
-    assert session.show_option("history-limit") == 40
+    assert session._show_option("history-limit") == 40
 
-    assert session.show_options()["history-limit"] == 40
+    assert session._show_options()["history-limit"] == 40
 
 
 def test_set_show_option(session: Session) -> None:
-    """Set option then Session.show_option(key)."""
+    """Set option then Session._show_option(key)."""
     session.set_option("history-limit", 20)
-    assert session.show_option("history-limit") == 20
+    assert session._show_option("history-limit") == 20
 
     session.set_option("history-limit", 40)
 
-    assert session.show_option("history-limit") == 40
+    assert session._show_option("history-limit") == 40
 
 
 def test_empty_session_option_returns_None(session: Session) -> None:
-    """Verify Session.show_option returns None for unset option."""
-    assert session.show_option("default-shell") is None
+    """Verify Session._show_option returns None for unset option."""
+    assert session._show_option("default-shell") is None
 
 
 def test_show_option_unknown(session: Session) -> None:
@@ -152,9 +152,9 @@ def test_show_option_unknown(session: Session) -> None:
 
 
 def test_show_option_ambiguous(session: Session) -> None:
-    """Session.show_option raises AmbiguousOption for ambiguous option."""
+    """Session._show_option raises AmbiguousOption for ambiguous option."""
     with pytest.raises(exc.AmbiguousOption):
-        session.show_option("default-")
+        session._show_option("default-")
 
 
 def test_set_option_ambiguous(session: Session) -> None:
diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index c7ceb86dd..0c16e182c 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -52,7 +52,7 @@ def test_fresh_window_data(session: Session) -> None:
     """Verify window data is fresh."""
     attached_window = session.attached_window
     assert attached_window is not None
-    pane_base_idx = attached_window.show_option("pane-base-index", global_=True)
+    pane_base_idx = attached_window._show_option("pane-base-index", global_=True)
     assert pane_base_idx is not None
     pane_base_index = int(pane_base_idx)
 
@@ -268,19 +268,19 @@ def test_set_window_and_show_window_options(session: Session) -> None:
 
 
 def test_set_and_show_options(session: Session) -> None:
-    """Window.set_option() then Window.show_options(key)."""
+    """Window.set_option() then Window._show_options(key)."""
     window = session.new_window(window_name="test_window")
 
     window.set_option("main-pane-height", 20)
-    assert window.show_option("main-pane-height") == 20
+    assert window._show_option("main-pane-height") == 20
 
     window.set_option("main-pane-height", 40)
-    assert window.show_option("main-pane-height") == 40
-    assert window.show_options()["main-pane-height"] == 40
+    assert window._show_option("main-pane-height") == 40
+    assert window._show_options()["main-pane-height"] == 40
 
     if has_gte_version("2.3"):
         window.set_option("pane-border-format", " #P ")
-        assert window.show_option("pane-border-format") == " #P "
+        assert window._show_option("pane-border-format") == " #P "
 
 
 def test_empty_window_option_returns_None(session: Session) -> None:
diff --git a/tests/test_session.py b/tests/test_session.py
index 67c85deb9..4ffba5a89 100644
--- a/tests/test_session.py
+++ b/tests/test_session.py
@@ -117,35 +117,35 @@ def test_new_session(server: Server) -> None:
 
 
 def test_show_options(session: Session) -> None:
-    """Session.show_options() returns dict."""
-    options = session.show_options()
+    """Session._show_options() returns dict."""
+    options = session._show_options()
     assert isinstance(options, dict)
 
 
 def test_set_show_options_single(session: Session) -> None:
-    """Set option then Session.show_options(key)."""
+    """Set option then Session._show_options(key)."""
     session.set_option("history-limit", 20)
-    assert session.show_option("history-limit") == 20
+    assert session._show_option("history-limit") == 20
 
     session.set_option("history-limit", 40)
-    assert session.show_option("history-limit") == 40
+    assert session._show_option("history-limit") == 40
 
-    assert session.show_options()["history-limit"] == 40
+    assert session._show_options()["history-limit"] == 40
 
 
 def test_set_show_option(session: Session) -> None:
-    """Set option then Session.show_option(key)."""
+    """Set option then Session._show_option(key)."""
     session.set_option("history-limit", 20)
-    assert session.show_option("history-limit") == 20
+    assert session._show_option("history-limit") == 20
 
     session.set_option("history-limit", 40)
 
-    assert session.show_option("history-limit") == 40
+    assert session._show_option("history-limit") == 40
 
 
 def test_empty_session_option_returns_None(session: Session) -> None:
-    """Verify Session.show_option returns None for unset option."""
-    assert session.show_option("default-shell") is None
+    """Verify Session._show_option returns None for unset option."""
+    assert session._show_option("default-shell") is None
 
 
 def test_show_option_unknown(session: Session) -> None:
@@ -155,9 +155,9 @@ def test_show_option_unknown(session: Session) -> None:
 
 
 def test_show_option_ambiguous(session: Session) -> None:
-    """Session.show_option raises AmbiguousOption for ambiguous option."""
+    """Session._show_option raises AmbiguousOption for ambiguous option."""
     with pytest.raises(exc.AmbiguousOption):
-        session.show_option("default-")
+        session._show_option("default-")
 
 
 def test_set_option_ambiguous(session: Session) -> None:
diff --git a/tests/test_window.py b/tests/test_window.py
index 7bce74636..176909197 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -60,7 +60,7 @@ def test_fresh_window_data(session: Session) -> None:
     """Verify window data is fresh."""
     active_window = session.active_window
     assert active_window is not None
-    pane_base_idx = active_window.show_option("pane-base-index", global_=True)
+    pane_base_idx = active_window._show_option("pane-base-index", global_=True)
     assert pane_base_idx is not None
     pane_base_index = int(pane_base_idx)
 
@@ -268,25 +268,25 @@ def test_show_window_options(session: Session) -> None:
     options = window.show_window_options()
     assert isinstance(options, dict)
 
-    options_2 = window.show_options()
+    options_2 = window._show_options()
     assert isinstance(options_2, dict)
 
-    pane_options = window.show_options(scope=OptionScope.Pane)
+    pane_options = window._show_options(scope=OptionScope.Pane)
     assert isinstance(pane_options, dict)
 
-    pane_options_global = window.show_options(scope=OptionScope.Pane, global_=True)
+    pane_options_global = window._show_options(scope=OptionScope.Pane, global_=True)
     assert isinstance(pane_options_global, dict)
 
-    window_options = window.show_options(scope=OptionScope.Window)
+    window_options = window._show_options(scope=OptionScope.Window)
     assert isinstance(window_options, dict)
 
-    window_options_global = window.show_options(scope=OptionScope.Window, global_=True)
+    window_options_global = window._show_options(scope=OptionScope.Window, global_=True)
     assert isinstance(window_options_global, dict)
 
-    server_options = window.show_options(scope=OptionScope.Server)
+    server_options = window._show_options(scope=OptionScope.Server)
     assert isinstance(server_options, dict)
 
-    server_options_global = window.show_options(scope=OptionScope.Server, global_=True)
+    server_options_global = window._show_options(scope=OptionScope.Server, global_=True)
     assert isinstance(server_options_global, dict)
 
 
@@ -306,19 +306,19 @@ def test_set_window_and_show_window_options(session: Session) -> None:
 
 
 def test_set_and_show_window_options(session: Session) -> None:
-    """Window.set_option() then Window.show_options(key)."""
+    """Window.set_option() then Window._show_options(key)."""
     window = session.new_window(window_name="test_window")
 
     window.set_option("main-pane-height", 20)
-    assert window.show_option("main-pane-height") == 20
+    assert window._show_option("main-pane-height") == 20
 
     window.set_option("main-pane-height", 40)
-    assert window.show_option("main-pane-height") == 40
-    assert window.show_options()["main-pane-height"] == 40
+    assert window._show_option("main-pane-height") == 40
+    assert window._show_options()["main-pane-height"] == 40
 
     if has_gte_version("2.3"):
         window.set_option("pane-border-format", " #P ")
-        assert window.show_option("pane-border-format") == " #P "
+        assert window._show_option("pane-border-format") == " #P "
 
 
 def test_empty_window_option_returns_None(session: Session) -> None:

From bf19ca68327688d39941d3b35dc75eafeb34abce Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 7 Feb 2024 12:09:32 -0600
Subject: [PATCH 015/136] feat(Window): Use OptionsMixin for Window.set_option,
 Window.show_option(s)

---
 src/libtmux/options.py |   5 +
 src/libtmux/window.py  | 233 +----------------------------------------
 2 files changed, 9 insertions(+), 229 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index 89ced4f50..45a74a2ba 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -551,6 +551,7 @@ def set_option(
         _format: bool | None = None,
         prevent_overwrite: bool | None = None,
         ignore_errors: bool | None = None,
+        suppress_warnings: bool | None = None,
         append: bool | None = None,
         g: bool | None = None,
         global_: bool | None = None,
@@ -631,6 +632,10 @@ def set_option(
             assert isinstance(ignore_errors, bool)
             flags.append("-q")
 
+        if suppress_warnings is not None and suppress_warnings:
+            assert isinstance(suppress_warnings, bool)
+            flags.append("-q")
+
         if append is not None and append:
             assert isinstance(append, bool)
             flags.append("-a")
diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index 04db5daee..7f7382e3d 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -16,7 +16,6 @@
 from libtmux._internal.query_list import QueryList
 from libtmux.common import tmux_cmd
 from libtmux.constants import (
-    OPTION_SCOPE_FLAG_MAP,
     RESIZE_ADJUSTMENT_DIRECTION_FLAG_MAP,
     OptionScope,
     PaneDirection,
@@ -27,7 +26,8 @@
 from libtmux.pane import Pane
 
 from . import exc
-from .options import handle_option_error
+from .common import PaneDict, WindowOptionDict
+from .options import OptionsMixin
 
 if t.TYPE_CHECKING:
     import sys
@@ -49,7 +49,7 @@
 
 
 @dataclasses.dataclass()
-class Window(Obj):
+class Window(Obj, OptionsMixin):
     """:term:`tmux(1)` :term:`Window` [window_manual]_.
 
     Holds :class:`Pane` objects.
@@ -104,6 +104,7 @@ class Window(Obj):
        https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.
     """
 
+    default_option_scope: OptionScope | None = OptionScope.Window
     server: Server
 
     def __enter__(self) -> Self:
@@ -437,230 +438,6 @@ def select_layout(self, layout: str | None = None) -> Window:
 
         return self
 
-    def set_option(
-        self,
-        option: str,
-        value: int | str,
-        _format: bool | None = None,
-        unset: bool | None = None,
-        unset_panes: bool | None = None,
-        prevent_overwrite: bool | None = None,
-        suppress_warnings: bool | None = None,
-        append: bool | None = None,
-        g: bool | None = None,
-        scope: OptionScope | None = None,
-    ) -> Window:
-        """Set option for tmux window.
-
-        Wraps ``$ tmux set-option <option> <value>``.
-
-        Parameters
-        ----------
-        option : str
-            option to set, e.g. 'aggressive-resize'
-        value : str
-            window option value. True/False will turn in 'on' and 'off',
-            also accepts string of 'on' or 'off' directly.
-
-        Raises
-        ------
-        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
-        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
-        """
-        flags: list[str] = []
-        if isinstance(value, bool) and value:
-            value = "on"
-        elif isinstance(value, bool) and not value:
-            value = "off"
-
-        if unset is not None and unset:
-            assert isinstance(unset, bool)
-            flags.append("-u")
-
-        if unset_panes is not None and unset_panes:
-            assert isinstance(unset_panes, bool)
-            flags.append("-U")
-
-        if _format is not None and _format:
-            assert isinstance(_format, bool)
-            flags.append("-F")
-
-        if prevent_overwrite is not None and prevent_overwrite:
-            assert isinstance(prevent_overwrite, bool)
-            flags.append("-o")
-
-        if suppress_warnings is not None and suppress_warnings:
-            assert isinstance(suppress_warnings, bool)
-            flags.append("-q")
-
-        if append is not None and append:
-            assert isinstance(append, bool)
-            flags.append("-a")
-
-        if g is not None and g:
-            assert isinstance(g, bool)
-            flags.append("-g")
-
-        if scope is not None:
-            assert scope in OPTION_SCOPE_FLAG_MAP
-            flags.append(
-                OPTION_SCOPE_FLAG_MAP[scope],
-            )
-
-        cmd = self.cmd(
-            "set-option",
-            "-w",
-            *flags,
-            option,
-            value,
-        )
-
-        if isinstance(cmd.stderr, list) and len(cmd.stderr):
-            handle_option_error(cmd.stderr[0])
-
-        return self
-
-    @t.overload
-    def show_options(
-        self,
-        g: bool | None,
-        scope: OptionScope | None,
-        include_hooks: bool | None,
-        include_parents: bool | None,
-        values_only: t.Literal[True],
-    ) -> list[str]: ...
-
-    @t.overload
-    def show_options(
-        self,
-        g: bool | None,
-        scope: OptionScope | None,
-        include_hooks: bool | None,
-        include_parents: bool | None,
-        values_only: None = None,
-    ) -> WindowOptionDict: ...
-
-    @t.overload
-    def show_options(
-        self,
-        g: bool | None = None,
-        scope: OptionScope | None = None,
-        include_hooks: bool | None = None,
-        include_parents: bool | None = None,
-        values_only: t.Literal[False] = False,
-    ) -> WindowOptionDict: ...
-
-    def show_options(
-        self,
-        g: bool | None = False,
-        scope: OptionScope | None = OptionScope.Window,
-        include_hooks: bool | None = None,
-        include_parents: bool | None = None,
-        values_only: bool | None = False,
-    ) -> WindowOptionDict | list[str]:
-        """Return a dict of options for the window.
-
-        Parameters
-        ----------
-        g : str, optional
-            Pass ``-g`` flag for global variable, default False.
-        """
-        tmux_args: tuple[str, ...] = ()
-
-        if g:
-            tmux_args += ("-g",)
-
-        if scope is not None:
-            assert scope in OPTION_SCOPE_FLAG_MAP
-            tmux_args += (OPTION_SCOPE_FLAG_MAP[scope],)
-
-        if include_parents is not None and include_parents:
-            tmux_args += ("-A",)
-
-        if include_hooks is not None and include_hooks:
-            tmux_args += ("-H",)
-
-        if values_only is not None and values_only:
-            tmux_args += ("-v",)
-
-        cmd = self.cmd("show-options", *tmux_args)
-
-        output = cmd.stdout
-
-        # The shlex.split function splits the args at spaces, while also
-        # retaining quoted sub-strings.
-        #   shlex.split('this is "a test"') => ['this', 'is', 'a test']
-
-        window_options: WindowOptionDict = {}
-        for item in output:
-            try:
-                key, val = shlex.split(item)
-            except ValueError:
-                logger.exception("Error extracting option: %s", item)
-            assert isinstance(key, str)
-            assert isinstance(val, str)
-
-            if isinstance(val, str) and val.isdigit():
-                window_options[key] = int(val)
-
-        return window_options
-
-    def show_option(
-        self,
-        option: str,
-        g: bool = False,
-        scope: OptionScope | None = OptionScope.Window,
-        include_hooks: bool | None = None,
-        include_parents: bool | None = None,
-    ) -> str | int | None:
-        """Return option value for the target window.
-
-        todo: test and return True/False for on/off string
-
-        Parameters
-        ----------
-        option : str
-        g : bool, optional
-            Pass ``-g`` flag, global. Default False.
-
-        Raises
-        ------
-        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
-        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
-        """
-        tmux_args: tuple[str | int, ...] = ()
-
-        if g:
-            tmux_args += ("-g",)
-
-        if scope is not None:
-            assert scope in OPTION_SCOPE_FLAG_MAP
-            tmux_args += (OPTION_SCOPE_FLAG_MAP[scope],)
-
-        if include_parents is not None and include_parents:
-            tmux_args += ("-A",)
-
-        if include_hooks is not None and include_hooks:
-            tmux_args += ("-H",)
-
-        tmux_args += (option,)
-
-        cmd = self.cmd("show-options", *tmux_args)
-
-        if len(cmd.stderr):
-            handle_option_error(cmd.stderr[0])
-
-        window_options_output = cmd.stdout
-
-        if not len(window_options_output):
-            return None
-
-        value_raw = next(shlex.split(item) for item in window_options_output)
-
-        value: str | int = int(value_raw[1]) if value_raw[1].isdigit() else value_raw[1]
-
-        return value
-
     def rename_window(self, new_name: str) -> Window:
         """Rename window.
 
@@ -679,8 +456,6 @@ def rename_window(self, new_name: str) -> Window:
         >>> window.rename_window('New name')
         Window(@1 1:New name, Session($1 ...))
         """
-        import shlex
-
         lex = shlex.shlex(new_name)
         lex.escape = " "
         lex.whitespace_split = False

From 5b3a7456cef8917afd92130920cc7ab990f7d3e6 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Mon, 5 Feb 2024 16:30:13 -0600
Subject: [PATCH 016/136] feat(Pane): Use OptionsMixin for Pane.set_option,
 Pane.show_option(s)

---
 src/libtmux/pane.py | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/pane.py b/src/libtmux/pane.py
index 17752df37..054bd6e40 100644
--- a/src/libtmux/pane.py
+++ b/src/libtmux/pane.py
@@ -18,11 +18,13 @@
 from libtmux.constants import (
     PANE_DIRECTION_FLAG_MAP,
     RESIZE_ADJUSTMENT_DIRECTION_FLAG_MAP,
+    OptionScope,
     PaneDirection,
     ResizeAdjustmentDirection,
 )
 from libtmux.formats import FORMAT_SEPARATOR
 from libtmux.neo import Obj, fetch_obj
+from libtmux.options import OptionsMixin
 
 if t.TYPE_CHECKING:
     import sys
@@ -43,7 +45,7 @@
 
 
 @dataclasses.dataclass()
-class Pane(Obj):
+class Pane(Obj, OptionsMixin):
     """:term:`tmux(1)` :term:`Pane` [pane_manual]_.
 
     ``Pane`` instances can send commands directly to a pane, or traverse
@@ -90,6 +92,7 @@ class Pane(Obj):
        Accessed April 1st, 2018.
     """
 
+    default_option_scope: OptionScope | None = OptionScope.Pane
     server: Server
 
     def __enter__(self) -> Self:

From c44709f93532f8c22d906ed3b2e0384d61714cf4 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 7 Feb 2024 16:00:27 -0600
Subject: [PATCH 017/136] feat(Session): Use OptionsMixin for
 Session.set_option, Session.show_option(s)

---
 src/libtmux/session.py | 155 ++---------------------------------------
 1 file changed, 5 insertions(+), 150 deletions(-)

diff --git a/src/libtmux/session.py b/src/libtmux/session.py
index 60e4039da..c6396d27b 100644
--- a/src/libtmux/session.py
+++ b/src/libtmux/session.py
@@ -14,9 +14,11 @@
 import warnings
 
 from libtmux._internal.query_list import QueryList
-from libtmux.constants import WINDOW_DIRECTION_FLAG_MAP, WindowDirection
+from libtmux.common import tmux_cmd
+from libtmux.constants import WINDOW_DIRECTION_FLAG_MAP, OptionScope, WindowDirection
 from libtmux.formats import FORMAT_SEPARATOR
 from libtmux.neo import Obj, fetch_obj, fetch_objs
+from libtmux.options import OptionsMixin
 from libtmux.pane import Pane
 from libtmux.window import Window
 
@@ -26,7 +28,6 @@
     WindowDict,
     session_check_name,
 )
-from .options import handle_option_error
 
 if t.TYPE_CHECKING:
     import sys
@@ -47,7 +48,7 @@
 
 
 @dataclasses.dataclass()
-class Session(Obj, EnvironmentMixin):
+class Session(Obj, EnvironmentMixin, OptionsMixin):
     """:term:`tmux(1)` :term:`Session` [session_manual]_.
 
     Holds :class:`Window` objects.
@@ -90,6 +91,7 @@ class Session(Obj, EnvironmentMixin):
        https://man.openbsd.org/tmux.1#DESCRIPTION. Accessed April 1st, 2018.
     """
 
+    default_option_scope: OptionScope | None = None
     server: Server
 
     def __enter__(self) -> Self:
@@ -237,153 +239,6 @@ def cmd(
     Commands (tmux-like)
     """
 
-    def set_option(
-        self,
-        option: str,
-        value: str | int,
-        global_: bool = False,
-    ) -> Session:
-        """Set option ``$ tmux set-option <option> <value>``.
-
-        Parameters
-        ----------
-        option : str
-            the window option. such as 'default-shell'.
-        value : str, int, or bool
-            True/False will turn in 'on' and 'off'. You can also enter 'on' or
-            'off' directly.
-        _global : bool, optional
-            check for option globally across all servers (-g)
-
-        Raises
-        ------
-        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
-        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
-
-        Notes
-        -----
-        .. todo::
-
-            Needs tests
-        """
-        if isinstance(value, bool) and value:
-            value = "on"
-        elif isinstance(value, bool) and not value:
-            value = "off"
-
-        tmux_args: tuple[str | int, ...] = ()
-
-        if global_:
-            tmux_args += ("-g",)
-
-        assert isinstance(option, str)
-        assert isinstance(value, (str, int))
-
-        tmux_args += (
-            option,
-            value,
-        )
-
-        proc = self.cmd("set-option", *tmux_args)
-
-        if isinstance(proc.stderr, list) and len(proc.stderr):
-            handle_option_error(proc.stderr[0])
-
-        return self
-
-    def show_options(
-        self,
-        global_: bool | None = False,
-    ) -> dict[str, str | int]:
-        """Return dict of options for the session.
-
-        Parameters
-        ----------
-        _global : bool, optional
-            Pass ``-g`` flag for global variable (server-wide)
-
-        Returns
-        -------
-        :py:obj:`dict`
-
-        Notes
-        -----
-        Uses ``_global`` for keyword name instead of ``global`` to avoid
-        colliding with reserved keyword.
-        """
-        tmux_args: tuple[str, ...] = ()
-
-        if global_:
-            tmux_args += ("-g",)
-
-        tmux_args += ("show-options",)
-        session_output = self.cmd(*tmux_args).stdout
-
-        session_options: dict[str, str | int] = {}
-        for item in session_output:
-            key, val = item.split(" ", maxsplit=1)
-            assert isinstance(key, str)
-            assert isinstance(val, str)
-
-            if isinstance(val, str) and val.isdigit():
-                session_options[key] = int(val)
-
-        return session_options
-
-    def show_option(
-        self,
-        option: str,
-        global_: bool = False,
-    ) -> str | int | bool | None:
-        """Return option value for the target session.
-
-        Parameters
-        ----------
-        option : str
-            option name
-        _global : bool, optional
-            use global option scope, same as ``-g``
-
-        Returns
-        -------
-        str, int, or bool
-
-        Raises
-        ------
-        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
-        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
-
-        Notes
-        -----
-        Uses ``_global`` for keyword name instead of ``global`` to avoid
-        colliding with reserved keyword.
-
-        Test and return True/False for on/off string.
-        """
-        tmux_args: tuple[str, ...] = ()
-
-        if global_:
-            tmux_args += ("-g",)
-
-        tmux_args += (option,)
-
-        cmd = self.cmd("show-options", *tmux_args)
-
-        if isinstance(cmd.stderr, list) and len(cmd.stderr):
-            handle_option_error(cmd.stderr[0])
-
-        if not len(cmd.stdout):
-            return None
-
-        value_raw: list[str] = next(item.split(" ") for item in cmd.stdout)
-
-        assert isinstance(value_raw[0], str)
-        assert isinstance(value_raw[1], str)
-
-        value: str | int = int(value_raw[1]) if value_raw[1].isdigit() else value_raw[1]
-
-        return value
-
     def select_window(self, target_window: str | int) -> Window:
         """Select window and return the selected window.
 

From bbb5767bcc634c2e41172847ea98e264715a83fc Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 8 Feb 2024 08:15:13 -0600
Subject: [PATCH 018/136] feat(Server): Use OptionsMixin for Server.set_option,
 Server.show_option(s)

---
 src/libtmux/server.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/server.py b/src/libtmux/server.py
index 9041fe2cf..edc3e65a0 100644
--- a/src/libtmux/server.py
+++ b/src/libtmux/server.py
@@ -18,6 +18,7 @@
 from libtmux import exc, formats
 from libtmux._internal.query_list import QueryList
 from libtmux.common import tmux_cmd
+from libtmux.constants import OptionScope
 from libtmux.neo import fetch_objs
 from libtmux.pane import Pane
 from libtmux.session import Session
@@ -30,6 +31,7 @@
     WindowDict,
     session_check_name,
 )
+from .options import OptionsMixin
 
 if t.TYPE_CHECKING:
     import types
@@ -44,7 +46,7 @@
 logger = logging.getLogger(__name__)
 
 
-class Server(EnvironmentMixin):
+class Server(EnvironmentMixin, OptionsMixin):
     """:term:`tmux(1)` :term:`Server` [server_manual]_.
 
     - :attr:`Server.sessions` [:class:`Session`, ...]
@@ -117,6 +119,9 @@ class Server(EnvironmentMixin):
     formatter_prefix = "server_"
     """Namespace used for :class:`~libtmux.common.TmuxMappingObject`"""
 
+    default_option_scope: OptionScope | None = OptionScope.Server
+    """For option management."""
+
     def __init__(
         self,
         socket_name: str | None = None,

From 0f583b2f4472c3d07bd48996d251dbf63f9042fc Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 7 Feb 2024 16:00:34 -0600
Subject: [PATCH 019/136] tests: Handle Window.show_options scope mismatch

---
 tests/legacy_api/test_window.py | 5 ++++-
 tests/test_window.py            | 7 +++++--
 2 files changed, 9 insertions(+), 3 deletions(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index 0c16e182c..7ca880114 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -276,7 +276,10 @@ def test_set_and_show_options(session: Session) -> None:
 
     window.set_option("main-pane-height", 40)
     assert window._show_option("main-pane-height") == 40
-    assert window._show_options()["main-pane-height"] == 40
+
+    # By default, show-options will session scope, even if target is a window
+    with pytest.raises(KeyError):
+        assert window._show_options()["main-pane-height"] == 40
 
     if has_gte_version("2.3"):
         window.set_option("pane-border-format", " #P ")
diff --git a/tests/test_window.py b/tests/test_window.py
index 176909197..6c7fb4e0f 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -234,7 +234,7 @@ def test_window_rename(
     window_name_after: str,
 ) -> None:
     """Test Window.rename_window()."""
-    session.set_option("automatic-rename", "off")
+    session.set_option("automatic-rename", "off", scope=None)
     window = session.new_window(window_name=window_name_before, attach=True)
 
     assert window == session.active_window
@@ -314,7 +314,10 @@ def test_set_and_show_window_options(session: Session) -> None:
 
     window.set_option("main-pane-height", 40)
     assert window._show_option("main-pane-height") == 40
-    assert window._show_options()["main-pane-height"] == 40
+
+    # By default, show-options will session scope, even if target is a window
+    with pytest.raises(KeyError):
+        assert window._show_options()["main-pane-height"] == 40
 
     if has_gte_version("2.3"):
         window.set_option("pane-border-format", " #P ")

From d3c4d47138fe2ced201263754e35c86ae0b6f7da Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Tue, 6 Feb 2024 12:48:39 -0600
Subject: [PATCH 020/136] tests(window): Version guard to scope

---
 tests/legacy_api/test_window.py | 28 ++++++++++++++++++++++++----
 tests/test_window.py            | 25 ++++++++++++++++++++++---
 2 files changed, 46 insertions(+), 7 deletions(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index 7ca880114..261ba49ac 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -10,7 +10,8 @@
 import pytest
 
 from libtmux import exc
-from libtmux.common import has_version
+from libtmux.common import has_gte_version, has_lt_version, has_version
+from libtmux.constants import OptionScope
 from libtmux.pane import Pane
 from libtmux.server import Server
 from libtmux.window import Window
@@ -272,18 +273,37 @@ def test_set_and_show_options(session: Session) -> None:
     window = session.new_window(window_name="test_window")
 
     window.set_option("main-pane-height", 20)
-    assert window._show_option("main-pane-height") == 20
+    if has_gte_version("3.0"):
+        assert window._show_option("main-pane-height") == 20
+    else:
+        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 20
 
     window.set_option("main-pane-height", 40)
-    assert window._show_option("main-pane-height") == 40
+
+    if has_gte_version("3.0"):
+        assert window._show_option("main-pane-height") == 40
+    else:
+        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 40
 
     # By default, show-options will session scope, even if target is a window
     with pytest.raises(KeyError):
         assert window._show_options()["main-pane-height"] == 40
 
+    if has_gte_version("3.0"):
+        assert window._show_option("main-pane-height") == 40
+    else:
+        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 40
+
     if has_gte_version("2.3"):
         window.set_option("pane-border-format", " #P ")
-        assert window._show_option("pane-border-format") == " #P "
+
+        if has_gte_version("3.0"):
+            assert window._show_option("pane-border-format") == " #P "
+        else:
+            assert (
+                window._show_option("pane-border-format", scope=OptionScope.Window)
+                == " #P "
+            )
 
 
 def test_empty_window_option_returns_None(session: Session) -> None:
diff --git a/tests/test_window.py b/tests/test_window.py
index 6c7fb4e0f..b9c7c797b 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -310,18 +310,37 @@ def test_set_and_show_window_options(session: Session) -> None:
     window = session.new_window(window_name="test_window")
 
     window.set_option("main-pane-height", 20)
-    assert window._show_option("main-pane-height") == 20
+    if has_gte_version("3.0"):
+        assert window._show_option("main-pane-height") == 20
+    else:
+        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 20
 
     window.set_option("main-pane-height", 40)
-    assert window._show_option("main-pane-height") == 40
+
+    if has_gte_version("3.0"):
+        assert window._show_option("main-pane-height") == 40
+    else:
+        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 40
 
     # By default, show-options will session scope, even if target is a window
     with pytest.raises(KeyError):
         assert window._show_options()["main-pane-height"] == 40
 
+    if has_gte_version("3.0"):
+        assert window._show_option("main-pane-height") == 40
+    else:
+        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 40
+
     if has_gte_version("2.3"):
         window.set_option("pane-border-format", " #P ")
-        assert window._show_option("pane-border-format") == " #P "
+
+        if has_gte_version("3.0"):
+            assert window._show_option("pane-border-format") == " #P "
+        else:
+            assert (
+                window._show_option("pane-border-format", scope=OptionScope.Window)
+                == " #P "
+            )
 
 
 def test_empty_window_option_returns_None(session: Session) -> None:

From 55563e9176371e030968c19aef355ecf490fb51d Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 8 Feb 2024 11:32:29 -0600
Subject: [PATCH 021/136] tests(Window): For Window.default_option_scope

---
 tests/legacy_api/test_window.py | 2 +-
 tests/test_window.py            | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index 261ba49ac..7935c192c 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -287,7 +287,7 @@ def test_set_and_show_options(session: Session) -> None:
 
     # By default, show-options will session scope, even if target is a window
     with pytest.raises(KeyError):
-        assert window._show_options()["main-pane-height"] == 40
+        assert window._show_options(scope=OptionScope.Session)["main-pane-height"] == 40
 
     if has_gte_version("3.0"):
         assert window._show_option("main-pane-height") == 40
diff --git a/tests/test_window.py b/tests/test_window.py
index b9c7c797b..e4bd04c43 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -324,7 +324,7 @@ def test_set_and_show_window_options(session: Session) -> None:
 
     # By default, show-options will session scope, even if target is a window
     with pytest.raises(KeyError):
-        assert window._show_options()["main-pane-height"] == 40
+        assert window._show_options(scope=OptionScope.Session)["main-pane-height"] == 40
 
     if has_gte_version("3.0"):
         assert window._show_option("main-pane-height") == 40

From e5882ad480f3f234b4b953374b86cecc9b3c4bfb Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 8 Feb 2024 13:28:14 -0600
Subject: [PATCH 022/136] docs(options): Add page for option helpers

---
 docs/api/index.md   | 1 +
 docs/api/options.md | 6 ++++++
 2 files changed, 7 insertions(+)
 create mode 100644 docs/api/options.md

diff --git a/docs/api/index.md b/docs/api/index.md
index 99d614fee..91492db7f 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -11,6 +11,7 @@ servers
 sessions
 windows
 panes
+options
 constants
 common
 exceptions
diff --git a/docs/api/options.md b/docs/api/options.md
new file mode 100644
index 000000000..5a5b9af3d
--- /dev/null
+++ b/docs/api/options.md
@@ -0,0 +1,6 @@
+# Options
+
+```{eval-rst}
+.. automodule:: libtmux.options
+   :members:
+```

From 94b493140a617cfdc3aafa79459b95e101bf338a Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 8 Feb 2024 18:34:13 -0600
Subject: [PATCH 023/136] internal(constants[options]): GPT generated
 dataclasses

---
 src/libtmux/_internal/constants.py | 247 +++++++++++++++++++++++++++++
 1 file changed, 247 insertions(+)
 create mode 100644 src/libtmux/_internal/constants.py

diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py
new file mode 100644
index 000000000..3a7dd0da6
--- /dev/null
+++ b/src/libtmux/_internal/constants.py
@@ -0,0 +1,247 @@
+from __future__ import annotations
+
+import typing as t
+from dataclasses import dataclass, field
+
+from libtmux._internal.dataclasses import SkipDefaultFieldsReprMixin
+
+TerminalFeatures = dict[str, list[str]]
+
+
+T = t.TypeVar("T")
+
+
+class TmuxArray(dict[int, T], t.Generic[T]):
+    """Support non-sequential indexes without raising IndexError."""
+
+    def add(self, index: int, value: T) -> None:
+        self[index] = value
+
+    def append(self, value: T) -> None:
+        index = max(self.keys()) + 1
+        self[index] = value
+
+    def iter_values(self) -> t.Iterator[T]:
+        for index in sorted(self.keys()):
+            yield self[index]
+
+    def as_list(self) -> list[T]:
+        return [self[index] for index in sorted(self.keys())]
+
+
+@dataclass(repr=False)
+class ServerOptions(
+    SkipDefaultFieldsReprMixin,
+):
+    backspace: str | None = field(default=None)
+    buffer_limit: int | None = field(default=None)
+    command_alias: TmuxArray[str] = field(default_factory=TmuxArray)
+    default_terminal: str | None = field(default=None)
+    copy_command: str | None = field(default=None)
+    escape_time: int | None = field(default=None)
+    editor: str | None = field(default=None)
+    exit_empty: t.Literal["on", "off"] | None = field(default=None)
+    exit_unattached: t.Literal["on", "off"] | None = field(default=None)
+    extended_keys: t.Literal["on", "off", "always"] | None = field(default=None)
+    focus_events: t.Literal["on", "off"] | None = field(default=None)
+    history_file: str | None = field(default=None)
+    message_limit: int | None = field(default=None)
+    prompt_history_limit: int | None = field(default=None)
+    set_clipboard: t.Literal["on", "external", "off"] | None = field(default=None)
+    terminal_features: TerminalFeatures = field(default_factory=dict)
+    terminal_overrides: TmuxArray[str] = field(default_factory=TmuxArray)
+    user_keys: TmuxArray[str] = field(default_factory=TmuxArray)
+
+    def __init__(self, **kwargs: object) -> None:
+        # Convert hyphenated keys to underscored attribute names and assign values
+        for key, value in kwargs.items():
+            key_underscored = key.replace("-", "_")
+            setattr(self, key_underscored, value)
+
+
+@dataclass(repr=False)
+class SessionOptions(
+    SkipDefaultFieldsReprMixin,
+):
+    activity_action: t.Literal["any", "none", "current", "other"] | None = field(
+        default=None,
+    )
+    assume_paste_time: int | None = field(default=None)
+    base_index: int | None = field(default=None)
+    bell_action: t.Literal["any", "none", "current", "other"] | None = field(
+        default=None,
+    )
+    default_command: str | None = field(default=None)
+    default_shell: str | None = field(default=None)
+    default_size: str | None = field(default=None)  # Format "XxY"
+    destroy_unattached: t.Literal["on", "off"] | None = field(default=None)
+    detach_on_destroy: (
+        t.Literal["off", "on", "no-detached", "previous", "next"] | None
+    ) = field(default=None)
+    display_panes_active_colour: str | None = field(default=None)
+    display_panes_colour: str | None = field(default=None)
+    display_panes_time: int | None = field(default=None)
+    display_time: int | None = field(default=None)
+    history_limit: int | None = field(default=None)
+    key_table: str | None = field(default=None)
+    lock_after_time: int | None = field(default=None)
+    lock_command: str | None = field(default=None)
+    menu_style: str | None = field(default=None)
+    menu_selected_style: str | None = field(default=None)
+    menu_border_style: str | None = field(default=None)
+    menu_border_lines: (
+        t.Literal["single", "rounded", "double", "heavy", "simple", "padded", "none"]
+        | None
+    ) = field(default=None)
+    message_command_style: str | None = field(default=None)
+    message_line: int | None = field(default=None)
+    message_style: str | None = field(default=None)
+    mouse: t.Literal["on", "off"] | None = field(default=None)
+    prefix: str | None = field(default=None)
+    prefix2: str | None = field(default=None)
+    renumber_windows: t.Literal["on", "off"] | None = field(default=None)
+    repeat_time: int | None = field(default=None)
+    set_titles: t.Literal["on", "off"] | None = field(default=None)
+    set_titles_string: str | None = field(default=None)
+    silence_action: t.Literal["any", "none", "current", "other"] | None = field(
+        default=None,
+    )
+    status: t.Literal["off", "on"] | int | None = field(default=None)
+    status_format: list[str] | None = field(default=None)
+    status_interval: int | None = field(default=None)
+    status_justify: t.Literal["left", "centre", "right", "absolute-centre"] | None = (
+        field(default=None)
+    )
+    status_keys: t.Literal["vi", "emacs"] | None = field(default=None)
+    status_left: str | None = field(default=None)
+    status_left_length: int | None = field(default=None)
+    status_left_style: str | None = field(default=None)
+    status_position: t.Literal["top", "bottom"] | None = field(default=None)
+    status_right: str | None = field(default=None)
+    status_right_length: int | None = field(default=None)
+    status_right_style: str | None = field(default=None)
+    status_style: str | None = field(default=None)
+    update_environment: list[str] | None = field(default=None)
+    visual_activity: t.Literal["on", "off", "both"] | None = field(default=None)
+    visual_bell: t.Literal["on", "off", "both"] | None = field(default=None)
+    visual_silence: t.Literal["on", "off", "both"] | None = field(default=None)
+    word_separators: str | None = field(default=None)
+
+    def __init__(self, **kwargs: object) -> None:
+        # Convert hyphenated keys to underscored attribute names and assign values
+        for key, value in kwargs.items():
+            key_underscored = key.replace("-", "_")
+            setattr(self, key_underscored, value)
+
+
+@dataclass(repr=False)
+class WindowOptions(
+    SkipDefaultFieldsReprMixin,
+):
+    aggressive_resize: t.Literal["on", "off"] | None = field(default=None)
+    automatic_rename: t.Literal["on", "off"] | None = field(default=None)
+    automatic_rename_format: str | None = field(default=None)
+    clock_mode_colour: str | None = field(default=None)
+    clock_mode_style: t.Literal["12", "24"] | None = field(default=None)
+    fill_character: str | None = field(default=None)
+    main_pane_height: int | str | None = field(default=None)
+    main_pane_width: int | str | None = field(default=None)
+    copy_mode_match_style: str | None = field(default=None)
+    copy_mode_mark_style: str | None = field(default=None)
+    copy_mode_current_match_style: str | None = field(default=None)
+    mode_keys: t.Literal["vi", "emacs"] | None = field(default=None)
+    mode_style: str | None = field(default=None)
+    monitor_activity: t.Literal["on", "off"] | None = field(default=None)
+    monitor_bell: t.Literal["on", "off"] | None = field(default=None)
+    monitor_silence: int | None = field(default=None)  # Assuming seconds as int
+    other_pane_height: int | str | None = field(default=None)
+    other_pane_width: int | str | None = field(default=None)
+    pane_active_border_style: str | None = field(default=None)
+    pane_base_index: int | None = field(default=None)
+    pane_border_format: str | None = field(default=None)
+    pane_border_indicators: t.Literal["off", "colour", "arrows", "both"] | None = field(
+        default=None
+    )
+    pane_border_lines: (
+        t.Literal["single", "double", "heavy", "simple", "number"] | None
+    ) = field(default=None)
+    pane_border_status: t.Literal["off", "top", "bottom"] | None = field(
+        default=None,
+    )
+    pane_border_style: str | None = field(default=None)
+    popup_style: str | None = field(default=None)
+    popup_border_style: str | None = field(default=None)
+    popup_border_lines: (
+        t.Literal["single", "rounded", "double", "heavy", "simple", "padded", "none"]
+        | None
+    ) = field(default=None)
+    window_status_activity_style: str | None = field(default=None)
+    window_status_bell_style: str | None = field(default=None)
+    window_status_current_format: str | None = field(default=None)
+    window_status_current_style: str | None = field(default=None)
+    window_status_format: str | None = field(default=None)
+    window_status_last_style: str | None = field(default=None)
+    window_status_separator: str | None = field(default=None)
+    window_status_style: str | None = field(default=None)
+    window_size: t.Literal["largest", "smallest", "manual", "latest"] | None = field(
+        default=None
+    )
+    wrap_search: t.Literal["on", "off"] | None = field(default=None)
+
+    def __init__(self, **kwargs: object) -> None:
+        # Convert hyphenated keys to underscored attribute names and assign values
+        for key, value in kwargs.items():
+            key_underscored = key.replace("-", "_")
+            setattr(self, key_underscored, value)
+
+
+@dataclass(repr=False)
+class PaneOptions(
+    SkipDefaultFieldsReprMixin,
+):
+    allow_passthrough: t.Literal["on", "off", "all"] | None = field(default=None)
+    allow_rename: t.Literal["on", "off"] | None = field(default=None)
+    alternate_screen: t.Literal["on", "off"] | None = field(default=None)
+    cursor_colour: str | None = field(default=None)
+    pane_colours: list[str] | None = field(default=None)
+    cursor_style: (
+        t.Literal[
+            "default",
+            "blinking-block",
+            "block",
+            "blinking-underline",
+            "underline",
+            "blinking-bar",
+            "bar",
+        ]
+        | None
+    ) = field(default=None)
+    remain_on_exit: t.Literal["on", "off", "failed"] | None = field(default=None)
+    remain_on_exit_format: str | None = field(default=None)
+    scroll_on_clear: t.Literal["on", "off"] | None = field(default=None)
+    synchronize_panes: t.Literal["on", "off"] | None = field(default=None)
+    window_active_style: str | None = field(default=None)
+    window_style: str | None = field(default=None)
+
+    def __init__(self, **kwargs: object) -> None:
+        # Convert hyphenated keys to underscored attribute names and assign values
+        for key, value in kwargs.items():
+            key_underscored = key.replace("-", "_")
+            setattr(self, key_underscored, value)
+
+
+@dataclass(repr=False)
+class Options(
+    ServerOptions,
+    SessionOptions,
+    WindowOptions,
+    PaneOptions,
+    SkipDefaultFieldsReprMixin,
+):
+    def __init__(self, **kwargs: object) -> None:
+        # Convert hyphenated keys to underscored attribute names and assign values
+        # Remove asaterisk from inherited options
+        for key, value in kwargs.items():
+            key_underscored = key.replace("-", "_")
+            key_asterisk_removed = key_underscored.rstrip("*")
+            setattr(self, key_asterisk_removed, value)

From 8b8d16099d484fb155994a046b3aa3c6f80fd3c7 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 8 Feb 2024 08:28:59 -0600
Subject: [PATCH 024/136] tests(test_options): Test OptionsMixin

!squash tests(test_options): Tests for OptionsMixin

!squash test_options: renamings

!squash test_options: Stable baseline
---
 src/libtmux/_internal/constants.py |   4 +-
 tests/test_options.py              | 509 +++++++++++++++++++++++++++++
 2 files changed, 511 insertions(+), 2 deletions(-)
 create mode 100644 tests/test_options.py

diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py
index 3a7dd0da6..4e4a20253 100644
--- a/src/libtmux/_internal/constants.py
+++ b/src/libtmux/_internal/constants.py
@@ -160,7 +160,7 @@ class WindowOptions(
     pane_base_index: int | None = field(default=None)
     pane_border_format: str | None = field(default=None)
     pane_border_indicators: t.Literal["off", "colour", "arrows", "both"] | None = field(
-        default=None
+        default=None,
     )
     pane_border_lines: (
         t.Literal["single", "double", "heavy", "simple", "number"] | None
@@ -184,7 +184,7 @@ class WindowOptions(
     window_status_separator: str | None = field(default=None)
     window_status_style: str | None = field(default=None)
     window_size: t.Literal["largest", "smallest", "manual", "latest"] | None = field(
-        default=None
+        default=None,
     )
     wrap_search: t.Literal["on", "off"] | None = field(default=None)
 
diff --git a/tests/test_options.py b/tests/test_options.py
new file mode 100644
index 000000000..0d9aababe
--- /dev/null
+++ b/tests/test_options.py
@@ -0,0 +1,509 @@
+"""Test for libtmux options management."""
+
+from __future__ import annotations
+
+import dataclasses
+import textwrap
+import typing as t
+
+import pytest
+
+from libtmux._internal.constants import (
+    Options,
+    PaneOptions,
+    ServerOptions,
+    SessionOptions,
+    WindowOptions,
+)
+from libtmux._internal.sparse_array import SparseArray
+from libtmux.common import has_gte_version
+from libtmux.constants import OptionScope
+from libtmux.exc import OptionError
+from libtmux.pane import Pane
+
+if t.TYPE_CHECKING:
+    from typing_extensions import LiteralString
+
+    from libtmux.server import Server
+
+
+def test_options(server: Server) -> None:
+    """Test basic options."""
+    session = server.new_session(session_name="test")
+    window = session.new_window(window_name="test")
+    pane = window.split_window(attach=False)
+
+    for obj in [server, session, window, pane]:
+        obj._show_options()
+        obj._show_options(global_=True)
+        obj._show_options(include_inherited=True)
+        obj._show_options(include_hooks=True)
+        with pytest.raises(OptionError):
+            obj._show_option("test")
+        if has_gte_version("3.0"):
+            obj._show_option("test", ignore_errors=True)
+        with pytest.raises(OptionError):
+            obj.set_option("test", "invalid")
+        if isinstance(obj, Pane):
+            if has_gte_version("3.0"):
+                obj.set_option("test", "invalid", ignore_errors=True)
+            else:
+                with pytest.raises(OptionError):
+                    obj.set_option("test", "invalid", ignore_errors=True)
+        else:
+            obj.set_option("test", "invalid", ignore_errors=True)
+
+
+def test_options_server(server: Server) -> None:
+    """Test server options."""
+    session = server.new_session(session_name="test")
+    window = session.new_window(window_name="test")
+    pane = window.split_window(attach=False)
+
+    server.set_option("buffer-limit", 100)
+    assert server._show_option("buffer-limit") == 100
+    if has_gte_version("3.0"):
+        server.set_option("buffer-limit", 150, scope=OptionScope.Pane)
+
+    if has_gte_version("3.0"):
+        # set-option and show-options w/ Pane (-p) does not exist until 3.0+
+        server.set_option(
+            "buffer-limit",
+            150,
+            scope=OptionScope.Pane,
+            ignore_errors=True,
+        )
+    server.set_option("buffer-limit", 150, scope=OptionScope.Server)
+
+    if has_gte_version("3.0"):
+        assert session._show_option("buffer-limit") == 150
+
+    # Server option in deeper objects
+    if has_gte_version("3.0"):
+        pane.set_option("buffer-limit", 100)
+    else:
+        with pytest.raises(OptionError):
+            pane.set_option("buffer-limit", 100)
+
+    if has_gte_version("3.0"):
+        assert pane._show_option("buffer-limit") == 100
+        assert window._show_option("buffer-limit") == 100
+        assert server._show_option("buffer-limit") == 100
+
+    server_options = ServerOptions(**server._show_options(scope=OptionScope.Server))
+    if has_gte_version("3.0"):
+        assert server._show_option("buffer-limit") == 100
+
+        assert server_options.buffer_limit == 100
+
+        server.set_option("buffer-limit", 150, scope=OptionScope.Server)
+
+        assert server._show_option("buffer-limit") == 150
+
+        server.unset_option("buffer-limit")
+
+        assert server._show_option("buffer-limit") == 50
+
+
+def test_options_session(server: Server) -> None:
+    """Test session options."""
+    session = server.new_session(session_name="test")
+    session.new_window(window_name="test")
+
+    session_options_ = session._show_options(scope=OptionScope.Session)
+
+    session_options = SessionOptions(**session_options_)
+    assert session_options.default_size == session_options_.get("default-size")
+
+
+def test_options_window(server: Server) -> None:
+    """Test window options."""
+    session = server.new_session(session_name="test")
+    window = session.new_window(window_name="test")
+    window.split_window(attach=False)
+
+    window_options_ = window._show_options(scope=OptionScope.Window)
+
+    window_options = WindowOptions(**window_options_)
+    assert window_options.automatic_rename == window_options_.get("automatic-rename")
+
+
+def test_options_pane(server: Server) -> None:
+    """Test pane options."""
+    session = server.new_session(session_name="test")
+    window = session.new_window(window_name="test")
+    pane = window.split_window(attach=False)
+
+    pane_options_ = pane._show_options(scope=OptionScope.Pane)
+
+    pane_options = PaneOptions(**pane_options_)
+    assert pane_options.window_active_style == pane_options_.get("window-active-style")
+
+
+def test_options_grid(server: Server) -> None:
+    """Test options against grid."""
+    session = server.new_session(session_name="test")
+    window = session.new_window(window_name="test")
+    pane = window.split_window(attach=False)
+
+    for include_inherited in [True, False]:
+        for global_ in [True, False]:
+            for obj in [server, session, window, pane]:
+                for scope in [
+                    OptionScope.Server,
+                    OptionScope.Session,
+                    OptionScope.Window,
+                ]:
+                    objglobal__options_ = obj._show_options(
+                        scope=scope,
+                        include_inherited=include_inherited,
+                        global_=global_,
+                    )
+                    objglobal__options = Options(**objglobal__options_)
+                    for field in dataclasses.fields(objglobal__options):
+                        expected = objglobal__options_.get(field.name.replace("_", "-"))
+
+                        if include_inherited and expected is None:
+                            expected = objglobal__options_.get(
+                                f"{field.name.replace('_', '-')}*",
+                                None,
+                            )
+
+                        default_value = None
+                        if field.default_factory is not dataclasses.MISSING:
+                            default_value = field.default_factory()
+                            if expected is None:
+                                default_value = None
+                        assert (
+                            getattr(objglobal__options, field.name, default_value)
+                            == expected
+                        ), (
+                            f"Expect {field.name} to be {expected} when "
+                            + f"scope={scope}, global_={global_}"
+                        )
+                    if (
+                        has_gte_version("3.0")
+                        and scope == OptionScope.Window
+                        and global_
+                    ):
+                        assert objglobal__options.pane_base_index == 0
+
+
+def test_custom_options(
+    server: Server,
+) -> None:
+    """Test tmux's user (custom) options."""
+    session = server.new_session(session_name="test")
+    session.set_option("@custom-option", "test")
+    assert session._show_option("@custom-option") == "test"
+
+
+MOCKED_GLOBAL_OPTIONS: list[LiteralString] = """
+backspace C-?
+buffer-limit 50
+command-alias[0] split-pane=split-window
+command-alias[1] splitp=split-window
+command-alias[2] "server-info=show-messages -JT"
+command-alias[3] "info=show-messages -JT"
+command-alias[4] "choose-window=choose-tree -w"
+command-alias[5] "choose-session=choose-tree -s"
+copy-command ''
+default-terminal xterm-256color
+editor vim
+escape-time 50
+exit-empty on
+exit-unattached off
+extended-keys off
+focus-events off
+history-file ''
+message-limit 1000
+prompt-history-limit 100
+set-clipboard external
+terminal-overrides[0] xterm-256color:Tc
+terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
+terminal-features[1] screen*:title
+user-keys
+""".strip().split("\n")
+
+
+@dataclasses.dataclass
+class MockedCmdResponse:
+    """Mocked tmux_cmd response."""
+
+    stdout: list[LiteralString] | None
+    stderr: list[str] | None
+
+
+def cmd_mocked(*args: object) -> MockedCmdResponse:
+    """Mock command response for show-options -s (server)."""
+    return MockedCmdResponse(
+        stdout=MOCKED_GLOBAL_OPTIONS,
+        stderr=None,
+    )
+
+
+def fake_cmd(
+    stdout: list[str] | None,
+    stderr: list[str] | None = None,
+) -> t.Callable[
+    [tuple[object, ...]],
+    MockedCmdResponse,
+]:
+    """Mock command response for show-options -s (server)."""
+
+    def _cmd(*args: object) -> MockedCmdResponse:
+        return MockedCmdResponse(
+            stdout=stdout,
+            stderr=stderr,
+        )
+
+    return _cmd
+
+
+def test_terminal_features(
+    server: Server,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test tmux's terminal-feature option destructuring."""
+    monkeypatch.setattr(server, "cmd", fake_cmd(stdout=MOCKED_GLOBAL_OPTIONS))
+    options_ = server._show_options()
+    assert any("terminal-features" in k for k in options_)
+    options = Options(**options_)
+    assert options
+    assert options.terminal_features
+    assert options.terminal_features["screen*"] == ["title"]
+    assert options.terminal_features["xterm*"] == [
+        "clipboard",
+        "ccolour",
+        "cstyle",
+        "focus",
+    ]
+
+
+def test_terminal_overrides(
+    server: Server,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test tmux's terminal-overrides option destructuring."""
+    monkeypatch.setattr(server, "cmd", cmd_mocked)
+    options_ = server._show_options()
+    assert any("terminal-overrides" in k for k in options_)
+    options = Options(**options_)
+    assert options
+    assert options.terminal_overrides
+    assert options_["terminal-overrides"] is not None
+    assert isinstance(options_["terminal-overrides"], dict)
+    assert not isinstance(options_["terminal-overrides"], SparseArray)
+    assert "xterm-256color" in options_["terminal-overrides"]
+    assert isinstance(options_["terminal-overrides"]["xterm-256color"], dict)
+    assert options_["terminal-overrides"]["xterm-256color"] == {"Tc": None}
+
+
+def test_command_alias(
+    server: Server,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test tmux's command-alias option destructuring."""
+    monkeypatch.setattr(server, "cmd", cmd_mocked)
+    options_ = server._show_options()
+    assert any("command-alias" in k for k in options_)
+    options = Options(**options_)
+    assert options
+    assert options.command_alias
+    assert isinstance(options_["command-alias"], dict)
+    assert not isinstance(options_["command-alias"], SparseArray)
+    assert isinstance(options_["command-alias"]["split-pane"], str)
+    assert options_["command-alias"]["split-pane"] == "split-window"
+
+
+def test_user_keys(
+    server: Server,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test tmux's user-keys option destructuring."""
+    monkeypatch.setattr(server, "cmd", cmd_mocked)
+    options_ = server._show_options()
+    assert any("user-keys" in k for k in options_)
+    options = Options(**options_)
+    assert options
+    assert options.user_keys is None
+
+
+class OptionDataclassTestFixture(t.NamedTuple):
+    """Test fixture raw show_option(s) data into typed libtmux data."""
+
+    # pytest internal
+    test_id: str
+
+    # test data
+    mocked_cmd_stdout: list[str]  # option data (raw)
+    tmux_option: str  # e.g. terminal-features
+
+    # results
+    expected: t.Any  # e.g. 50, TerminalFeatures({}), etc.
+    dataclass_attribute: str  # e.g. terminal_features
+
+
+TEST_FIXTURES: list[OptionDataclassTestFixture] = [
+    OptionDataclassTestFixture(
+        test_id="terminal-features",
+        mocked_cmd_stdout=textwrap.dedent(
+            """
+            terminal-features[0] xterm*:clipboard:ccolour:cstyle:focus
+            terminal-features[1] screen*:title
+            """,
+        )
+        .strip()
+        .split("\n"),
+        dataclass_attribute="terminal_features",
+        tmux_option="terminal-features",
+        expected={
+            "screen*": ["title"],
+            "xterm*": ["clipboard", "ccolour", "cstyle", "focus"],
+        },
+    ),
+    OptionDataclassTestFixture(
+        test_id="command-alias",
+        mocked_cmd_stdout=textwrap.dedent(
+            """
+            command-alias[0] split-pane=split-window
+            command-alias[1] splitp=split-window
+            command-alias[2] "server-info=show-messages -JT"
+            command-alias[3] "info=show-messages -JT"
+            command-alias[4] "choose-window=choose-tree -w"
+            command-alias[5] "choose-session=choose-tree -s"
+            """,
+        )
+        .strip()
+        .split("\n"),
+        dataclass_attribute="command_alias",
+        tmux_option="command-alias",
+        expected=TmuxArray(
+            {
+                "split-pane": "split-window",
+                "splitp": "split-window",
+                "server-info": "show-messages -JT",
+                "info": "show-messages -JT",
+                "choose-window": "choose-tree -w",
+                "choose-session": "choose-tree -s",
+            },
+        ),
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    list(OptionDataclassTestFixture._fields),
+    TEST_FIXTURES,
+    ids=[test.test_id for test in TEST_FIXTURES],
+)
+def test_mocked_cmd_stdoutclass_fixture(
+    monkeypatch: pytest.MonkeyPatch,
+    test_id: str,
+    mocked_cmd_stdout: list[str],
+    tmux_option: str,
+    expected: t.Any,
+    dataclass_attribute: str,
+    server: Server,
+) -> None:
+    """Parametrized test grid for options."""
+    monkeypatch.setattr(server, "cmd", fake_cmd(stdout=mocked_cmd_stdout))
+
+    options_ = server._show_options()
+    assert any(tmux_option in k for k in options_)
+    options = Options(**options_)
+    assert options
+    assert hasattr(options, dataclass_attribute)
+    assert getattr(options, dataclass_attribute, None) == expected
+
+
+@pytest.mark.parametrize(
+    list(OptionDataclassTestFixture._fields),
+    TEST_FIXTURES,
+    ids=[test.test_id for test in TEST_FIXTURES],
+)
+def test_show_option_pane_fixture(
+    monkeypatch: pytest.MonkeyPatch,
+    test_id: str,
+    mocked_cmd_stdout: list[str],
+    tmux_option: str,
+    expected: t.Any,
+    dataclass_attribute: str,
+    server: Server,
+) -> None:
+    """Test Pane.show_option(s)?."""
+    session = server.new_session(session_name="test")
+    window = session.new_window(window_name="test")
+    pane = window.split_window(attach=False)
+
+    monkeypatch.setattr(pane, "cmd", fake_cmd(stdout=mocked_cmd_stdout))
+
+    result = pane.show_option(tmux_option)
+
+    assert result == expected
+
+    if expected is None:
+        assert result is not None, (
+            f"Expected {expected} to be {type(expected)}, got None"
+        )
+
+    if isinstance(expected, dict):
+        assert isinstance(result, dict), f'Expected dict, got "{type(result)}"'
+
+        for k, v in expected.items():
+            assert k in result
+
+            assert result[k] == v
+
+
+def test_stable_baseline_options_and_hooks(server: Server) -> None:
+    """Ensure stable baseline across tmux versions."""
+    session = server.new_session(session_name="test", detach=True)
+
+    # List variables
+    assert server.show_option("command-alias") == {
+        "choose-session": "choose-tree -s",
+        "choose-window": "choose-tree -w",
+        "info": "show-messages -JT",
+        "server-info": "show-messages -JT",
+        "split-pane": "split-window",
+        "splitp": "split-window",
+    }
+    if has_gte_version("3.2"):
+        assert server.show_option("terminal-features") == {
+            "screen*": [
+                "title",
+            ],
+            "xterm*": [
+                "clipboard",
+                "ccolour",
+                "cstyle",
+                "focus",
+                "title",
+            ],
+        }
+    assert server.show_option("terminal-overrides") is None
+    assert server.show_option("user-keys") is None
+    assert server.show_option("status-format") is None
+    assert server.show_option("update-environment") is None
+
+    # List variables: Pane
+    pane = session.active_pane
+    assert pane is not None
+    assert pane.show_option("pane-colours") is None
+
+
+def test_high_level_api_expectations(server: Server) -> None:
+    """Ensure options and hooks behave as expected."""
+
+    # Raw input and output
+    # Should be able to functionally parse raw CLI output, even outside of libtmux into
+    # options.
+
+    # Parsing steps
+    # 1. Basic KV split: Should split options into key,values.
+    # 2. Structure: Should decompose array-like options and dictionaries
+    #    In the case of sparse arrays, which don't exist in Python, a SparseArray is
+    #    used that behaves like a list but allows for sparse indexes so the indices
+    #    aren't lost but the shape is still respected.
+    # 3. Python Typings: Should cast the fully structured objects into types

From eb7251960209ed790b8bc6aa5364f89b09c83550 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 16 Feb 2024 04:57:00 -0600
Subject: [PATCH 025/136] constants: Add HOOK_SCOPE_FLAG_MAP

---
 src/libtmux/constants.py | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/src/libtmux/constants.py b/src/libtmux/constants.py
index 0e98203c3..3b23895b9 100644
--- a/src/libtmux/constants.py
+++ b/src/libtmux/constants.py
@@ -76,3 +76,10 @@ class OptionScope(enum.Enum):
     OptionScope.Window: "-w",
     OptionScope.Pane: "-p",
 }
+
+HOOK_SCOPE_FLAG_MAP: dict[OptionScope, str] = {
+    OptionScope.Server: "",
+    OptionScope.Session: "",
+    OptionScope.Window: "-w",
+    OptionScope.Pane: "-p",
+}

From bb5b39891c3bf25e98f90df0efb61c01dc43517a Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 15 Feb 2024 10:42:33 -0600
Subject: [PATCH 026/136] docs(API): Document internal constants

---
 docs/internals/constants.md | 15 +++++++++++++++
 docs/internals/index.md     |  1 +
 2 files changed, 16 insertions(+)
 create mode 100644 docs/internals/constants.md

diff --git a/docs/internals/constants.md b/docs/internals/constants.md
new file mode 100644
index 000000000..65059ce94
--- /dev/null
+++ b/docs/internals/constants.md
@@ -0,0 +1,15 @@
+# Internal Constants - `libtmux._internal.constants`
+
+:::{warning}
+Be careful with these! These constants are private, internal as they're **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need a data structure here made public or stabilized please [file an issue](https://github.com/tmux-python/libtmux/issues).
+:::
+
+```{eval-rst}
+.. automodule:: libtmux._internal.constants
+   :members:
+   :undoc-members:
+   :inherited-members:
+   :show-inheritance:
+```
diff --git a/docs/internals/index.md b/docs/internals/index.md
index 09d4a1d6f..c79aed0e2 100644
--- a/docs/internals/index.md
+++ b/docs/internals/index.md
@@ -11,6 +11,7 @@ If you need an internal API stabilized please [file an issue](https://github.com
 ```{toctree}
 dataclasses
 query_list
+constants
 ```
 
 ## Environmental variables

From 2245b54fd6adc9875671ad27a6b4eaa35264245c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 15 Feb 2024 10:46:58 -0600
Subject: [PATCH 027/136] feat(internal[constants]): Add Hooks data structure

---
 src/libtmux/_internal/constants.py | 256 ++++++++++++++++++++++++++---
 1 file changed, 235 insertions(+), 21 deletions(-)

diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py
index 4e4a20253..4de3df453 100644
--- a/src/libtmux/_internal/constants.py
+++ b/src/libtmux/_internal/constants.py
@@ -1,32 +1,25 @@
+"""Internal constants."""
+
 from __future__ import annotations
 
+import io
+import logging
 import typing as t
 from dataclasses import dataclass, field
 
 from libtmux._internal.dataclasses import SkipDefaultFieldsReprMixin
+from libtmux._internal.sparse_array import SparseArray, is_sparse_array_list
 
-TerminalFeatures = dict[str, list[str]]
+if t.TYPE_CHECKING:
+    from typing import TypeAlias
 
 
 T = t.TypeVar("T")
 
+TerminalFeatures = dict[str, list[str]]
+HookArray: TypeAlias = "dict[str, SparseArray[str]]"
 
-class TmuxArray(dict[int, T], t.Generic[T]):
-    """Support non-sequential indexes without raising IndexError."""
-
-    def add(self, index: int, value: T) -> None:
-        self[index] = value
-
-    def append(self, value: T) -> None:
-        index = max(self.keys()) + 1
-        self[index] = value
-
-    def iter_values(self) -> t.Iterator[T]:
-        for index in sorted(self.keys()):
-            yield self[index]
-
-    def as_list(self) -> list[T]:
-        return [self[index] for index in sorted(self.keys())]
+logger = logging.getLogger(__name__)
 
 
 @dataclass(repr=False)
@@ -35,7 +28,7 @@ class ServerOptions(
 ):
     backspace: str | None = field(default=None)
     buffer_limit: int | None = field(default=None)
-    command_alias: TmuxArray[str] = field(default_factory=TmuxArray)
+    command_alias: SparseArray[str] = field(default_factory=SparseArray)
     default_terminal: str | None = field(default=None)
     copy_command: str | None = field(default=None)
     escape_time: int | None = field(default=None)
@@ -49,8 +42,8 @@ class ServerOptions(
     prompt_history_limit: int | None = field(default=None)
     set_clipboard: t.Literal["on", "external", "off"] | None = field(default=None)
     terminal_features: TerminalFeatures = field(default_factory=dict)
-    terminal_overrides: TmuxArray[str] = field(default_factory=TmuxArray)
-    user_keys: TmuxArray[str] = field(default_factory=TmuxArray)
+    terminal_overrides: SparseArray[str] = field(default_factory=SparseArray)
+    user_keys: SparseArray[str] = field(default_factory=SparseArray)
 
     def __init__(self, **kwargs: object) -> None:
         # Convert hyphenated keys to underscored attribute names and assign values
@@ -121,7 +114,7 @@ class SessionOptions(
     status_right_length: int | None = field(default=None)
     status_right_style: str | None = field(default=None)
     status_style: str | None = field(default=None)
-    update_environment: list[str] | None = field(default=None)
+    update_environment: SparseArray[str] = field(default_factory=SparseArray)
     visual_activity: t.Literal["on", "off", "both"] | None = field(default=None)
     visual_bell: t.Literal["on", "off", "both"] | None = field(default=None)
     visual_silence: t.Literal["on", "off", "both"] | None = field(default=None)
@@ -245,3 +238,224 @@ def __init__(self, **kwargs: object) -> None:
             key_underscored = key.replace("-", "_")
             key_asterisk_removed = key_underscored.rstrip("*")
             setattr(self, key_asterisk_removed, value)
+
+
+@dataclass(repr=False)
+class Hooks(
+    SkipDefaultFieldsReprMixin,
+):
+    """tmux hooks data structure."""
+
+    # --- Tmux normal hooks ---
+    # Run when a window has activity. See monitor-activity.
+    alert_activity: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a window has received a bell. See monitor-bell.
+    alert_bell: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a window has been silent. See monitor-silence.
+    alert_silence: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a client becomes the latest active client of its session.
+    client_active: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a client is attached.
+    client_attached: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a client is detached.
+    client_detached: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when focus enters a client.
+    client_focus_in: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when focus exits a client.
+    client_focus_out: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a client is resized.
+    client_resized: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a client's attached session is changed.
+    client_session_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when the program running in a pane exits, but remain-on-exit is on so the pane
+    # has not closed.
+    pane_died: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when the program running in a pane exits.
+    pane_exited: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when the focus enters a pane, if the focus-events option is on.
+    pane_focus_in: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when the focus exits a pane, if the focus-events option is on.
+    pane_focus_out: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when the terminal clipboard is set using the xterm(1) escape sequence.
+    pane_set_clipboard: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a new session created.
+    session_created: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a session closed.
+    session_closed: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a session is renamed.
+    session_renamed: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a window is linked into a session.
+    window_linked: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a window is renamed.
+    window_renamed: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a window is resized. This may be after the client-resized hook is run.
+    window_resized: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a window is unlinked from a session.
+    window_unlinked: SparseArray[str] = field(default_factory=SparseArray)
+
+    # --- Tmux control mode hooks ---
+    # The client has detached.
+    client_detached_control: SparseArray[str] = field(default_factory=SparseArray)
+    # The client is now attached to the session with ID session-id, which is named name.
+    client_session_changed_control: SparseArray[str] = field(
+        default_factory=SparseArray,
+    )
+    # An error has happened in a configuration file.
+    config_error: SparseArray[str] = field(default_factory=SparseArray)
+    # The pane has been continued after being paused (if the pause-after flag is set,
+    # see refresh-client -A).
+    continue_control: SparseArray[str] = field(default_factory=SparseArray)
+    # The tmux client is exiting immediately, either because it is not attached to any
+    # session or an error occurred.
+    exit_control: SparseArray[str] = field(default_factory=SparseArray)
+    # New form of %output sent when the pause-after flag is set.
+    extended_output: SparseArray[str] = field(default_factory=SparseArray)
+    # The layout of a window with ID window-id changed.
+    layout_change: SparseArray[str] = field(default_factory=SparseArray)
+    # A message sent with the display-message command.
+    message_control: SparseArray[str] = field(default_factory=SparseArray)
+    # A window pane produced output.
+    output: SparseArray[str] = field(default_factory=SparseArray)
+    # The pane with ID pane-id has changed mode.
+    pane_mode_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # Paste buffer name has been changed.
+    paste_buffer_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # Paste buffer name has been deleted.
+    paste_buffer_deleted: SparseArray[str] = field(default_factory=SparseArray)
+    # The pane has been paused (if the pause-after flag is set).
+    pause_control: SparseArray[str] = field(default_factory=SparseArray)
+    # The client is now attached to the session with ID session-id, which is named name.
+    session_changed_control: SparseArray[str] = field(default_factory=SparseArray)
+    # The current session was renamed to name.
+    session_renamed_control: SparseArray[str] = field(default_factory=SparseArray)
+    # The session with ID session-id changed its active window to the window with ID
+    # window-id.
+    session_window_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # A session was created or destroyed.
+    sessions_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # The value of the format associated with subscription name has changed to value.
+    subscription_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # The window with ID window-id was created but is not linked to the current session.
+    unlinked_window_add: SparseArray[str] = field(default_factory=SparseArray)
+    # The window with ID window-id, which is not linked to the current session, was
+    # closed.
+    unlinked_window_close: SparseArray[str] = field(default_factory=SparseArray)
+    # The window with ID window-id, which is not linked to the current session, was
+    # renamed.
+    unlinked_window_renamed: SparseArray[str] = field(default_factory=SparseArray)
+    # The window with ID window-id was linked to the current session.
+    window_add: SparseArray[str] = field(default_factory=SparseArray)
+    # The window with ID window-id closed.
+    window_close: SparseArray[str] = field(default_factory=SparseArray)
+    # The layout of a window with ID window-id changed. The new layout is window-layout.
+    # The window's visible layout is window-visible-layout and the window flags are
+    # window-flags.
+    window_layout_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # The active pane in the window with ID window-id changed to the pane with ID
+    # pane-id.
+    window_pane_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # The window with ID window-id was renamed to name.
+    window_renamed_control: SparseArray[str] = field(default_factory=SparseArray)
+
+    # --- After hooks - Run after specific tmux commands complete ---
+    # Runs after 'bind-key' completes
+    after_bind_key: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'capture-pane' completes
+    after_capture_pane: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'copy-mode' completes
+    after_copy_mode: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'display-message' completes
+    after_display_message: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'display-panes' completes
+    after_display_panes: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'kill-pane' completes
+    after_kill_pane: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'list-buffers' completes
+    after_list_buffers: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'list-clients' completes
+    after_list_clients: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'list-keys' completes
+    after_list_keys: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'list-panes' completes
+    after_list_panes: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'list-sessions' completes
+    after_list_sessions: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'list-windows' completes
+    after_list_windows: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'load-buffer' completes
+    after_load_buffer: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'lock-server' completes
+    after_lock_server: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'new-session' completes
+    after_new_session: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'new-window' completes
+    after_new_window: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'paste-buffer' completes
+    after_paste_buffer: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'pipe-pane' completes
+    after_pipe_pane: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'queue' command is processed
+    after_queue: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'refresh-client' completes
+    after_refresh_client: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'rename-session' completes
+    after_rename_session: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'rename-window' completes
+    after_rename_window: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'resize-pane' completes
+    after_resize_pane: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'resize-window' completes
+    after_resize_window: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'save-buffer' completes
+    after_save_buffer: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'select-layout' completes
+    after_select_layout: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'select-pane' completes
+    after_select_pane: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'select-window' completes
+    after_select_window: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'send-keys' completes
+    after_send_keys: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'set-buffer' completes
+    after_set_buffer: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'set-environment' completes
+    after_set_environment: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'set-hook' completes
+    after_set_hook: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'set-option' completes
+    after_set_option: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'show-environment' completes
+    after_show_environment: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'show-messages' completes
+    after_show_messages: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'show-options' completes
+    after_show_options: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'split-window' completes
+    after_split_window: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs after 'unbind-key' completes
+    after_unbind_key: SparseArray[str] = field(default_factory=SparseArray)
+
+    @classmethod
+    def from_stdout(cls, value: list[str]) -> Hooks:
+        from libtmux.options import (
+            explode_arrays,
+            explode_complex,
+            parse_options_to_dict,
+        )
+
+        output_exploded = explode_complex(
+            explode_arrays(
+                parse_options_to_dict(
+                    io.StringIO("\n".join(value)),
+                ),
+                force_array=True,
+            ),
+        )
+
+        assert is_sparse_array_list(output_exploded)
+
+        output_renamed: HookArray = {
+            k.lstrip("%").replace("-", "_"): v for k, v in output_exploded.items()
+        }
+
+        return cls(**output_renamed)

From b2fb5a70106f801658a75314fb629a52a4e18118 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 15 Feb 2024 11:24:27 -0600
Subject: [PATCH 028/136] feat!(hooks): HooksMixin

---
 src/libtmux/hooks.py | 346 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 346 insertions(+)
 create mode 100644 src/libtmux/hooks.py

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
new file mode 100644
index 000000000..3d8e1a7db
--- /dev/null
+++ b/src/libtmux/hooks.py
@@ -0,0 +1,346 @@
+"""Helpers for tmux hooks."""
+
+from __future__ import annotations
+
+import logging
+import shlex
+import typing as t
+import warnings
+
+from libtmux._internal.constants import (
+    Hooks,
+)
+from libtmux.common import CmdMixin, has_lt_version
+from libtmux.constants import (
+    DEFAULT_OPTION_SCOPE,
+    HOOK_SCOPE_FLAG_MAP,
+    OptionScope,
+    _DefaultOptionScope,
+)
+from libtmux.options import handle_option_error
+
+if t.TYPE_CHECKING:
+    from typing_extensions import Self
+
+HookDict = dict[str, t.Any]
+
+logger = logging.getLogger(__name__)
+
+
+class HooksMixin(CmdMixin):
+    """Mixin for manager scoped hooks in tmux.
+
+    Requires tmux 3.1+. For older versions, use raw commands.
+    """
+
+    default_hook_scope: OptionScope | None
+    hooks: Hooks
+
+    def __init__(self, default_hook_scope: OptionScope | None) -> None:
+        """When not a user (custom) hook, scope can be implied."""
+        self.default_hook_scope = default_hook_scope
+        self.hooks = Hooks()
+
+    def run_hook(
+        self,
+        hook: str,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+    ) -> Self:
+        """Run a hook immediately. Useful for testing."""
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_hook_scope
+
+        flags: list[str] = ["-R"]
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in HOOK_SCOPE_FLAG_MAP
+
+            flag = HOOK_SCOPE_FLAG_MAP[scope]
+            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+                warnings.warn(
+                    "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
+                    stacklevel=2,
+                )
+            else:
+                flags += (flag,)
+
+        cmd = self.cmd(
+            "set-hook",
+            *flags,
+            hook,
+        )
+
+        if isinstance(cmd.stderr, list) and len(cmd.stderr):
+            handle_option_error(cmd.stderr[0])
+
+        return self
+
+    def set_hook(
+        self,
+        hook: str,
+        value: int | str,
+        _format: bool | None = None,
+        unset: bool | None = None,
+        run: bool | None = None,
+        prevent_overwrite: bool | None = None,
+        ignore_errors: bool | None = None,
+        append: bool | None = None,
+        g: bool | None = None,
+        global_: bool | None = None,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+    ) -> Self:
+        """Set hook for tmux target.
+
+        Wraps ``$ tmux set-hook <hook> <value>``.
+
+        Parameters
+        ----------
+        hook : str
+            hook to set, e.g. 'aggressive-resize'
+        value : str
+            hook command.
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+        """
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_hook_scope
+
+        flags: list[str] = []
+
+        if unset is not None and unset:
+            assert isinstance(unset, bool)
+            flags.append("-u")
+
+        if run is not None and run:
+            assert isinstance(run, bool)
+            flags.append("-R")
+
+        if _format is not None and _format:
+            assert isinstance(_format, bool)
+            flags.append("-F")
+
+        if prevent_overwrite is not None and prevent_overwrite:
+            assert isinstance(prevent_overwrite, bool)
+            flags.append("-o")
+
+        if ignore_errors is not None and ignore_errors:
+            assert isinstance(ignore_errors, bool)
+            flags.append("-q")
+
+        if append is not None and append:
+            assert isinstance(append, bool)
+            flags.append("-a")
+
+        if global_ is not None and global_:
+            assert isinstance(global_, bool)
+            flags.append("-g")
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in HOOK_SCOPE_FLAG_MAP
+
+            flag = HOOK_SCOPE_FLAG_MAP[scope]
+            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+                warnings.warn(
+                    "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
+                    stacklevel=2,
+                )
+            else:
+                flags += (flag,)
+
+        cmd = self.cmd(
+            "set-hook",
+            *flags,
+            hook,
+            value,
+        )
+
+        if isinstance(cmd.stderr, list) and len(cmd.stderr):
+            handle_option_error(cmd.stderr[0])
+
+        return self
+
+    def unset_hook(
+        self,
+        hook: str,
+        global_: bool | None = None,
+        ignore_errors: bool | None = None,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+    ) -> Self:
+        """Unset hook for tmux target.
+
+        Wraps ``$ tmux set-hook -u <hook>`` / ``$ tmux set-hook -U <hook>``
+
+        Parameters
+        ----------
+        hook : str
+            hook to unset, e.g. 'after-show-environment'
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+        """
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_hook_scope
+
+        flags: list[str] = ["-u"]
+
+        if ignore_errors is not None and ignore_errors:
+            assert isinstance(ignore_errors, bool)
+            flags.append("-q")
+
+        if global_ is not None and global_:
+            assert isinstance(global_, bool)
+            flags.append("-g")
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in HOOK_SCOPE_FLAG_MAP
+
+            flag = HOOK_SCOPE_FLAG_MAP[scope]
+            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+                warnings.warn(
+                    "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
+                    stacklevel=2,
+                )
+            else:
+                flags += (flag,)
+
+        cmd = self.cmd(
+            "set-hook",
+            *flags,
+            hook,
+        )
+
+        if isinstance(cmd.stderr, list) and len(cmd.stderr):
+            handle_option_error(cmd.stderr[0])
+
+        return self
+
+    def show_hooks(
+        self,
+        global_: bool | None = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+    ) -> HookDict:
+        """Return a dict of hooks for the target."""
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_hook_scope
+
+        flags: tuple[str, ...] = ()
+
+        if global_:
+            flags += ("-g",)
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in HOOK_SCOPE_FLAG_MAP
+
+            flag = HOOK_SCOPE_FLAG_MAP[scope]
+            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+                warnings.warn(
+                    "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
+                    stacklevel=2,
+                )
+            else:
+                flags += (flag,)
+
+        if ignore_errors is not None and ignore_errors:
+            assert isinstance(ignore_errors, bool)
+            flags += ("-q",)
+
+        cmd = self.cmd("show-hooks", *flags)
+        output = cmd.stdout
+        hooks: HookDict = {}
+        for item in output:
+            try:
+                key, val = shlex.split(item)
+            except ValueError:
+                logger.warning(f"Error extracting hook: {item}")
+                key, val = item, None
+            assert isinstance(key, str)
+            assert isinstance(val, str) or val is None
+
+            if isinstance(val, str) and val.isdigit():
+                hooks[key] = int(val)
+
+        return hooks
+
+    def _show_hook(
+        self,
+        hook: str,
+        global_: bool = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+    ) -> list[str] | None:
+        """Return value for the hook.
+
+        Parameters
+        ----------
+        hook : str
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+        """
+        if scope is DEFAULT_OPTION_SCOPE:
+            scope = self.default_hook_scope
+
+        flags: tuple[str | int, ...] = ()
+
+        if global_:
+            flags += ("-g",)
+
+        if scope is not None and not isinstance(scope, _DefaultOptionScope):
+            assert scope in HOOK_SCOPE_FLAG_MAP
+
+            flag = HOOK_SCOPE_FLAG_MAP[scope]
+            if flag in {"-p", "-w"} and has_lt_version("3.2"):
+                warnings.warn(
+                    "Scope flag '-w' and '-p' requires tmux 3.2+. Ignoring.",
+                    stacklevel=2,
+                )
+            else:
+                flags += (flag,)
+
+        if ignore_errors is not None and ignore_errors:
+            flags += ("-q",)
+
+        flags += (hook,)
+
+        cmd = self.cmd("show-hooks", *flags)
+
+        if len(cmd.stderr):
+            handle_option_error(cmd.stderr[0])
+
+        return cmd.stdout
+
+    def show_hook(
+        self,
+        hook: str,
+        global_: bool = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+    ) -> str | int | None:
+        """Return value for the hook.
+
+        Parameters
+        ----------
+        hook : str
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+        """
+        hooks_output = self._show_hook(
+            hook=hook,
+            scope=scope,
+            ignore_errors=ignore_errors,
+        )
+        if hooks_output is None:
+            return None
+        hooks = Hooks.from_stdout(hooks_output)
+        return getattr(hooks, hook.replace("-", "_"), None)

From e6d742c785b42c31ec7154bb0152b6f80c873f88 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 15 Feb 2024 17:30:39 -0600
Subject: [PATCH 029/136] feat(Pane): Add HooksMixin

---
 src/libtmux/pane.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/pane.py b/src/libtmux/pane.py
index 054bd6e40..690e5b6f4 100644
--- a/src/libtmux/pane.py
+++ b/src/libtmux/pane.py
@@ -23,6 +23,7 @@
     ResizeAdjustmentDirection,
 )
 from libtmux.formats import FORMAT_SEPARATOR
+from libtmux.hooks import HooksMixin
 from libtmux.neo import Obj, fetch_obj
 from libtmux.options import OptionsMixin
 
@@ -45,7 +46,11 @@
 
 
 @dataclasses.dataclass()
-class Pane(Obj, OptionsMixin):
+class Pane(
+    Obj,
+    OptionsMixin,
+    HooksMixin,
+):
     """:term:`tmux(1)` :term:`Pane` [pane_manual]_.
 
     ``Pane`` instances can send commands directly to a pane, or traverse
@@ -93,6 +98,7 @@ class Pane(Obj, OptionsMixin):
     """
 
     default_option_scope: OptionScope | None = OptionScope.Pane
+    default_hook_scope: OptionScope | None = OptionScope.Pane
     server: Server
 
     def __enter__(self) -> Self:

From 4d0a3e018f16435910f0aea271fc67981c7f9119 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 15 Feb 2024 17:33:29 -0600
Subject: [PATCH 030/136] feat(Window): Add HooksMixin

---
 src/libtmux/window.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index 7f7382e3d..b36d1d40c 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -22,6 +22,7 @@
     ResizeAdjustmentDirection,
     WindowDirection,
 )
+from libtmux.hooks import HooksMixin
 from libtmux.neo import Obj, fetch_obj, fetch_objs
 from libtmux.pane import Pane
 
@@ -49,7 +50,11 @@
 
 
 @dataclasses.dataclass()
-class Window(Obj, OptionsMixin):
+class Window(
+    Obj,
+    OptionsMixin,
+    HooksMixin,
+):
     """:term:`tmux(1)` :term:`Window` [window_manual]_.
 
     Holds :class:`Pane` objects.
@@ -105,6 +110,7 @@ class Window(Obj, OptionsMixin):
     """
 
     default_option_scope: OptionScope | None = OptionScope.Window
+    default_hook_scope: OptionScope | None = OptionScope.Window
     server: Server
 
     def __enter__(self) -> Self:

From ef35102813058209798b1360a45a68f641802e95 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 15 Feb 2024 17:33:51 -0600
Subject: [PATCH 031/136] feat(Session): Add HooksMixin

---
 src/libtmux/session.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/session.py b/src/libtmux/session.py
index c6396d27b..83c7ed6bf 100644
--- a/src/libtmux/session.py
+++ b/src/libtmux/session.py
@@ -17,6 +17,7 @@
 from libtmux.common import tmux_cmd
 from libtmux.constants import WINDOW_DIRECTION_FLAG_MAP, OptionScope, WindowDirection
 from libtmux.formats import FORMAT_SEPARATOR
+from libtmux.hooks import HooksMixin
 from libtmux.neo import Obj, fetch_obj, fetch_objs
 from libtmux.options import OptionsMixin
 from libtmux.pane import Pane
@@ -48,7 +49,12 @@
 
 
 @dataclasses.dataclass()
-class Session(Obj, EnvironmentMixin, OptionsMixin):
+class Session(
+    Obj,
+    EnvironmentMixin,
+    OptionsMixin,
+    HooksMixin,
+):
     """:term:`tmux(1)` :term:`Session` [session_manual]_.
 
     Holds :class:`Window` objects.
@@ -92,6 +98,7 @@ class Session(Obj, EnvironmentMixin, OptionsMixin):
     """
 
     default_option_scope: OptionScope | None = None
+    default_hook_scope: OptionScope | None = None
     server: Server
 
     def __enter__(self) -> Self:

From a6a57794af1ca4aaa0c75057d2ad7df72aad3c3f Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 15 Feb 2024 17:34:33 -0600
Subject: [PATCH 032/136] feat(Server): Add HooksMixin

---
 src/libtmux/server.py | 9 ++++++++-
 1 file changed, 8 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/server.py b/src/libtmux/server.py
index edc3e65a0..18b182c5e 100644
--- a/src/libtmux/server.py
+++ b/src/libtmux/server.py
@@ -19,6 +19,7 @@
 from libtmux._internal.query_list import QueryList
 from libtmux.common import tmux_cmd
 from libtmux.constants import OptionScope
+from libtmux.hooks import HooksMixin
 from libtmux.neo import fetch_objs
 from libtmux.pane import Pane
 from libtmux.session import Session
@@ -46,7 +47,11 @@
 logger = logging.getLogger(__name__)
 
 
-class Server(EnvironmentMixin, OptionsMixin):
+class Server(
+    EnvironmentMixin,
+    OptionsMixin,
+    HooksMixin,
+):
     """:term:`tmux(1)` :term:`Server` [server_manual]_.
 
     - :attr:`Server.sessions` [:class:`Session`, ...]
@@ -121,6 +126,8 @@ class Server(EnvironmentMixin, OptionsMixin):
 
     default_option_scope: OptionScope | None = OptionScope.Server
     """For option management."""
+    default_hook_scope: OptionScope | None = OptionScope.Server
+    """For hook management."""
 
     def __init__(
         self,

From e160705d245982bf917f8b090370eecdca25a750 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 16 Feb 2024 06:27:58 -0600
Subject: [PATCH 033/136] docs(API): Add Hooks

---
 docs/api/hooks.md | 6 ++++++
 docs/api/index.md | 1 +
 2 files changed, 7 insertions(+)
 create mode 100644 docs/api/hooks.md

diff --git a/docs/api/hooks.md b/docs/api/hooks.md
new file mode 100644
index 000000000..7c4d1cf8f
--- /dev/null
+++ b/docs/api/hooks.md
@@ -0,0 +1,6 @@
+# Hooks
+
+```{eval-rst}
+.. automodule:: libtmux.hooks
+   :members:
+```
diff --git a/docs/api/index.md b/docs/api/index.md
index 91492db7f..49c720a5c 100644
--- a/docs/api/index.md
+++ b/docs/api/index.md
@@ -12,6 +12,7 @@ sessions
 windows
 panes
 options
+hooks
 constants
 common
 exceptions

From 93d43309797eea3668b008bae2b8324f723aff56 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 15 Feb 2024 09:39:30 -0600
Subject: [PATCH 034/136] tests(test_hooks): Test HooksMixin

---
 tests/test_hooks.py | 309 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 309 insertions(+)
 create mode 100644 tests/test_hooks.py

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
new file mode 100644
index 000000000..3cc750afe
--- /dev/null
+++ b/tests/test_hooks.py
@@ -0,0 +1,309 @@
+"""Testsuite for libtmux hook management."""
+
+from __future__ import annotations
+
+import typing as t
+
+import pytest
+
+from libtmux._internal.constants import Hooks
+from libtmux._internal.sparse_array import SparseArray
+from libtmux.common import has_gte_version, has_lt_version
+
+if t.TYPE_CHECKING:
+    from libtmux.server import Server
+
+if has_lt_version("3.0"):
+    pytest.skip(
+        reason="only support hooks in tmux 3.0 and above",
+        allow_module_level=True,
+    )
+
+
+def test_hooks_raw_cmd(
+    server: Server,
+) -> None:
+    """Raw hook set, show, unset via cmd."""
+    session = server.new_session(session_name="test hooks")
+    window = session.attached_window
+    pane = window.attached_pane
+    assert pane is not None
+
+    #
+    # Global
+    #
+    set_hook_proc = server.cmd(
+        "set-hook",
+        "-g",
+        "session-renamed[0]",
+        "set -g status-left-style bg=red",
+    )
+
+    assert not set_hook_proc.stdout
+    assert not set_hook_proc.stderr
+    assert not server.cmd("show-hooks").stdout
+
+    show_hooks_proc = server.cmd("show-hooks", "-g", "session-renamed[0]")
+
+    assert "set-option -g status-left-style bg=red" in show_hooks_proc.stdout[0]
+
+    # Server: Unset
+
+    # Server: Unset: Index
+    set_hook_proc = server.cmd(
+        "set-hook",
+        "-g",
+        "-u",
+        "session-renamed[0]",
+    )
+    assert server.cmd("show-hooks", "-g", "session-renamed[0]").stdout == [
+        "session-renamed[0] ",
+    ]
+
+    # Server: Unset variable
+    set_hook_proc = server.cmd(
+        "set-hook",
+        "-g",
+        "-u",
+        "session-renamed",
+    )
+    assert server.cmd("show-hooks", "-g", "session-renamed[0]").stdout == [
+        "session-renamed[0] ",
+    ]
+
+    #
+    # Session
+    #
+    set_hook_proc = session.cmd(
+        "set-hook",
+        "session-renamed[0]",
+        "set -g status-left-style bg=red",
+    )
+
+    assert not set_hook_proc.stdout
+    assert not set_hook_proc.stderr
+
+    assert not session.cmd(
+        "show-hooks",
+        "-s",
+    ).stdout
+    show_hooks_proc = session.cmd(
+        "show-hooks",
+        "session-renamed[0]",
+    )
+
+    assert "set-option -g status-left-style bg=red" in show_hooks_proc.stdout[0]
+
+    # Session: Unset
+
+    # Session: Unset: Index
+    set_hook_proc = session.cmd(
+        "set-hook",
+        "-u",
+        "session-renamed[0]",
+    )
+    assert session.cmd("show-hooks", "-s", "session-renamed[0]").stdout == []
+
+    # Session: Unset variable
+    set_hook_proc = session.cmd(
+        "set-hook",
+        "-u",
+        "session-renamed",
+    )
+    assert session.cmd("show-hooks", "-s", "session-renamed[0]").stdout == []
+
+    if has_gte_version("3.2"):
+        #
+        # Window
+        #
+        set_hook_proc = window.cmd(
+            "set-hook",
+            "-w",
+            "session-renamed[0]",
+            "set -g status-left-style bg=red",
+        )
+
+        assert not set_hook_proc.stdout
+        assert not set_hook_proc.stderr
+
+        show_hooks_proc = server.cmd(
+            "show-hooks",
+            "session-renamed[0]",
+        )
+
+        assert "set-option -g status-left-style bg=red" in show_hooks_proc.stdout[0]
+
+        # Window: Unset
+
+        # Window: Unset: Index
+        set_hook_proc = window.cmd(
+            "set-hook",
+            "-w",
+            "-u",
+            "session-renamed[0]",
+        )
+        assert window.cmd("show-hooks", "-w", "session-renamed[0]").stdout == [
+            "session-renamed[0] ",
+        ]
+
+        # Window: Unset variable
+        set_hook_proc = window.cmd(
+            "set-hook",
+            "-w",
+            "-u",
+            "session-renamed",
+        )
+        assert window.cmd("show-hooks", "-w", "session-renamed[0]").stdout == []
+
+        #
+        # Pane
+        #
+        set_hook_proc = pane.cmd(
+            "set-hook",
+            "-p",
+            "session-renamed[0]",
+            "set -g status-left-style bg=red",
+        )
+
+        assert not set_hook_proc.stdout
+        assert not set_hook_proc.stderr
+
+        show_hooks_proc = server.cmd(
+            "show-hooks",
+            "-p",
+            "session-renamed[0]",
+        )
+
+        assert "set-option -g status-left-style bg=red" in show_hooks_proc.stdout[0]
+
+        # Pane: Unset
+
+        # Pane: Unset: Index
+        set_hook_proc = pane.cmd(
+            "set-hook",
+            "-p",
+            "-u",
+            "session-renamed[0]",
+        )
+        assert pane.cmd("show-hooks", "-p", "session-renamed[0]").stdout == [
+            "session-renamed[0] ",
+        ]
+
+        # Pane: Unset variable
+        set_hook_proc = pane.cmd(
+            "set-hook",
+            "-p",
+            "-u",
+            "session-renamed",
+        )
+        assert pane.cmd("show-hooks", "-p", "session-renamed[0]").stdout == []
+
+
+def test_hooks_dataclass(
+    server: Server,
+) -> None:
+    """Tests for hooks dataclass."""
+    session = server.new_session(session_name="test hooks")
+    window = session.attached_window
+    pane = window.attached_pane
+    assert pane is not None
+
+    #
+    # Session
+    #
+    set_hook_proc = session.cmd(
+        "set-hook",
+        "session-renamed[0]",
+        "set -g status-left-style bg=red",
+    )
+
+    assert not set_hook_proc.stdout
+    assert not set_hook_proc.stderr
+
+    show_hooks_proc = server.cmd(
+        "show-hooks",
+        "session-renamed[0]",
+    )
+
+    hooks = Hooks.from_stdout(show_hooks_proc.stdout)
+    assert hooks.session_renamed.as_list() == [
+        "set-option -g status-left-style bg=red",
+    ]
+
+    set_hook_proc = session.cmd(
+        "set-hook",
+        "-p",
+        "session-renamed[0]",
+        "set -g status-left-style bg=red",
+    )
+    set_hook_proc = session.cmd(
+        "set-hook",
+        "session-renamed[1]",
+        "set -g status-left-style bg=white",
+    )
+    set_hook_proc = session.cmd(
+        "set-hook",
+        "session-renamed[2]",
+        "set -g status-left-style bg=blue",
+    )
+    set_hook_proc = session.cmd(
+        "set-hook",
+        "after-set-buffer[2]",
+        "set -g status-left-style bg=pink",
+    )
+
+    global_out = server.cmd("show-hooks", "-g").stdout
+    session_out = server.cmd("show-hooks").stdout
+
+    window_out = server.cmd("show-hooks", "-w").stdout
+    pane_out = server.cmd("show-hooks", "-p").stdout
+
+    session_out_processed = Hooks.from_stdout(session_out)
+    assert session_out_processed.session_renamed is not None
+
+    assert (
+        session_out_processed.session_renamed[2]
+        == "set-option -g status-left-style bg=blue"
+    )
+
+    hooks = Hooks.from_stdout(global_out + session_out + window_out + pane_out)
+
+    assert hooks.session_renamed.as_list() == [
+        "set-option -g status-left-style bg=red",
+        "set-option -g status-left-style bg=white",
+        "set-option -g status-left-style bg=blue",
+    ]
+    assert hooks.after_set_buffer.as_list() == [
+        "set-option -g status-left-style bg=pink",
+    ]
+
+
+def test_hooks_mixin(
+    server: Server,
+) -> None:
+    """Tests for hooks."""
+    session = server.new_session(session_name="test hooks")
+    window = session.attached_window
+    pane = window.attached_pane
+    assert pane is not None
+
+    pane.set_hook("session-renamed[0]", "set -g status-left-style bg=red")
+
+    #
+    # Pane
+    #
+    assert not pane.show_hooks()
+
+    show_hooks_raw = pane._show_hook(
+        "session-renamed[0]",
+    )
+
+    assert show_hooks_raw is not None
+
+    hooks = Hooks.from_stdout(show_hooks_raw)
+
+    assert hooks.session_renamed == SparseArray(
+        {
+            0: "set-option -g status-left-style bg=red",
+        },
+    )

From f61c9e30cfae687eea8e13daca440c3ebfdf5b24 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 23 Feb 2025 05:51:01 -0600
Subject: [PATCH 035/136] fix(options): improve type safety for SparseArray
 handling

- Update SparseArray type parameter to include all value types
- Add proper type checking for both dict and SparseArray cases
- Fix return type casting in _show_option method
- Resolve mypy errors related to string indexing of SparseArray
---
 src/libtmux/options.py | 21 ++++++++++++++++-----
 1 file changed, 16 insertions(+), 5 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index 45a74a2ba..d6bfa921e 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -108,7 +108,11 @@
 ]
 ExplodedComplexUntypedOptionsDict: TypeAlias = dict[
     str,
-    t.Union[str, int, list[str | int], dict[str, list[str | int]], "SparseArray[str]"]
+    str
+    | int
+    | list[str | int]
+    | dict[str, list[str | int]]
+    | SparseArray[str | int]
     | None,
 ]
 
@@ -368,7 +372,7 @@ def explode_arrays(
     """
     options: dict[str, t.Any] = {}
     for key, val in _dict.items():
-        Default: type[dict[t.Any, t.Any] | SparseArray[str]] = (
+        Default: type[dict[t.Any, t.Any] | SparseArray[str | int | bool | None]] = (
             dict if isinstance(key, str) and key == "terminal-features" else SparseArray
         )
         if "[" not in key:
@@ -1071,12 +1075,19 @@ def _show_option(
             ),
         )
 
-        if not isinstance(output_exploded, dict):
-            return output_exploded
+        if not isinstance(output_exploded, (dict, SparseArray)):
+            return t.cast("ConvertedValue", output_exploded)
 
-        if option not in output_exploded:
+        if isinstance(output_exploded, dict) and option not in output_exploded:
             return None
 
+        if isinstance(output_exploded, SparseArray):
+            try:
+                index = int(option)
+                return output_exploded[index]
+            except (ValueError, KeyError):
+                return None
+
         return t.cast("ConvertedValue | None", output_exploded[option])
 
     def show_option(

From 4db46729a1e2be65b02382e111c883b7a1490ff0 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 23 Feb 2025 05:53:54 -0600
Subject: [PATCH 036/136] test(options): update terminal-features test for tmux
 3.4

- Add version-specific assertions for terminal features
- Handle rxvt* features in tmux 3.4+
- Make test more robust by checking individual features
---
 tests/test_options.py | 28 ++++++++++++++++------------
 1 file changed, 16 insertions(+), 12 deletions(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index 0d9aababe..272af6ab0 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -470,18 +470,22 @@ def test_stable_baseline_options_and_hooks(server: Server) -> None:
         "splitp": "split-window",
     }
     if has_gte_version("3.2"):
-        assert server.show_option("terminal-features") == {
-            "screen*": [
-                "title",
-            ],
-            "xterm*": [
-                "clipboard",
-                "ccolour",
-                "cstyle",
-                "focus",
-                "title",
-            ],
-        }
+        terminal_features = server.show_option("terminal-features")
+        assert isinstance(terminal_features, dict)
+        assert "screen*" in terminal_features
+        assert terminal_features["screen*"] == ["title"]
+        assert "xterm*" in terminal_features
+        assert terminal_features["xterm*"] == [
+            "clipboard",
+            "ccolour",
+            "cstyle",
+            "focus",
+            "title",
+        ]
+        # Additional features in tmux 3.4+
+        if has_gte_version("3.4"):
+            assert "rxvt*" in terminal_features
+            assert terminal_features["rxvt*"] == ["ignorefkeys"]
     assert server.show_option("terminal-overrides") is None
     assert server.show_option("user-keys") is None
     assert server.show_option("status-format") is None

From 7a31af623993019b01969953fe90546c8f708cfc Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 23 Feb 2025 06:02:13 -0600
Subject: [PATCH 037/136] test(options): improve test coverage and type safety

WHAT:
- Add comprehensive test coverage for complex option values and edge cases
- Add tests for terminal features edge cases including empty/malformed features
- Add tests for style validation and error handling
- Fix type safety issues in terminal features tests

WHY:
- Ensure proper handling of tmux's complex option types:
  * Empty feature lists (tmux returns [''] not [])
  * Malformed feature strings with colons
  * Features containing spaces and special chars
- Improve type safety by:
  * Adding proper type assertions for runtime checks
  * Using t.cast() to handle complex union types
  * Fixing string vs int indexing for SparseArray
- Make tests more maintainable by:
  * Breaking complex assertions into steps
  * Using descriptive variable names
  * Adding clear comments about tmux behavior
---
 tests/test_options.py | 126 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 126 insertions(+)

diff --git a/tests/test_options.py b/tests/test_options.py
index 272af6ab0..c4fd18771 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -511,3 +511,129 @@ def test_high_level_api_expectations(server: Server) -> None:
     #    used that behaves like a list but allows for sparse indexes so the indices
     #    aren't lost but the shape is still respected.
     # 3. Python Typings: Should cast the fully structured objects into types
+
+
+def test_complex_option_values(server: Server) -> None:
+    """Test complex option values and edge cases."""
+    session = server.new_session(session_name="test")
+
+    # Test quoted values with spaces
+    session.set_option("@complex-option", "value with spaces")
+    assert session.show_option("@complex-option") == "value with spaces"
+
+    # Test escaped characters
+    session.set_option("@escaped-option", "line1\\nline2")
+    assert session.show_option("@escaped-option") == "line1\\nline2"
+
+    # Test empty values
+    session.set_option("@empty-option", "")
+    assert session.show_option("@empty-option") == ""
+
+    # Test option inheritance
+    parent_val = session.show_option("status-style")
+    session.set_option("status-style", "fg=red")
+    assert session.show_option("status-style") == "fg=red"
+    assert session.show_option("status-style", include_inherited=True) == "fg=red"
+    session.unset_option("status-style")
+    assert session.show_option("status-style", include_inherited=True) == parent_val
+
+
+def test_terminal_features_edge_cases(
+    server: Server,
+    monkeypatch: pytest.MonkeyPatch,
+) -> None:
+    """Test edge cases for terminal-features option."""
+    # Test empty features
+    monkeypatch.setattr(
+        server,
+        "cmd",
+        fake_cmd(stdout=["terminal-features[0] xterm*:"]),
+    )
+    options = server._show_options()
+    terminal_features = t.cast(dict[str, list[str]], options["terminal-features"])
+    assert isinstance(terminal_features, dict)
+    xterm_features = terminal_features["xterm*"]
+    assert isinstance(xterm_features, list)
+    assert xterm_features == [""]  # tmux returns [''] for empty features
+
+    # Test malformed features
+    monkeypatch.setattr(
+        server,
+        "cmd",
+        fake_cmd(stdout=["terminal-features[0] xterm*:invalid:feature:with:colons"]),
+    )
+    options = server._show_options()
+    terminal_features = t.cast(dict[str, list[str]], options["terminal-features"])
+    assert isinstance(terminal_features, dict)
+    xterm_features = terminal_features["xterm*"]
+    assert isinstance(xterm_features, list)
+    assert any(f == "invalid" for f in xterm_features)
+    assert any(f == "feature" for f in xterm_features)
+
+    # Test features with special characters
+    monkeypatch.setattr(
+        server,
+        "cmd",
+        fake_cmd(
+            stdout=[
+                'terminal-features[0] "xterm*:feature with space:special*char"',
+            ],
+        ),
+    )
+    options = server._show_options()
+    terminal_features = t.cast(dict[str, list[str]], options["terminal-features"])
+    assert isinstance(terminal_features, dict)
+    xterm_features = terminal_features["xterm*"]
+    assert isinstance(xterm_features, list)
+    assert any(f == "feature with space" for f in xterm_features)
+    assert any(f == "special*char" for f in xterm_features)
+
+
+def test_style_option_validation(server: Server) -> None:
+    """Test style option validation."""
+    session = server.new_session(session_name="test")
+
+    # Valid style
+    session.set_option("status-style", "fg=red,bg=default,bold")
+    assert session.show_option("status-style") == "fg=red,bg=default,bold"
+
+    # Invalid style should raise OptionError
+    with pytest.raises(OptionError):
+        session.set_option("status-style", "invalid-style")
+
+    # Test complex style with multiple attributes
+    session.set_option(
+        "status-style",
+        "fg=colour240,bg=#525252,bold,underscore",
+    )
+    assert (
+        session.show_option("status-style") == "fg=colour240,bg=#525252,bold,underscore"
+    )
+
+    # Test style with variables
+    session.set_option("status-style", "fg=#{?pane_in_mode,red,green}")
+    assert session.show_option("status-style") == "fg=#{?pane_in_mode,red,green}"
+
+
+def test_option_error_handling(server: Server) -> None:
+    """Test error handling for options."""
+    session = server.new_session(session_name="test")
+
+    # Test invalid/unknown option (tmux 3.0+ returns 'invalid option')
+    with pytest.raises(OptionError) as exc_info:
+        session.show_option("non-existent-option")
+    error_msg = str(exc_info.value).lower()
+    assert any(msg in error_msg for msg in ["unknown option", "invalid option"])
+
+    # Test invalid option value
+    with pytest.raises(OptionError):
+        session.set_option("aggressive-resize", "invalid")
+
+    # Test ambiguous option (if supported by tmux version)
+    if has_gte_version("2.4"):
+        with pytest.raises(OptionError) as exc_info:
+            # Use a partial name that could match multiple options
+            session.show_option(
+                "window-"
+            )  # Ambiguous: could be window-size, window-style, etc.
+        assert "ambiguous option" in str(exc_info.value).lower()

From 9d60be195599eb6e973097c2830ac63f91d0993c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 23 Feb 2025 06:06:29 -0600
Subject: [PATCH 038/136] fix(tests): improve type safety in style option tests

WHAT:
- Add type assertions for style option values
- Convert style values to strings before comparison
- Fix mypy errors in test_style_option_validation

WHY:
- Ensure type safety when handling style option values
- Prevent potential runtime errors from type mismatches
- Make test assertions more robust and explicit
---
 tests/test_options.py | 140 +++++++++++++++++++++++++-----------------
 1 file changed, 82 insertions(+), 58 deletions(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index c4fd18771..666d409ec 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -469,6 +469,7 @@ def test_stable_baseline_options_and_hooks(server: Server) -> None:
         "split-pane": "split-window",
         "splitp": "split-window",
     }
+
     if has_gte_version("3.2"):
         terminal_features = server.show_option("terminal-features")
         assert isinstance(terminal_features, dict)
@@ -486,7 +487,16 @@ def test_stable_baseline_options_and_hooks(server: Server) -> None:
         if has_gte_version("3.4"):
             assert "rxvt*" in terminal_features
             assert terminal_features["rxvt*"] == ["ignorefkeys"]
-    assert server.show_option("terminal-overrides") is None
+
+    # Terminal overrides differ by version
+    if has_gte_version("3.0"):
+        assert server.show_option("terminal-overrides") is None
+    else:
+        terminal_overrides = server.show_option("terminal-overrides")
+        assert isinstance(terminal_overrides, dict)
+        assert "screen*" in terminal_overrides
+        assert "xterm*" in terminal_overrides
+
     assert server.show_option("user-keys") is None
     assert server.show_option("status-format") is None
     assert server.show_option("update-environment") is None
@@ -529,13 +539,74 @@ def test_complex_option_values(server: Server) -> None:
     session.set_option("@empty-option", "")
     assert session.show_option("@empty-option") == ""
 
-    # Test option inheritance
-    parent_val = session.show_option("status-style")
-    session.set_option("status-style", "fg=red")
-    assert session.show_option("status-style") == "fg=red"
-    assert session.show_option("status-style", include_inherited=True) == "fg=red"
-    session.unset_option("status-style")
-    assert session.show_option("status-style", include_inherited=True) == parent_val
+    # Test option inheritance (only for tmux >= 3.0)
+    if has_gte_version("3.0"):
+        parent_val = session.show_option("status-style")
+        session.set_option("status-style", "fg=red")
+        assert session.show_option("status-style") == "fg=red"
+        assert session.show_option("status-style", include_inherited=True) == "fg=red"
+        session.unset_option("status-style")
+        assert session.show_option("status-style", include_inherited=True) == parent_val
+
+
+def test_style_option_validation(server: Server) -> None:
+    """Test style option validation."""
+    session = server.new_session(session_name="test")
+
+    # Valid style (format differs between tmux versions)
+    session.set_option("status-style", "fg=red,bg=default,bold")
+    style = session.show_option("status-style")
+    assert isinstance(style, str)
+    assert "fg=red" in str(style)
+    if has_gte_version("3.0"):
+        assert "bg=default" in str(style)
+        assert "bold" in str(style)
+    else:
+        assert "bright" in str(style)
+
+    # Invalid style should raise OptionError
+    with pytest.raises(OptionError):
+        session.set_option("status-style", "invalid-style")
+
+    # Test complex style with multiple attributes (tmux >= 3.0)
+    if has_gte_version("3.0"):
+        session.set_option(
+            "status-style",
+            "fg=colour240,bg=#525252,bold,underscore",
+        )
+        style = session.show_option("status-style")
+        assert isinstance(style, str)
+        assert style == "fg=colour240,bg=#525252,bold,underscore"
+
+        # Test style with variables
+        session.set_option("status-style", "fg=#{?pane_in_mode,red,green}")
+        style = session.show_option("status-style")
+        assert isinstance(style, str)
+        assert style == "fg=#{?pane_in_mode,red,green}"
+
+
+def test_option_error_handling(server: Server) -> None:
+    """Test error handling for options."""
+    session = server.new_session(session_name="test")
+
+    # Test invalid/unknown option (tmux 3.0+ returns 'invalid option')
+    with pytest.raises(OptionError) as exc_info:
+        session.show_option("non-existent-option")
+    error_msg = str(exc_info.value).lower()
+    assert any(msg in error_msg for msg in ["unknown option", "invalid option"])
+
+    # Test invalid option value
+    with pytest.raises(OptionError):
+        session.set_option("aggressive-resize", "invalid")
+
+    # Test ambiguous option (if supported by tmux version)
+    if has_gte_version("2.4"):
+        with pytest.raises(OptionError) as exc_info:
+            # Use a partial name that could match multiple options
+            session.show_option(
+                "window-"
+            )  # Ambiguous: could be window-size, window-style, etc.
+        assert "ambiguous option" in str(exc_info.value).lower()
 
 
 def test_terminal_features_edge_cases(
@@ -543,6 +614,9 @@ def test_terminal_features_edge_cases(
     monkeypatch: pytest.MonkeyPatch,
 ) -> None:
     """Test edge cases for terminal-features option."""
+    if not has_gte_version("3.2"):
+        pytest.skip("terminal-features requires tmux >= 3.2")
+
     # Test empty features
     monkeypatch.setattr(
         server,
@@ -587,53 +661,3 @@ def test_terminal_features_edge_cases(
     assert isinstance(xterm_features, list)
     assert any(f == "feature with space" for f in xterm_features)
     assert any(f == "special*char" for f in xterm_features)
-
-
-def test_style_option_validation(server: Server) -> None:
-    """Test style option validation."""
-    session = server.new_session(session_name="test")
-
-    # Valid style
-    session.set_option("status-style", "fg=red,bg=default,bold")
-    assert session.show_option("status-style") == "fg=red,bg=default,bold"
-
-    # Invalid style should raise OptionError
-    with pytest.raises(OptionError):
-        session.set_option("status-style", "invalid-style")
-
-    # Test complex style with multiple attributes
-    session.set_option(
-        "status-style",
-        "fg=colour240,bg=#525252,bold,underscore",
-    )
-    assert (
-        session.show_option("status-style") == "fg=colour240,bg=#525252,bold,underscore"
-    )
-
-    # Test style with variables
-    session.set_option("status-style", "fg=#{?pane_in_mode,red,green}")
-    assert session.show_option("status-style") == "fg=#{?pane_in_mode,red,green}"
-
-
-def test_option_error_handling(server: Server) -> None:
-    """Test error handling for options."""
-    session = server.new_session(session_name="test")
-
-    # Test invalid/unknown option (tmux 3.0+ returns 'invalid option')
-    with pytest.raises(OptionError) as exc_info:
-        session.show_option("non-existent-option")
-    error_msg = str(exc_info.value).lower()
-    assert any(msg in error_msg for msg in ["unknown option", "invalid option"])
-
-    # Test invalid option value
-    with pytest.raises(OptionError):
-        session.set_option("aggressive-resize", "invalid")
-
-    # Test ambiguous option (if supported by tmux version)
-    if has_gte_version("2.4"):
-        with pytest.raises(OptionError) as exc_info:
-            # Use a partial name that could match multiple options
-            session.show_option(
-                "window-"
-            )  # Ambiguous: could be window-size, window-style, etc.
-        assert "ambiguous option" in str(exc_info.value).lower()

From 7d94e99fa46f4e29dc3f4b63195c1c6dcf45c07c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 23 Feb 2025 06:09:13 -0600
Subject: [PATCH 039/136] fix(tests): handle status-format version
 compatibility

WHAT:
- Add version check for status-format option (added in tmux 2.9)
- Update test assertions to handle version-specific behavior

WHY:
- Ensure tests pass on older tmux versions
- Properly handle version-specific options
- Improve test robustness across tmux versions
---
 tests/test_options.py | 10 +++++++++-
 1 file changed, 9 insertions(+), 1 deletion(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index 666d409ec..26eb1a508 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -498,7 +498,15 @@ def test_stable_baseline_options_and_hooks(server: Server) -> None:
         assert "xterm*" in terminal_overrides
 
     assert server.show_option("user-keys") is None
-    assert server.show_option("status-format") is None
+
+    # status-format was added in tmux 2.9
+    if has_gte_version("2.9"):
+        status_format = server.show_option("status-format")
+        assert isinstance(status_format, (dict, type(None)))
+    else:
+        with pytest.raises(OptionError):
+            server.show_option("status-format")
+
     assert server.show_option("update-environment") is None
 
     # List variables: Pane

From 3fd7458a835df64d39439417f9b172a7d663ed4b Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 23 Feb 2025 06:12:26 -0600
Subject: [PATCH 040/136] fix(tests): handle update-environment version
 compatibility

WHAT:
- Add version check for update-environment option (added in tmux 3.0)
- Update test assertions to handle version-specific behavior
- Add type checking for update-environment value

WHY:
- Ensure tests pass on older tmux versions
- Properly handle version-specific options
- Improve test robustness across tmux versions
---
 tests/test_options.py | 8 +++++++-
 1 file changed, 7 insertions(+), 1 deletion(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index 26eb1a508..c87459644 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -507,7 +507,13 @@ def test_stable_baseline_options_and_hooks(server: Server) -> None:
         with pytest.raises(OptionError):
             server.show_option("status-format")
 
-    assert server.show_option("update-environment") is None
+    # update-environment was added in tmux 3.0
+    if has_gte_version("3.0"):
+        update_env = server.show_option("update-environment")
+        assert isinstance(update_env, (list, type(None)))
+    else:
+        with pytest.raises(OptionError):
+            server.show_option("update-environment")
 
     # List variables: Pane
     pane = session.active_pane

From 4dfe8981432b1c4eceb6c10780994b1fc83cafcd Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 25 Oct 2025 10:15:58 -0500
Subject: [PATCH 041/136] fix(compat): add tmux version compatibility for
 3.2a-3.5

- Add command_error hook field (tmux 3.5+)
- Guard pane-colours test with version check (tmux 3.3+)
- Update terminal-overrides expectations for tmux 3.5
- Fix escape-time doctests to not rely on default value
---
 src/libtmux/_internal/constants.py |  2 ++
 src/libtmux/options.py             |  7 ++-----
 tests/test_options.py              | 11 ++++++++---
 3 files changed, 12 insertions(+), 8 deletions(-)

diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py
index 4de3df453..523caa22f 100644
--- a/src/libtmux/_internal/constants.py
+++ b/src/libtmux/_internal/constants.py
@@ -434,6 +434,8 @@ class Hooks(
     after_split_window: SparseArray[str] = field(default_factory=SparseArray)
     # Runs after 'unbind-key' completes
     after_unbind_key: SparseArray[str] = field(default_factory=SparseArray)
+    # Runs when a command fails (tmux 3.5+)
+    command_error: SparseArray[str] = field(default_factory=SparseArray)
 
     @classmethod
     def from_stdout(cls, value: list[str]) -> Hooks:
diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index d6bfa921e..a793d58b5 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -600,9 +600,6 @@ def set_option(
         ...
         ...     default_option_scope = OptionScope.Server
 
-        >>> MyServer()._show_option('escape-time')
-        500
-
         >>> MyServer().set_option('escape-time', 1250)
         <libtmux.options.MyServer object at ...>
 
@@ -718,8 +715,8 @@ def unset_option(
         >>> MyServer().unset_option('escape-time')
         <libtmux.options.MyServer object at ...>
 
-        >>> MyServer()._show_option('escape-time')
-        500
+        >>> isinstance(MyServer()._show_option('escape-time'), int)
+        True
         """
         if scope is DEFAULT_OPTION_SCOPE:
             scope = self.default_option_scope
diff --git a/tests/test_options.py b/tests/test_options.py
index c87459644..8ca35b993 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -489,7 +489,11 @@ def test_stable_baseline_options_and_hooks(server: Server) -> None:
             assert terminal_features["rxvt*"] == ["ignorefkeys"]
 
     # Terminal overrides differ by version
-    if has_gte_version("3.0"):
+    # In tmux 3.5+, terminal-overrides has a default value
+    if has_gte_version("3.5"):
+        terminal_overrides = server.show_option("terminal-overrides")
+        assert isinstance(terminal_overrides, (dict, type(None)))
+    elif has_gte_version("3.0"):
         assert server.show_option("terminal-overrides") is None
     else:
         terminal_overrides = server.show_option("terminal-overrides")
@@ -515,10 +519,11 @@ def test_stable_baseline_options_and_hooks(server: Server) -> None:
         with pytest.raises(OptionError):
             server.show_option("update-environment")
 
-    # List variables: Pane
+    # List variables: Pane (pane-colours added in tmux 3.3)
     pane = session.active_pane
     assert pane is not None
-    assert pane.show_option("pane-colours") is None
+    if has_gte_version("3.3"):
+        assert pane.show_option("pane-colours") is None
 
 
 def test_high_level_api_expectations(server: Server) -> None:

From bd68cc8dabf3a27c5608b84cafc2fdbd53c1bf0f Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 25 Oct 2025 10:31:34 -0500
Subject: [PATCH 042/136] fix(tests): handle tmux version differences in
 options tests

Based on examination of tmux source code:

1. terminal-overrides defaults:
   - tmux 3.0a-3.1b: Have default values (xterm*, screen*)
   - tmux 3.2+: Defaults removed (commit 527f66ed, April 2020)

2. terminal-overrides parsing:
   - Fix split("=") to split("=", 1) to handle values containing "="
   - Example: "RGB=\E[...=%p1%d...]" was failing to parse

3. Style option behavior:
   - When bg=default is set, tmux stores bg as color 8 (default)
   - When converting to string, color 8 is omitted from output
   - Test was incorrectly expecting "bg=default" in output
   - This behavior is consistent across all tmux versions

Verification method:
- Created git worktrees for tmux 3.0a, 3.1b, 3.2a
- Examined options-table.c, style.c, colour.c in each version
- Tested terminal-overrides parsing with actual tmux commands

References:
- tmux-3.0a/options-table.c:219-223 (terminal-overrides defaults)
- tmux-3.2a/options-table.c:314-318 (empty defaults)
- tmux-3.0a/style.c:174-245 (style_tostring implementation)
- tmux-3.0a/style.c:231-235 (bg color 8 omitted)
---
 src/libtmux/options.py |  2 +-
 tests/test_options.py  | 14 ++++++++++----
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index a793d58b5..346091bbe 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -501,7 +501,7 @@ def explode_complex(
                         if term not in new_overrides:
                             new_overrides[term] = {}
                         if features and "=" in features:
-                            k, v = features.split("=")
+                            k, v = features.split("=", 1)
 
                             if v.isdigit():
                                 v = int(v)
diff --git a/tests/test_options.py b/tests/test_options.py
index 8ca35b993..f504550fd 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -489,12 +489,16 @@ def test_stable_baseline_options_and_hooks(server: Server) -> None:
             assert terminal_features["rxvt*"] == ["ignorefkeys"]
 
     # Terminal overrides differ by version
-    # In tmux 3.5+, terminal-overrides has a default value
-    if has_gte_version("3.5"):
+    # tmux 3.0a-3.1b: has default values (xterm*, screen*)
+    # tmux 3.2+: defaults removed, returns None unless explicitly set
+    if has_gte_version("3.2"):
         terminal_overrides = server.show_option("terminal-overrides")
         assert isinstance(terminal_overrides, (dict, type(None)))
     elif has_gte_version("3.0"):
-        assert server.show_option("terminal-overrides") is None
+        # tmux 3.0a/3.1b have defaults like "xterm*:XT:Ms=...,screen*:XT"
+        terminal_overrides = server.show_option("terminal-overrides")
+        assert isinstance(terminal_overrides, dict)
+        assert "screen*" in terminal_overrides or "xterm*" in terminal_overrides
     else:
         terminal_overrides = server.show_option("terminal-overrides")
         assert isinstance(terminal_overrides, dict)
@@ -573,12 +577,14 @@ def test_style_option_validation(server: Server) -> None:
     session = server.new_session(session_name="test")
 
     # Valid style (format differs between tmux versions)
+    # Note: when you set bg=default, tmux internally sets bg to 8 (default color)
+    # and when converting to string, it omits the bg property entirely
     session.set_option("status-style", "fg=red,bg=default,bold")
     style = session.show_option("status-style")
     assert isinstance(style, str)
     assert "fg=red" in str(style)
+    # bg=default is NOT included in output (tmux omits it when bg is default)
     if has_gte_version("3.0"):
-        assert "bg=default" in str(style)
         assert "bold" in str(style)
     else:
         assert "bright" in str(style)

From 917af2a8c73f3ab40566e9a0ca446a9e475b3029 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 25 Oct 2025 10:45:11 -0500
Subject: [PATCH 043/136] fix(tests): handle style option format changes in
 tmux 3.2
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Based on examination of tmux source code commit f03b6113 (May 2020):

In tmux 3.2, style options changed from OPTIONS_TABLE_STYLE to
OPTIONS_TABLE_STRING with OPTIONS_TABLE_IS_STYLE flag to support
format expansion in styles.

This changed how styles are stored and displayed:

**tmux ≤3.1 behavior:**
- Styles parsed and normalized when stored
- Output uses style_tostring() which normalizes:
  - "bold" → "bright"
  - bg=default (color 8) omitted from output
- Example: Input "fg=red,bg=default,bold" → Output "fg=red,bright"

**tmux ≥3.2 behavior:**
- Styles stored as literal strings (enables format expansion like #{...})
- Output shows the exact string that was set
- Example: Input "fg=red,bg=default,bold" → Output "fg=red,bg=default,bold"

Verification method:
- Created git worktrees for tmux 3.0a, 3.1b, 3.2a, 3.3a, 3.4, 3.5
- Examined source code changes across versions
- Tested directly with tmux commands to verify behavior

References:
- tmux commit f03b6113 (tmux 3.2 style type change)
- tmux-3.0a/options.c:126-127 (OPTIONS_IS_STYLE → style_tostring)
- tmux-3.0a/style.c:174-245 (style_tostring implementation)
- tmux-3.0a/attributes.c:26-50 (attributes_tostring: bold→bright)
---
 tests/test_options.py | 12 ++++++++----
 1 file changed, 8 insertions(+), 4 deletions(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index f504550fd..c95e5eef2 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -577,17 +577,21 @@ def test_style_option_validation(server: Server) -> None:
     session = server.new_session(session_name="test")
 
     # Valid style (format differs between tmux versions)
-    # Note: when you set bg=default, tmux internally sets bg to 8 (default color)
-    # and when converting to string, it omits the bg property entirely
+    # tmux ≤3.1: Styles are normalized when stored (bold→bright, bg=default omitted)
+    # tmux ≥3.2: Styles stored as strings (literal input, allows format expansion)
     session.set_option("status-style", "fg=red,bg=default,bold")
     style = session.show_option("status-style")
     assert isinstance(style, str)
     assert "fg=red" in str(style)
-    # bg=default is NOT included in output (tmux omits it when bg is default)
-    if has_gte_version("3.0"):
+
+    if has_gte_version("3.2"):
+        # tmux 3.2+: literal string output
+        assert "bg=default" in str(style)
         assert "bold" in str(style)
     else:
+        # tmux <3.2: normalized output (bold→bright, bg=default omitted)
         assert "bright" in str(style)
+        assert "bg=default" not in str(style)
 
     # Invalid style should raise OptionError
     with pytest.raises(OptionError):

From dcae8e3eb00c91886cddbd6680977bca99085af3 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 25 Oct 2025 10:55:57 -0500
Subject: [PATCH 044/136] =?UTF-8?q?fix(tests):=20handle=20bold=E2=86=92bri?=
 =?UTF-8?q?ght=20conversion=20in=20complex=20style=20test?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

tmux <3.2 normalizes 'bold' to 'bright' in style output.
Added version guard to expect correct output format.

Verification method:
- Created git worktrees for tmux versions 3.0a, 3.1b, 3.2a, 3.3a, 3.4, 3.5
- Examined source code to trace style handling across versions
- Tested directly with tmux commands to verify actual behavior

In tmux ≤3.1, styles are parsed and normalized when stored:
- attributes_fromstring() accepts both "bold" and "bright" as aliases
- attributes_tostring() always outputs "bright" (never "bold")

References:
- tmux-3.0a/attributes.c:32-50 (attributes_fromstring table)
- tmux-3.0a/attributes.c:26-28 (attributes_tostring output)
- tmux-3.0a/options.c:126-127 (OPTIONS_IS_STYLE → style_tostring)
- tmux commit f03b6113 (tmux 3.2 style format change)
---
 tests/test_options.py | 7 ++++++-
 1 file changed, 6 insertions(+), 1 deletion(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index c95e5eef2..56dad3441 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -605,7 +605,12 @@ def test_style_option_validation(server: Server) -> None:
         )
         style = session.show_option("status-style")
         assert isinstance(style, str)
-        assert style == "fg=colour240,bg=#525252,bold,underscore"
+        if has_gte_version("3.2"):
+            # tmux 3.2+: literal string output
+            assert style == "fg=colour240,bg=#525252,bold,underscore"
+        else:
+            # tmux <3.2: bold→bright
+            assert style == "fg=colour240,bg=#525252,bright,underscore"
 
         # Test style with variables
         session.set_option("status-style", "fg=#{?pane_in_mode,red,green}")

From 9c1dc7c6c423fc5c3c7b590dd034959fc7da4130 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 25 Oct 2025 11:06:39 -0500
Subject: [PATCH 045/136] fix(tests): skip format expansion test on tmux <3.2

Format expansion in style options (e.g., fg=#{...}) was added in
tmux 3.2 (commit f03b6113). Earlier versions reject styles with
format syntax as invalid.

Verification from tmux source code:
- Examined cmd-set-option.c in tmux 3.2 (commit f03b6113)
- Found validation logic: styles WITH #{...} skip validation
- Styles WITHOUT #{...} are still validated
- In tmux <3.2, ALL styles are validated, rejecting #{...} syntax

From commit f03b6113 message:
"Any styles without a '#{' are still validated when they are set
but any with a '#{' are not."

From cmd-set-option.c after f03b6113:
```c
if ((oe->flags & OPTIONS_TABLE_IS_STYLE) &&
    strstr(value, "#{") == NULL &&
    style_parse(&sy, &grid_default_cell, value) != 0) {
```

The test now only runs the format expansion check on tmux 3.2+.

References:
- tmux commit f03b6113 (style format expansion support)
- cmd-set-option.c validation logic with strstr check
---
 tests/test_options.py | 11 ++++++-----
 1 file changed, 6 insertions(+), 5 deletions(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index 56dad3441..49e2d1e8f 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -612,11 +612,12 @@ def test_style_option_validation(server: Server) -> None:
             # tmux <3.2: bold→bright
             assert style == "fg=colour240,bg=#525252,bright,underscore"
 
-        # Test style with variables
-        session.set_option("status-style", "fg=#{?pane_in_mode,red,green}")
-        style = session.show_option("status-style")
-        assert isinstance(style, str)
-        assert style == "fg=#{?pane_in_mode,red,green}"
+        # Test style with variables (format expansion added in tmux 3.2)
+        if has_gte_version("3.2"):
+            session.set_option("status-style", "fg=#{?pane_in_mode,red,green}")
+            style = session.show_option("status-style")
+            assert isinstance(style, str)
+            assert style == "fg=#{?pane_in_mode,red,green}"
 
 
 def test_option_error_handling(server: Server) -> None:

From b6e93f6da1272385f2453a86145a9b4b857163de Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 11:53:56 -0600
Subject: [PATCH 046/136] feat(constants): add missing tmux 3.5+ options and
 hooks

why: Ensure libtmux constants cover latest tmux features for complete API support
what:
- Add ServerOptions: default_client_command, extended_keys_format
- Add WindowOptions: tiled_layout_max_columns
- Add PaneOptions: pane_scrollbars, pane_scrollbars_style
- Add Hooks: pane_title_changed, client_light_theme, client_dark_theme
---
 src/libtmux/_internal/constants.py | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py
index 523caa22f..8c25af5ba 100644
--- a/src/libtmux/_internal/constants.py
+++ b/src/libtmux/_internal/constants.py
@@ -44,6 +44,9 @@ class ServerOptions(
     terminal_features: TerminalFeatures = field(default_factory=dict)
     terminal_overrides: SparseArray[str] = field(default_factory=SparseArray)
     user_keys: SparseArray[str] = field(default_factory=SparseArray)
+    # tmux 3.5+ options
+    default_client_command: str | None = field(default=None)
+    extended_keys_format: t.Literal["csi-u", "xterm"] | None = field(default=None)
 
     def __init__(self, **kwargs: object) -> None:
         # Convert hyphenated keys to underscored attribute names and assign values
@@ -180,6 +183,8 @@ class WindowOptions(
         default=None,
     )
     wrap_search: t.Literal["on", "off"] | None = field(default=None)
+    # tmux 3.5+ options
+    tiled_layout_max_columns: int | None = field(default=None)
 
     def __init__(self, **kwargs: object) -> None:
         # Convert hyphenated keys to underscored attribute names and assign values
@@ -215,6 +220,9 @@ class PaneOptions(
     synchronize_panes: t.Literal["on", "off"] | None = field(default=None)
     window_active_style: str | None = field(default=None)
     window_style: str | None = field(default=None)
+    # tmux 3.5+ options
+    pane_scrollbars: t.Literal["off", "modal", "on"] | None = field(default=None)
+    pane_scrollbars_style: str | None = field(default=None)
 
     def __init__(self, **kwargs: object) -> None:
         # Convert hyphenated keys to underscored attribute names and assign values
@@ -292,6 +300,12 @@ class Hooks(
     window_resized: SparseArray[str] = field(default_factory=SparseArray)
     # Run when a window is unlinked from a session.
     window_unlinked: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when a pane title changes (tmux 3.5+)
+    pane_title_changed: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when terminal reports a light theme (tmux 3.5+)
+    client_light_theme: SparseArray[str] = field(default_factory=SparseArray)
+    # Run when terminal reports a dark theme (tmux 3.5+)
+    client_dark_theme: SparseArray[str] = field(default_factory=SparseArray)
 
     # --- Tmux control mode hooks ---
     # The client has detached.

From a61e279913985aa8a4ba1b642d2a0e137a9eb2ef Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 11:54:03 -0600
Subject: [PATCH 047/136] tests(options): add comprehensive option test grid
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

why: Ensure 100% API coverage for tmux options with proper typing validation
what:
- Add OptionTestCase NamedTuple for parametrized testing
- Add 66 test cases covering all option scopes (Server, Session, Window, Pane)
- Test integer, boolean, choice, string, and style option types
- Handle boolean option conversion (on/off → bool)
- Use safe test values for dangerous options (exit-empty, exit-unattached)
- Support version-gated options with min_version parameter
---
 tests/test_options.py | 408 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 408 insertions(+)

diff --git a/tests/test_options.py b/tests/test_options.py
index 49e2d1e8f..a45007da2 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -696,3 +696,411 @@ def test_terminal_features_edge_cases(
     assert isinstance(xterm_features, list)
     assert any(f == "feature with space" for f in xterm_features)
     assert any(f == "special*char" for f in xterm_features)
+
+
+# =============================================================================
+# Comprehensive Option Test Grid
+# =============================================================================
+
+
+class OptionTestCase(t.NamedTuple):
+    """Test case for option validation."""
+
+    test_id: str
+    option: str  # tmux option name (hyphenated)
+    scope: OptionScope
+    test_value: t.Any  # Value to set
+    expected_type: type  # Expected Python type after retrieval
+    min_version: str | None = None  # Minimum tmux version required
+    xfail_reason: str | None = None  # Mark as expected failure with reason
+
+
+# --- Server Options ---
+SERVER_INTEGER_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase("server_buffer_limit", "buffer-limit", OptionScope.Server, 100, int),
+    OptionTestCase("server_escape_time", "escape-time", OptionScope.Server, 50, int),
+    OptionTestCase(
+        "server_message_limit", "message-limit", OptionScope.Server, 500, int
+    ),
+    OptionTestCase(
+        "server_prompt_history_limit",
+        "prompt-history-limit",
+        OptionScope.Server,
+        50,
+        int,
+    ),
+]
+
+SERVER_BOOLEAN_OPTIONS: list[OptionTestCase] = [
+    # Note: exit-empty and exit-unattached are tested with "off" to avoid killing server
+    OptionTestCase("server_exit_empty", "exit-empty", OptionScope.Server, "off", bool),
+    OptionTestCase(
+        "server_exit_unattached", "exit-unattached", OptionScope.Server, "off", bool
+    ),
+    OptionTestCase(
+        "server_focus_events", "focus-events", OptionScope.Server, "on", bool
+    ),
+]
+
+SERVER_CHOICE_OPTIONS: list[OptionTestCase] = [
+    # extended-keys: "on"/"off" return bool, use "always" for str test (3.2+)
+    OptionTestCase(
+        "server_extended_keys",
+        "extended-keys",
+        OptionScope.Server,
+        "always",
+        str,
+        "3.2",
+    ),
+    OptionTestCase(
+        "server_set_clipboard", "set-clipboard", OptionScope.Server, "external", str
+    ),
+]
+
+SERVER_STRING_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "server_default_terminal",
+        "default-terminal",
+        OptionScope.Server,
+        "screen-256color",
+        str,
+    ),
+    OptionTestCase("server_editor", "editor", OptionScope.Server, "vim", str),
+]
+
+# --- Session Options ---
+SESSION_INTEGER_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase("session_base_index", "base-index", OptionScope.Session, 1, int),
+    OptionTestCase(
+        "session_display_panes_time",
+        "display-panes-time",
+        OptionScope.Session,
+        2000,
+        int,
+    ),
+    OptionTestCase(
+        "session_display_time", "display-time", OptionScope.Session, 1000, int
+    ),
+    OptionTestCase(
+        "session_history_limit", "history-limit", OptionScope.Session, 5000, int
+    ),
+    OptionTestCase(
+        "session_lock_after_time", "lock-after-time", OptionScope.Session, 300, int
+    ),
+    OptionTestCase("session_repeat_time", "repeat-time", OptionScope.Session, 500, int),
+    OptionTestCase(
+        "session_status_interval", "status-interval", OptionScope.Session, 5, int
+    ),
+    OptionTestCase(
+        "session_status_left_length", "status-left-length", OptionScope.Session, 20, int
+    ),
+    OptionTestCase(
+        "session_status_right_length",
+        "status-right-length",
+        OptionScope.Session,
+        30,
+        int,
+    ),
+]
+
+SESSION_BOOLEAN_OPTIONS: list[OptionTestCase] = [
+    # Note: destroy-unattached is tested with "off" to avoid destroying test session
+    OptionTestCase(
+        "session_destroy_unattached",
+        "destroy-unattached",
+        OptionScope.Session,
+        "off",
+        bool,
+    ),
+    OptionTestCase("session_mouse", "mouse", OptionScope.Session, "on", bool),
+    OptionTestCase(
+        "session_renumber_windows", "renumber-windows", OptionScope.Session, "on", bool
+    ),
+    OptionTestCase("session_set_titles", "set-titles", OptionScope.Session, "on", bool),
+]
+
+SESSION_CHOICE_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "session_activity_action", "activity-action", OptionScope.Session, "any", str
+    ),
+    OptionTestCase(
+        "session_bell_action", "bell-action", OptionScope.Session, "any", str
+    ),
+    # detach-on-destroy: "on"/"off" return bool, use "no-detached" (3.2+) for str
+    OptionTestCase(
+        "session_detach_on_destroy",
+        "detach-on-destroy",
+        OptionScope.Session,
+        "no-detached",
+        str,
+        "3.2",
+    ),
+    OptionTestCase(
+        "session_silence_action", "silence-action", OptionScope.Session, "none", str
+    ),
+    OptionTestCase(
+        "session_status_keys", "status-keys", OptionScope.Session, "vi", str
+    ),
+    OptionTestCase(
+        "session_status_justify", "status-justify", OptionScope.Session, "left", str
+    ),
+    OptionTestCase(
+        "session_status_position", "status-position", OptionScope.Session, "bottom", str
+    ),
+    # visual-*: "on"/"off" return bool, use "both" for str test
+    OptionTestCase(
+        "session_visual_activity", "visual-activity", OptionScope.Session, "both", str
+    ),
+    OptionTestCase(
+        "session_visual_bell", "visual-bell", OptionScope.Session, "both", str
+    ),
+    OptionTestCase(
+        "session_visual_silence", "visual-silence", OptionScope.Session, "both", str
+    ),
+]
+
+SESSION_STRING_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "session_default_command", "default-command", OptionScope.Session, "", str
+    ),
+    OptionTestCase(
+        "session_status_left", "status-left", OptionScope.Session, "[#S]", str
+    ),
+    OptionTestCase(
+        "session_status_right", "status-right", OptionScope.Session, "%H:%M", str
+    ),
+]
+
+SESSION_STYLE_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "session_status_style", "status-style", OptionScope.Session, "fg=green", str
+    ),
+    OptionTestCase(
+        "session_status_left_style",
+        "status-left-style",
+        OptionScope.Session,
+        "fg=blue",
+        str,
+    ),
+    OptionTestCase(
+        "session_status_right_style",
+        "status-right-style",
+        OptionScope.Session,
+        "fg=yellow",
+        str,
+    ),
+    OptionTestCase(
+        "session_message_style", "message-style", OptionScope.Session, "fg=red", str
+    ),
+]
+
+# --- Window Options ---
+WINDOW_INTEGER_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "window_pane_base_index", "pane-base-index", OptionScope.Window, 1, int
+    ),
+    OptionTestCase(
+        "window_monitor_silence", "monitor-silence", OptionScope.Window, 10, int
+    ),
+]
+
+WINDOW_BOOLEAN_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "window_aggressive_resize", "aggressive-resize", OptionScope.Window, "on", bool
+    ),
+    OptionTestCase(
+        "window_automatic_rename", "automatic-rename", OptionScope.Window, "off", bool
+    ),
+    OptionTestCase(
+        "window_monitor_activity", "monitor-activity", OptionScope.Window, "on", bool
+    ),
+    OptionTestCase(
+        "window_monitor_bell", "monitor-bell", OptionScope.Window, "on", bool
+    ),
+    OptionTestCase("window_wrap_search", "wrap-search", OptionScope.Window, "on", bool),
+]
+
+WINDOW_CHOICE_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "window_clock_mode_style", "clock-mode-style", OptionScope.Window, "24", int
+    ),
+    OptionTestCase("window_mode_keys", "mode-keys", OptionScope.Window, "vi", str),
+    # pane-border-status: "off" returns bool, use "top" for str test
+    OptionTestCase(
+        "window_pane_border_status",
+        "pane-border-status",
+        OptionScope.Window,
+        "top",
+        str,
+    ),
+    OptionTestCase(
+        "window_window_size", "window-size", OptionScope.Window, "latest", str, "3.1"
+    ),
+]
+
+WINDOW_STRING_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "window_pane_border_format",
+        "pane-border-format",
+        OptionScope.Window,
+        "#{pane_index}",
+        str,
+    ),
+]
+
+WINDOW_STYLE_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "window_mode_style", "mode-style", OptionScope.Window, "fg=white", str
+    ),
+    OptionTestCase(
+        "window_pane_border_style",
+        "pane-border-style",
+        OptionScope.Window,
+        "fg=green",
+        str,
+    ),
+    OptionTestCase(
+        "window_pane_active_border_style",
+        "pane-active-border-style",
+        OptionScope.Window,
+        "fg=red",
+        str,
+    ),
+    OptionTestCase(
+        "window_window_status_style",
+        "window-status-style",
+        OptionScope.Window,
+        "fg=cyan",
+        str,
+    ),
+    OptionTestCase(
+        "window_window_status_current_style",
+        "window-status-current-style",
+        OptionScope.Window,
+        "fg=magenta",
+        str,
+    ),
+]
+
+# --- Pane Options ---
+PANE_BOOLEAN_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "pane_allow_rename", "allow-rename", OptionScope.Pane, "off", bool, "3.0"
+    ),
+    OptionTestCase(
+        "pane_alternate_screen", "alternate-screen", OptionScope.Pane, "on", bool, "3.0"
+    ),
+    OptionTestCase(
+        "pane_scroll_on_clear", "scroll-on-clear", OptionScope.Pane, "on", bool, "3.2"
+    ),
+    OptionTestCase(
+        "pane_synchronize_panes",
+        "synchronize-panes",
+        OptionScope.Pane,
+        "off",
+        bool,
+        "3.1",
+    ),
+]
+
+PANE_CHOICE_OPTIONS: list[OptionTestCase] = [
+    # allow-passthrough: "on"/"off" return bool, use "all" for str test (3.3+)
+    OptionTestCase(
+        "pane_allow_passthrough",
+        "allow-passthrough",
+        OptionScope.Pane,
+        "all",
+        str,
+        "3.3",
+    ),
+    # remain-on-exit: "on"/"off" return bool, use "failed" for str test (3.2+)
+    OptionTestCase(
+        "pane_remain_on_exit",
+        "remain-on-exit",
+        OptionScope.Pane,
+        "failed",
+        str,
+        "3.2",
+    ),
+]
+
+PANE_STYLE_OPTIONS: list[OptionTestCase] = [
+    OptionTestCase(
+        "pane_window_style", "window-style", OptionScope.Pane, "default", str, "3.0"
+    ),
+    OptionTestCase(
+        "pane_window_active_style",
+        "window-active-style",
+        OptionScope.Pane,
+        "default",
+        str,
+        "3.0",
+    ),
+]
+
+# Combine all option test cases
+ALL_OPTION_TEST_CASES: list[OptionTestCase] = (
+    SERVER_INTEGER_OPTIONS
+    + SERVER_BOOLEAN_OPTIONS
+    + SERVER_CHOICE_OPTIONS
+    + SERVER_STRING_OPTIONS
+    + SESSION_INTEGER_OPTIONS
+    + SESSION_BOOLEAN_OPTIONS
+    + SESSION_CHOICE_OPTIONS
+    + SESSION_STRING_OPTIONS
+    + SESSION_STYLE_OPTIONS
+    + WINDOW_INTEGER_OPTIONS
+    + WINDOW_BOOLEAN_OPTIONS
+    + WINDOW_CHOICE_OPTIONS
+    + WINDOW_STRING_OPTIONS
+    + WINDOW_STYLE_OPTIONS
+    + PANE_BOOLEAN_OPTIONS
+    + PANE_CHOICE_OPTIONS
+    + PANE_STYLE_OPTIONS
+)
+
+
+def _build_option_params() -> list[t.Any]:
+    """Build pytest params with appropriate marks."""
+    params = []
+    for tc in ALL_OPTION_TEST_CASES:
+        marks: list[t.Any] = []
+        if tc.xfail_reason:
+            marks.append(pytest.mark.xfail(reason=tc.xfail_reason))
+        params.append(pytest.param(tc, id=tc.test_id, marks=marks))
+    return params
+
+
+@pytest.mark.parametrize("test_case", _build_option_params())
+def test_option_set_show_cycle(server: Server, test_case: OptionTestCase) -> None:
+    """Test set/show cycle for each option type."""
+    if not has_gte_version("3.0"):
+        pytest.skip("Option tests require tmux 3.0+")
+
+    if test_case.min_version and not has_gte_version(test_case.min_version):
+        pytest.skip(f"Requires tmux {test_case.min_version}+")
+
+    # Get appropriate target object
+    session = server.new_session(session_name="test_option_cycle")
+    window = session.active_window
+    assert window is not None
+    pane = window.active_pane
+    assert pane is not None
+
+    targets = {
+        OptionScope.Server: server,
+        OptionScope.Session: session,
+        OptionScope.Window: window,
+        OptionScope.Pane: pane,
+    }
+    target = targets[test_case.scope]
+
+    # Test set
+    target.set_option(test_case.option, test_case.test_value)
+
+    # Test show
+    result = target.show_option(test_case.option)
+    assert result is not None, f"Expected {test_case.option} to be set, got None"
+    assert isinstance(result, test_case.expected_type), (
+        f"Expected {test_case.expected_type.__name__}, got {type(result).__name__}"
+    )

From 9cfafe5a54fe40f65d15223ac2f207f6974f1f01 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 11:54:11 -0600
Subject: [PATCH 048/136] tests(hooks): add comprehensive hook test grid

why: Ensure 100% API coverage for tmux hooks with proper set/show/unset validation
what:
- Add HookTestCase NamedTuple for parametrized testing
- Add 62 test cases covering all hook categories:
  - Alert hooks (3): activity, bell, silence
  - Client hooks (7): active, attached, detached, focus-in/out, resized, session-changed
  - Session hooks (3): created, closed, renamed
  - Window hooks (5): linked, renamed, resized, unlinked, session-window-changed
  - Pane hooks (6): died, exited, focus-in/out, mode-changed, set-clipboard
  - After-* hooks (38): all command completion hooks
- Add version-gated tests for tmux 3.5+ hooks (pane-title-changed, client-light/dark-theme)
---
 tests/test_hooks.py | 218 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 218 insertions(+)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 3cc750afe..dfa27c3e8 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -307,3 +307,221 @@ def test_hooks_mixin(
             0: "set-option -g status-left-style bg=red",
         },
     )
+
+
+# =============================================================================
+# Comprehensive Hook Test Grid
+# =============================================================================
+
+
+class HookTestCase(t.NamedTuple):
+    """Test case for hook validation."""
+
+    test_id: str
+    hook: str  # tmux hook name (hyphenated)
+    min_version: str = "3.0"  # Minimum tmux version required
+    xfail_reason: str | None = None  # Mark as expected failure with reason
+
+
+# --- Alert Hooks ---
+ALERT_HOOKS: list[HookTestCase] = [
+    HookTestCase("alert_activity", "alert-activity"),
+    HookTestCase("alert_bell", "alert-bell"),
+    HookTestCase("alert_silence", "alert-silence"),
+]
+
+# --- Client Hooks ---
+CLIENT_HOOKS: list[HookTestCase] = [
+    HookTestCase("client_active", "client-active"),
+    HookTestCase("client_attached", "client-attached"),
+    HookTestCase("client_detached", "client-detached"),
+    HookTestCase("client_focus_in", "client-focus-in"),
+    HookTestCase("client_focus_out", "client-focus-out"),
+    HookTestCase("client_resized", "client-resized"),
+    HookTestCase("client_session_changed", "client-session-changed"),
+]
+
+# --- Session Hooks ---
+SESSION_HOOKS: list[HookTestCase] = [
+    HookTestCase("session_created", "session-created"),
+    HookTestCase("session_closed", "session-closed"),
+    HookTestCase("session_renamed", "session-renamed"),
+]
+
+# --- Window Hooks ---
+WINDOW_HOOKS: list[HookTestCase] = [
+    HookTestCase("window_linked", "window-linked"),
+    HookTestCase("window_renamed", "window-renamed"),
+    HookTestCase("window_resized", "window-resized"),
+    HookTestCase("window_unlinked", "window-unlinked"),
+    HookTestCase("session_window_changed", "session-window-changed"),
+]
+
+# --- Pane Hooks ---
+PANE_HOOKS: list[HookTestCase] = [
+    HookTestCase("pane_died", "pane-died"),
+    HookTestCase("pane_exited", "pane-exited"),
+    HookTestCase("pane_focus_in", "pane-focus-in"),
+    HookTestCase("pane_focus_out", "pane-focus-out"),
+    HookTestCase("pane_mode_changed", "pane-mode-changed"),
+    HookTestCase("pane_set_clipboard", "pane-set-clipboard"),
+]
+
+# --- After-* Hooks ---
+AFTER_HOOKS: list[HookTestCase] = [
+    HookTestCase("after_bind_key", "after-bind-key"),
+    HookTestCase("after_capture_pane", "after-capture-pane"),
+    HookTestCase("after_copy_mode", "after-copy-mode"),
+    HookTestCase("after_display_message", "after-display-message"),
+    HookTestCase("after_display_panes", "after-display-panes"),
+    HookTestCase("after_kill_pane", "after-kill-pane"),
+    HookTestCase("after_list_buffers", "after-list-buffers"),
+    HookTestCase("after_list_clients", "after-list-clients"),
+    HookTestCase("after_list_keys", "after-list-keys"),
+    HookTestCase("after_list_panes", "after-list-panes"),
+    HookTestCase("after_list_sessions", "after-list-sessions"),
+    HookTestCase("after_list_windows", "after-list-windows"),
+    HookTestCase("after_load_buffer", "after-load-buffer"),
+    HookTestCase("after_lock_server", "after-lock-server"),
+    HookTestCase("after_new_session", "after-new-session"),
+    HookTestCase("after_new_window", "after-new-window"),
+    HookTestCase("after_paste_buffer", "after-paste-buffer"),
+    HookTestCase("after_pipe_pane", "after-pipe-pane"),
+    HookTestCase("after_queue", "after-queue"),
+    HookTestCase("after_refresh_client", "after-refresh-client"),
+    HookTestCase("after_rename_session", "after-rename-session"),
+    HookTestCase("after_rename_window", "after-rename-window"),
+    HookTestCase("after_resize_pane", "after-resize-pane"),
+    HookTestCase("after_resize_window", "after-resize-window"),
+    HookTestCase("after_save_buffer", "after-save-buffer"),
+    HookTestCase("after_select_layout", "after-select-layout"),
+    HookTestCase("after_select_pane", "after-select-pane"),
+    HookTestCase("after_select_window", "after-select-window"),
+    HookTestCase("after_send_keys", "after-send-keys"),
+    HookTestCase("after_set_buffer", "after-set-buffer"),
+    HookTestCase("after_set_environment", "after-set-environment"),
+    HookTestCase("after_set_hook", "after-set-hook"),
+    HookTestCase("after_set_option", "after-set-option"),
+    HookTestCase("after_show_environment", "after-show-environment"),
+    HookTestCase("after_show_messages", "after-show-messages"),
+    HookTestCase("after_show_options", "after-show-options"),
+    HookTestCase("after_split_window", "after-split-window"),
+    HookTestCase("after_unbind_key", "after-unbind-key"),
+]
+
+# --- New Hooks (tmux 3.5+) ---
+NEW_HOOKS: list[HookTestCase] = [
+    HookTestCase(
+        "pane_title_changed",
+        "pane-title-changed",
+        "3.5",
+        xfail_reason="pane-title-changed requires tmux 3.5+",
+    ),
+    HookTestCase(
+        "client_light_theme",
+        "client-light-theme",
+        "3.5",
+        xfail_reason="client-light-theme requires tmux 3.5+",
+    ),
+    HookTestCase(
+        "client_dark_theme",
+        "client-dark-theme",
+        "3.5",
+        xfail_reason="client-dark-theme requires tmux 3.5+",
+    ),
+]
+
+# Combine all hook test cases
+ALL_HOOK_TEST_CASES: list[HookTestCase] = (
+    ALERT_HOOKS + CLIENT_HOOKS + SESSION_HOOKS + WINDOW_HOOKS + PANE_HOOKS + AFTER_HOOKS
+)
+
+
+def _build_hook_params() -> list[t.Any]:
+    """Build pytest params with appropriate marks."""
+    params = []
+    for tc in ALL_HOOK_TEST_CASES:
+        marks: list[t.Any] = []
+        if tc.xfail_reason:
+            marks.append(pytest.mark.xfail(reason=tc.xfail_reason))
+        params.append(pytest.param(tc, id=tc.test_id, marks=marks))
+    return params
+
+
+@pytest.mark.parametrize("test_case", _build_hook_params())
+def test_hook_set_show_unset_cycle(server: Server, test_case: HookTestCase) -> None:
+    """Test set/show/unset cycle for each hook.
+
+    This parametrized test ensures all hooks in the libtmux constants can be:
+    1. Set with a command
+    2. Shown and verified
+    3. Unset cleanly
+    """
+    if not has_gte_version(test_case.min_version):
+        pytest.skip(f"Requires tmux {test_case.min_version}+")
+
+    session = server.new_session(session_name="test_hook_cycle")
+    window = session.active_window
+    assert window is not None
+    pane = window.active_pane
+    assert pane is not None
+
+    hook_cmd = "display-message 'test hook fired'"
+
+    # Test set_hook (using session-level hook which works on all tmux versions)
+    session.set_hook(f"{test_case.hook}[0]", hook_cmd)
+
+    # Test show_hook
+    result = session._show_hook(f"{test_case.hook}[0]")
+    assert result is not None, f"Expected hook {test_case.hook} to be set"
+
+    # Parse and verify
+    hooks = Hooks.from_stdout(result)
+    hook_attr = test_case.hook.replace("-", "_")
+    hook_value = getattr(hooks, hook_attr, None)
+    assert hook_value is not None, f"Hook attribute {hook_attr} not found in Hooks"
+    assert len(hook_value) > 0, f"Expected hook {test_case.hook} to have values"
+    assert "display-message" in hook_value[0], (
+        f"Expected 'display-message' in hook value, got: {hook_value[0]}"
+    )
+
+    # Test unset_hook
+    session.unset_hook(f"{test_case.hook}[0]")
+
+    # Verify unset
+    result_after_unset = session._show_hook(f"{test_case.hook}[0]")
+    if result_after_unset:
+        hooks_after = Hooks.from_stdout(result_after_unset)
+        hook_value_after = getattr(hooks_after, hook_attr, None)
+        # After unset, the hook should be empty or have empty value
+        if hook_value_after:
+            assert len(hook_value_after.as_list()) == 0 or hook_value_after[0] == "", (
+                f"Expected hook {test_case.hook} to be unset"
+            )
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in NEW_HOOKS],
+)
+def test_new_hooks_version_gated(server: Server, test_case: HookTestCase) -> None:
+    """Test new hooks that require tmux 3.5+.
+
+    These hooks are version-gated and will skip on older tmux versions.
+    """
+    if not has_gte_version(test_case.min_version):
+        pytest.skip(f"Requires tmux {test_case.min_version}+")
+
+    session = server.new_session(session_name="test_new_hooks")
+
+    hook_cmd = "display-message 'new hook fired'"
+
+    # Test set_hook
+    session.set_hook(f"{test_case.hook}[0]", hook_cmd)
+
+    # Test show_hook
+    result = session._show_hook(f"{test_case.hook}[0]")
+    assert result is not None, f"Expected hook {test_case.hook} to be set"
+
+    # Cleanup
+    session.unset_hook(f"{test_case.hook}[0]")

From e8e91909c50b261050d10b643a9a42f1e0a61e1f Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 13:13:37 -0600
Subject: [PATCH 049/136] SparseArray(docs): add comprehensive doctests

why: Document sparse array behavior for hooks and options handling
what:
- Add class-level doctests showing non-sequential index support
- Add doctests to add(), append(), iter_values(), as_list() methods
- Demonstrate dict-style access, index checking, sorted iteration
---
 src/libtmux/_internal/sparse_array.py | 129 ++++++++++++++++++++++++++
 1 file changed, 129 insertions(+)

diff --git a/src/libtmux/_internal/sparse_array.py b/src/libtmux/_internal/sparse_array.py
index c5c8bedff..8b1ac54fe 100644
--- a/src/libtmux/_internal/sparse_array.py
+++ b/src/libtmux/_internal/sparse_array.py
@@ -39,18 +39,147 @@ class SparseArray(dict[int, T], t.Generic[T]):
 
     :class:`list` would lose indice info, and :class:`dict` would lose list-like
     behavior.
+
+    Examples
+    --------
+    Create a sparse array and add values at non-sequential indices:
+
+    >>> from libtmux._internal.sparse_array import SparseArray
+
+    >>> arr: SparseArray[str] = SparseArray()
+    >>> arr.add(0, "first hook command")
+    >>> arr.add(5, "fifth hook command")
+    >>> arr.add(2, "second hook command")
+
+    Access values by index (dict-style):
+
+    >>> arr[0]
+    'first hook command'
+    >>> arr[5]
+    'fifth hook command'
+
+    Check index existence:
+
+    >>> 0 in arr
+    True
+    >>> 3 in arr
+    False
+
+    Iterate values in sorted index order:
+
+    >>> list(arr.iter_values())
+    ['first hook command', 'second hook command', 'fifth hook command']
+
+    Convert to a list (values only, sorted by index):
+
+    >>> arr.as_list()
+    ['first hook command', 'second hook command', 'fifth hook command']
+
+    Append adds at max index + 1:
+
+    >>> arr.append("appended command")
+    >>> arr[6]
+    'appended command'
+
+    Access raw indices:
+
+    >>> sorted(arr.keys())
+    [0, 2, 5, 6]
     """
 
     def add(self, index: int, value: T) -> None:
+        """Add a value at a specific index.
+
+        Parameters
+        ----------
+        index : int
+            The index at which to store the value.
+        value : T
+            The value to store.
+
+        Examples
+        --------
+        >>> from libtmux._internal.sparse_array import SparseArray
+
+        >>> arr: SparseArray[str] = SparseArray()
+        >>> arr.add(0, "hook at index 0")
+        >>> arr.add(10, "hook at index 10")
+        >>> arr[0]
+        'hook at index 0'
+        >>> arr[10]
+        'hook at index 10'
+        >>> sorted(arr.keys())
+        [0, 10]
+        """
         self[index] = value
 
     def append(self, value: T) -> None:
+        """Append a value at the next available index (max + 1).
+
+        Parameters
+        ----------
+        value : T
+            The value to append.
+
+        Examples
+        --------
+        >>> from libtmux._internal.sparse_array import SparseArray
+
+        >>> arr: SparseArray[str] = SparseArray()
+        >>> arr.add(0, "first")
+        >>> arr.add(5, "at index 5")
+        >>> arr.append("appended")
+        >>> arr[6]
+        'appended'
+        >>> arr.append("another")
+        >>> arr[7]
+        'another'
+        """
         index = max(self.keys()) + 1
         self[index] = value
 
     def iter_values(self) -> t.Iterator[T]:
+        """Iterate over values in sorted index order.
+
+        Yields
+        ------
+        T
+            Values in ascending index order.
+
+        Examples
+        --------
+        >>> from libtmux._internal.sparse_array import SparseArray
+
+        >>> arr: SparseArray[str] = SparseArray()
+        >>> arr.add(5, "fifth")
+        >>> arr.add(0, "first")
+        >>> arr.add(2, "second")
+        >>> for val in arr.iter_values():
+        ...     print(val)
+        first
+        second
+        fifth
+        """
         for index in sorted(self.keys()):
             yield self[index]
 
     def as_list(self) -> list[T]:
+        """Return values as a list in sorted index order.
+
+        Returns
+        -------
+        list[T]
+            List of values sorted by their indices.
+
+        Examples
+        --------
+        >>> from libtmux._internal.sparse_array import SparseArray
+
+        >>> arr: SparseArray[str] = SparseArray()
+        >>> arr.add(10, "tenth")
+        >>> arr.add(0, "zeroth")
+        >>> arr.add(5, "fifth")
+        >>> arr.as_list()
+        ['zeroth', 'fifth', 'tenth']
+        """
         return [self[index] for index in sorted(self.keys())]

From 4b2feb2e442d7edb7f5ed3230bc35cf91bbadb1f Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 13:13:42 -0600
Subject: [PATCH 050/136] Hooks(docs): add doctests for from_stdout parsing
 pipeline

why: Document full pipeline from raw tmux output to typed Hooks dataclass
what:
- Add class-level doctests showing hook parsing and access patterns
- Add from_stdout() doctests with parameter docs and examples
- Demonstrate sparse index preservation and multiple hook types
---
 src/libtmux/_internal/constants.py | 114 ++++++++++++++++++++++++++++-
 1 file changed, 113 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/_internal/constants.py b/src/libtmux/_internal/constants.py
index 8c25af5ba..99693c958 100644
--- a/src/libtmux/_internal/constants.py
+++ b/src/libtmux/_internal/constants.py
@@ -252,7 +252,71 @@ def __init__(self, **kwargs: object) -> None:
 class Hooks(
     SkipDefaultFieldsReprMixin,
 ):
-    """tmux hooks data structure."""
+    """tmux hooks data structure.
+
+    Parses tmux hook output into typed :class:`SparseArray` fields, preserving
+    array indices for hooks that can have multiple commands at different indices.
+
+    Examples
+    --------
+    Parse raw tmux hook output:
+
+    >>> from libtmux._internal.constants import Hooks
+
+    >>> raw = [
+    ...     "session-renamed[0] set-option -g status-left-style bg=red",
+    ...     "session-renamed[1] display-message 'session renamed'",
+    ... ]
+    >>> hooks = Hooks.from_stdout(raw)
+
+    Access individual hook commands by index:
+
+    >>> hooks.session_renamed[0]
+    'set-option -g status-left-style bg=red'
+    >>> hooks.session_renamed[1]
+    "display-message 'session renamed'"
+
+    Get all commands as a list (sorted by index):
+
+    >>> hooks.session_renamed.as_list()
+    ['set-option -g status-left-style bg=red', "display-message 'session renamed'"]
+
+    Sparse indices are preserved (gaps in index numbers):
+
+    >>> raw_sparse = [
+    ...     "pane-focus-in[0] refresh-client",
+    ...     "pane-focus-in[5] display-message 'focus'",
+    ... ]
+    >>> hooks_sparse = Hooks.from_stdout(raw_sparse)
+    >>> 0 in hooks_sparse.pane_focus_in
+    True
+    >>> 5 in hooks_sparse.pane_focus_in
+    True
+    >>> 3 in hooks_sparse.pane_focus_in
+    False
+    >>> sorted(hooks_sparse.pane_focus_in.keys())
+    [0, 5]
+
+    Iterate over values in index order:
+
+    >>> for cmd in hooks_sparse.pane_focus_in.iter_values():
+    ...     print(cmd)
+    refresh-client
+    display-message 'focus'
+
+    Multiple hook types in one parse:
+
+    >>> raw_multi = [
+    ...     "after-new-window[0] select-pane -t 0",
+    ...     "after-new-window[1] send-keys 'clear' Enter",
+    ...     "window-renamed[0] refresh-client -S",
+    ... ]
+    >>> hooks_multi = Hooks.from_stdout(raw_multi)
+    >>> len(hooks_multi.after_new_window)
+    2
+    >>> len(hooks_multi.window_renamed)
+    1
+    """
 
     # --- Tmux normal hooks ---
     # Run when a window has activity. See monitor-activity.
@@ -453,6 +517,54 @@ class Hooks(
 
     @classmethod
     def from_stdout(cls, value: list[str]) -> Hooks:
+        """Parse raw tmux hook output into a Hooks instance.
+
+        The parsing pipeline:
+
+        1. ``parse_options_to_dict()`` - Parse "key value" lines into dict
+        2. ``explode_arrays(force_array=True)`` - Extract array indices into SparseArray
+        3. ``explode_complex()`` - Handle complex option types
+        4. Rename keys: ``session-renamed`` → ``session_renamed``
+
+        Parameters
+        ----------
+        value : list[str]
+            Raw tmux output lines from ``show-hooks`` command.
+
+        Returns
+        -------
+        Hooks
+            Parsed hooks with SparseArray fields for each hook type.
+
+        Examples
+        --------
+        Basic parsing:
+
+        >>> from libtmux._internal.constants import Hooks
+
+        >>> raw = ["session-renamed[0] display-message 'renamed'"]
+        >>> hooks = Hooks.from_stdout(raw)
+        >>> hooks.session_renamed[0]
+        "display-message 'renamed'"
+
+        The pipeline preserves sparse indices:
+
+        >>> raw = [
+        ...     "after-select-window[0] refresh-client",
+        ...     "after-select-window[10] display-message 'selected'",
+        ... ]
+        >>> hooks = Hooks.from_stdout(raw)
+        >>> sorted(hooks.after_select_window.keys())
+        [0, 10]
+
+        Empty input returns empty SparseArrays:
+
+        >>> hooks_empty = Hooks.from_stdout([])
+        >>> len(hooks_empty.session_renamed)
+        0
+        >>> hooks_empty.session_renamed.as_list()
+        []
+        """
         from libtmux.options import (
             explode_arrays,
             explode_complex,

From 423d3b50c2db4f9039f402be451a947dfde1b6d1 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 13:13:49 -0600
Subject: [PATCH 051/136] options(docs): add force_array=True doctest for hooks
 parsing

why: Document hook-style usage of explode_arrays with SparseArray output
what:
- Add doctest example showing force_array=True for hooks output
- Demonstrate SparseArray type and index preservation
---
 src/libtmux/options.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index 346091bbe..5d0441fc9 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -369,6 +369,31 @@ def explode_arrays(
     ... "terminal-features": {0: "xterm*:clipboard:ccolour:cstyle:focus",
     ... 5: "screen*:title"}}
     True
+
+    Use ``force_array=True`` for hooks, which always use array format:
+
+    >>> from libtmux._internal.sparse_array import SparseArray
+
+    >>> hooks_output = io.StringIO(r'''
+    ... session-renamed[0] display-message 'renamed'
+    ... session-renamed[5] refresh-client
+    ... pane-focus-in[0] run-shell 'echo focus'
+    ... ''')
+    >>> hooks_exploded = explode_arrays(
+    ...     parse_options_to_dict(hooks_output),
+    ...     force_array=True,
+    ... )
+
+    Each hook becomes a SparseArray preserving indices:
+
+    >>> isinstance(hooks_exploded["session-renamed"], SparseArray)
+    True
+    >>> hooks_exploded["session-renamed"][0]
+    "display-message 'renamed'"
+    >>> hooks_exploded["session-renamed"][5]
+    'refresh-client'
+    >>> sorted(hooks_exploded["session-renamed"].keys())
+    [0, 5]
     """
     options: dict[str, t.Any] = {}
     for key, val in _dict.items():

From b9cd2f16b77b6156e5f82b0ad6352819073ca48d Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 13:13:57 -0600
Subject: [PATCH 052/136] hooks(feat): add bulk operations API for managing
 indexed hooks

why: Enable easier management of multiple indexed hooks at once
what:
- Add get_hook_indices() to get sorted list of existing indices
- Add get_hook_values() to get all values as SparseArray
- Add set_hooks_bulk() to set multiple hooks from dict/list/SparseArray
- Add clear_hook() to unset all indexed values for a hook
- Add append_hook() to append at next available index
- Add module docstring with version compatibility notes (3.0-3.5+)
- All methods support method chaining via Self return type
---
 src/libtmux/hooks.py | 288 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 287 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 3d8e1a7db..2312fddc1 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -1,4 +1,38 @@
-"""Helpers for tmux hooks."""
+"""Helpers for tmux hooks.
+
+tmux Hook Version Compatibility
+-------------------------------
+Hook array support requires tmux 3.0+.
+
+**tmux 3.0+**:
+- Hooks are array options (e.g., ``session-renamed[0]``, ``session-renamed[1]``)
+- Sparse indices supported (can have gaps: ``[0]``, ``[5]``, ``[10]``)
+- Session-level hooks available
+
+**tmux 3.2+**:
+- Window-level hooks via ``-w`` flag
+- Pane-level hooks via ``-p`` flag
+- Hook scope separation (session vs window vs pane)
+
+**tmux 3.3+**:
+- ``client-active`` hook
+- ``window-resized`` hook
+
+**tmux 3.5+**:
+- ``pane-title-changed`` hook
+- ``client-light-theme`` / ``client-dark-theme`` hooks
+- ``command-error`` hook
+
+Bulk Operations API
+-------------------
+This module provides bulk operations for managing multiple indexed hooks:
+
+- :meth:`~HooksMixin.get_hook_indices` - Get list of existing indices for a hook
+- :meth:`~HooksMixin.get_hook_values` - Get all values as SparseArray
+- :meth:`~HooksMixin.set_hooks_bulk` - Set multiple hooks at once
+- :meth:`~HooksMixin.clear_hook` - Unset all indexed values for a hook
+- :meth:`~HooksMixin.append_hook` - Append at next available index
+"""
 
 from __future__ import annotations
 
@@ -10,6 +44,7 @@
 from libtmux._internal.constants import (
     Hooks,
 )
+from libtmux._internal.sparse_array import SparseArray
 from libtmux.common import CmdMixin, has_lt_version
 from libtmux.constants import (
     DEFAULT_OPTION_SCOPE,
@@ -23,6 +58,7 @@
     from typing_extensions import Self
 
 HookDict = dict[str, t.Any]
+HookValues = dict[int, str] | SparseArray[str] | list[str]
 
 logger = logging.getLogger(__name__)
 
@@ -344,3 +380,253 @@ def show_hook(
             return None
         hooks = Hooks.from_stdout(hooks_output)
         return getattr(hooks, hook.replace("-", "_"), None)
+
+    # --- Bulk operations API ---
+
+    def get_hook_indices(
+        self,
+        hook: str,
+        global_: bool = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+    ) -> list[int]:
+        """Get list of indices that exist for a hook.
+
+        Parameters
+        ----------
+        hook : str
+            Hook name, e.g. 'session-renamed'
+        global_ : bool
+            Use global hooks
+        scope : OptionScope | None
+            Scope for the hook
+        ignore_errors : bool | None
+            Suppress errors
+
+        Returns
+        -------
+        list[int]
+            Sorted list of indices that exist for this hook.
+
+        Examples
+        --------
+        >>> # After setting hooks at indices 0, 1, 5:
+        >>> # session.get_hook_indices('session-renamed')
+        >>> # [0, 1, 5]
+        """
+        hooks_output = self._show_hook(
+            hook=hook,
+            global_=global_,
+            scope=scope,
+            ignore_errors=ignore_errors,
+        )
+        if hooks_output is None:
+            return []
+        hooks = Hooks.from_stdout(hooks_output)
+        hook_array = getattr(hooks, hook.replace("-", "_"), None)
+        if hook_array is None or not isinstance(hook_array, SparseArray):
+            return []
+        return sorted(hook_array.keys())
+
+    def get_hook_values(
+        self,
+        hook: str,
+        global_: bool = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+    ) -> SparseArray[str]:
+        """Get all indexed values for a hook as SparseArray.
+
+        Parameters
+        ----------
+        hook : str
+            Hook name, e.g. 'session-renamed'
+        global_ : bool
+            Use global hooks
+        scope : OptionScope | None
+            Scope for the hook
+        ignore_errors : bool | None
+            Suppress errors
+
+        Returns
+        -------
+        SparseArray[str]
+            SparseArray containing hook values at their original indices.
+
+        Examples
+        --------
+        >>> # values = session.get_hook_values('session-renamed')
+        >>> # for val in values.iter_values():
+        >>> #     print(val)
+        """
+        hooks_output = self._show_hook(
+            hook=hook,
+            global_=global_,
+            scope=scope,
+            ignore_errors=ignore_errors,
+        )
+        if hooks_output is None:
+            return SparseArray()
+        hooks = Hooks.from_stdout(hooks_output)
+        hook_array = getattr(hooks, hook.replace("-", "_"), None)
+        if hook_array is None or not isinstance(hook_array, SparseArray):
+            return SparseArray()
+        # Type narrowing doesn't work with isinstance for generics, so cast
+        result: SparseArray[str] = hook_array
+        return result
+
+    def set_hooks_bulk(
+        self,
+        hook: str,
+        values: HookValues,
+        *,
+        clear_existing: bool = False,
+        global_: bool | None = None,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+    ) -> Self:
+        """Set multiple indexed hooks at once.
+
+        Parameters
+        ----------
+        hook : str
+            Hook name, e.g. 'session-renamed'
+        values : HookValues
+            Values to set. Can be:
+            - dict[int, str]: {0: 'cmd1', 1: 'cmd2'} - explicit indices
+            - SparseArray[str]: preserves indices from another hook
+            - list[str]: ['cmd1', 'cmd2'] - sequential indices starting at 0
+        clear_existing : bool
+            If True, unset all existing hook values first
+        global_ : bool | None
+            Use global hooks
+        scope : OptionScope | None
+            Scope for the hook
+
+        Returns
+        -------
+        Self
+            Returns self for method chaining.
+
+        Examples
+        --------
+        Set hooks with explicit indices:
+
+        >>> # session.set_hooks_bulk('session-renamed', {
+        >>> #     0: 'display-message "hook 0"',
+        >>> #     1: 'display-message "hook 1"',
+        >>> # })
+
+        Set hooks from a list (sequential indices):
+
+        >>> # session.set_hooks_bulk('after-new-window', [
+        >>> #     'select-pane -t 0',
+        >>> #     'send-keys "clear" Enter',
+        >>> # ])
+
+        Replace all existing hooks:
+
+        >>> # session.set_hooks_bulk('session-renamed', [...], clear_existing=True)
+        """
+        if clear_existing:
+            self.clear_hook(hook, global_=global_, scope=scope)
+
+        # Convert list to dict with sequential indices
+        if isinstance(values, list):
+            values = dict(enumerate(values))
+
+        for index, value in values.items():
+            self.set_hook(
+                f"{hook}[{index}]",
+                value,
+                global_=global_,
+                scope=scope,
+            )
+
+        return self
+
+    def clear_hook(
+        self,
+        hook: str,
+        global_: bool | None = None,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        ignore_errors: bool | None = None,
+    ) -> Self:
+        """Unset all indexed values for a hook.
+
+        Parameters
+        ----------
+        hook : str
+            Hook name, e.g. 'session-renamed'
+        global_ : bool | None
+            Use global hooks
+        scope : OptionScope | None
+            Scope for the hook
+        ignore_errors : bool | None
+            Suppress errors when unsetting
+
+        Returns
+        -------
+        Self
+            Returns self for method chaining.
+
+        Examples
+        --------
+        >>> # session.clear_hook('session-renamed')
+        """
+        indices = self.get_hook_indices(
+            hook,
+            global_=global_ if global_ is not None else False,
+            scope=scope,
+            ignore_errors=ignore_errors,
+        )
+        for index in indices:
+            self.unset_hook(
+                f"{hook}[{index}]",
+                global_=global_,
+                scope=scope,
+                ignore_errors=ignore_errors,
+            )
+        return self
+
+    def append_hook(
+        self,
+        hook: str,
+        value: str,
+        global_: bool | None = None,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+    ) -> Self:
+        """Append a hook value at the next available index.
+
+        Parameters
+        ----------
+        hook : str
+            Hook name, e.g. 'session-renamed'
+        value : str
+            Hook command to append
+        global_ : bool | None
+            Use global hooks
+        scope : OptionScope | None
+            Scope for the hook
+
+        Returns
+        -------
+        Self
+            Returns self for method chaining.
+
+        Examples
+        --------
+        >>> # session.append_hook('session-renamed', 'display-message "appended"')
+        """
+        indices = self.get_hook_indices(
+            hook,
+            global_=global_ if global_ is not None else False,
+            scope=scope,
+        )
+        next_index = max(indices) + 1 if indices else 0
+        self.set_hook(
+            f"{hook}[{next_index}]",
+            value,
+            global_=global_,
+            scope=scope,
+        )
+        return self

From 69eca19e3f9929dc800fa6d29d9fab7dca244052 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 13:27:11 -0600
Subject: [PATCH 053/136] tests(hooks): add comprehensive bulk operations test
 grid

why: Ensure bulk operations API works correctly with parametrized tests
what:
- Add BulkOpTestCase NamedTuple with test_id, operation, setup, expected
- Add categorized test cases: GET_INDICES, GET_VALUES, SET_BULK, CLEAR, APPEND
- Create parametrized test_bulk_hook_operation() for 12 data-driven tests
- Add standalone tests for iteration, SparseArray input, method chaining
---
 tests/test_hooks.py | 290 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 290 insertions(+)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index dfa27c3e8..3512ee51b 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -525,3 +525,293 @@ def test_new_hooks_version_gated(server: Server, test_case: HookTestCase) -> Non
 
     # Cleanup
     session.unset_hook(f"{test_case.hook}[0]")
+
+
+# =============================================================================
+# Bulk Operations API Tests
+# =============================================================================
+
+
+class BulkOpTestCase(t.NamedTuple):
+    """Test case for bulk hook operations."""
+
+    test_id: str
+    operation: str  # "get_indices", "get_values", "set_bulk", "clear", "append"
+    hook: str  # Hook name to test
+    setup_hooks: dict[int, str]  # Initial hooks to set (index -> value)
+    operation_args: dict[str, t.Any]  # Args for operation
+    expected_indices: list[int]  # Expected indices after operation
+    expected_contains: list[str] | None = None  # Strings expected in values
+
+
+# --- get_hook_indices tests ---
+GET_INDICES_TESTS: list[BulkOpTestCase] = [
+    BulkOpTestCase(
+        "get_indices_empty",
+        "get_indices",
+        "session-renamed",
+        {},
+        {},
+        [],
+    ),
+    BulkOpTestCase(
+        "get_indices_sequential",
+        "get_indices",
+        "session-renamed",
+        {
+            0: "display-message 'hook 0'",
+            1: "display-message 'hook 1'",
+            2: "display-message 'hook 2'",
+        },
+        {},
+        [0, 1, 2],
+    ),
+    BulkOpTestCase(
+        "get_indices_sparse",
+        "get_indices",
+        "session-renamed",
+        {
+            0: "display-message 'hook 0'",
+            5: "display-message 'hook 5'",
+            10: "display-message 'hook 10'",
+        },
+        {},
+        [0, 5, 10],
+    ),
+]
+
+# --- get_hook_values tests ---
+GET_VALUES_TESTS: list[BulkOpTestCase] = [
+    BulkOpTestCase(
+        "get_values_empty",
+        "get_values",
+        "session-renamed",
+        {},
+        {},
+        [],
+    ),
+    BulkOpTestCase(
+        "get_values_sparse",
+        "get_values",
+        "session-renamed",
+        {0: "display-message 'hook 0'", 5: "display-message 'hook 5'"},
+        {},
+        [0, 5],
+        ["display-message"],
+    ),
+]
+
+# --- set_hooks_bulk tests ---
+SET_BULK_TESTS: list[BulkOpTestCase] = [
+    BulkOpTestCase(
+        "set_bulk_with_dict",
+        "set_bulk",
+        "session-renamed",
+        {},
+        {
+            "values": {
+                0: "display-message 'hook 0'",
+                1: "display-message 'hook 1'",
+                5: "display-message 'hook 5'",
+            },
+        },
+        [0, 1, 5],
+        ["hook 0", "hook 1", "hook 5"],
+    ),
+    BulkOpTestCase(
+        "set_bulk_with_list",
+        "set_bulk",
+        "session-renamed",
+        {},
+        {
+            "values": [
+                "display-message 'hook 0'",
+                "display-message 'hook 1'",
+                "display-message 'hook 2'",
+            ],
+        },
+        [0, 1, 2],
+    ),
+    BulkOpTestCase(
+        "set_bulk_clear_existing",
+        "set_bulk",
+        "session-renamed",
+        {0: "display-message 'old 0'", 1: "display-message 'old 1'"},
+        {"values": {0: "display-message 'new 0'"}, "clear_existing": True},
+        [0],
+        ["new 0"],
+    ),
+]
+
+# --- clear_hook tests ---
+CLEAR_TESTS: list[BulkOpTestCase] = [
+    BulkOpTestCase(
+        "clear_hook",
+        "clear",
+        "session-renamed",
+        {0: "display-message 'hook 0'", 5: "display-message 'hook 5'"},
+        {},
+        [],
+    ),
+]
+
+# --- append_hook tests ---
+APPEND_TESTS: list[BulkOpTestCase] = [
+    BulkOpTestCase(
+        "append_to_empty",
+        "append",
+        "session-renamed",
+        {},
+        {"value": "display-message 'appended'"},
+        [0],
+        ["appended"],
+    ),
+    BulkOpTestCase(
+        "append_sequential",
+        "append",
+        "session-renamed",
+        {0: "display-message 'initial'"},
+        {"value": "display-message 'appended'"},
+        [0, 1],
+    ),
+    BulkOpTestCase(
+        "append_after_sparse",
+        "append",
+        "session-renamed",
+        {0: "display-message 'at 0'", 10: "display-message 'at 10'"},
+        {"value": "display-message 'appended'"},
+        [0, 10, 11],
+        ["appended"],
+    ),
+]
+
+# Combine all bulk operation test cases
+ALL_BULK_OP_TESTS: list[BulkOpTestCase] = (
+    GET_INDICES_TESTS + GET_VALUES_TESTS + SET_BULK_TESTS + CLEAR_TESTS + APPEND_TESTS
+)
+
+
+def _build_bulk_op_params() -> list[t.Any]:
+    """Build pytest params for bulk operation tests."""
+    return [pytest.param(tc, id=tc.test_id) for tc in ALL_BULK_OP_TESTS]
+
+
+@pytest.mark.parametrize("test_case", _build_bulk_op_params())
+def test_bulk_hook_operation(server: Server, test_case: BulkOpTestCase) -> None:
+    """Test bulk hook operations.
+
+    This parametrized test ensures all bulk operations work correctly:
+    - get_hook_indices: returns sorted list of existing indices
+    - get_hook_values: returns SparseArray with values
+    - set_hooks_bulk: sets multiple hooks at once
+    - clear_hook: removes all indexed values
+    - append_hook: appends at next available index
+    """
+    session = server.new_session(session_name="test_bulk_ops")
+
+    # Setup initial hooks
+    for idx, val in test_case.setup_hooks.items():
+        session.set_hook(f"{test_case.hook}[{idx}]", val)
+
+    # Perform operation based on type
+    if test_case.operation == "get_indices":
+        result = session.get_hook_indices(test_case.hook)
+        assert result == test_case.expected_indices
+
+    elif test_case.operation == "get_values":
+        values = session.get_hook_values(test_case.hook)
+        assert isinstance(values, SparseArray)
+        assert sorted(values.keys()) == test_case.expected_indices
+        if test_case.expected_contains:
+            for expected_str in test_case.expected_contains:
+                assert any(expected_str in v for v in values.values())
+
+    elif test_case.operation == "set_bulk":
+        session.set_hooks_bulk(test_case.hook, **test_case.operation_args)
+        indices = session.get_hook_indices(test_case.hook)
+        assert indices == test_case.expected_indices
+        if test_case.expected_contains:
+            values = session.get_hook_values(test_case.hook)
+            for expected_str in test_case.expected_contains:
+                assert any(expected_str in v for v in values.values())
+
+    elif test_case.operation == "clear":
+        session.clear_hook(test_case.hook)
+        indices = session.get_hook_indices(test_case.hook)
+        assert indices == test_case.expected_indices
+
+    elif test_case.operation == "append":
+        session.append_hook(test_case.hook, test_case.operation_args["value"])
+        indices = session.get_hook_indices(test_case.hook)
+        assert indices == test_case.expected_indices
+        if test_case.expected_contains:
+            values = session.get_hook_values(test_case.hook)
+            for expected_str in test_case.expected_contains:
+                assert any(expected_str in v for v in values.values())
+
+    # Cleanup
+    session.clear_hook(test_case.hook)
+
+
+def test_bulk_hook_values_iteration(server: Server) -> None:
+    """Test iterating over hook values in sorted order."""
+    session = server.new_session(session_name="test_bulk_ops")
+
+    # Set hooks at sparse indices (out of order)
+    session.set_hook("session-renamed[5]", "display-message 'fifth'")
+    session.set_hook("session-renamed[0]", "display-message 'zeroth'")
+    session.set_hook("session-renamed[2]", "display-message 'second'")
+
+    values = session.get_hook_values("session-renamed")
+    value_list = list(values.iter_values())
+
+    # Values should be in sorted index order
+    assert len(value_list) == 3
+    assert "zeroth" in value_list[0]
+    assert "second" in value_list[1]
+    assert "fifth" in value_list[2]
+
+    # Cleanup
+    session.clear_hook("session-renamed")
+
+
+def test_bulk_hook_set_with_sparse_array(server: Server) -> None:
+    """Test set_hooks_bulk with SparseArray input."""
+    session = server.new_session(session_name="test_bulk_ops")
+
+    sparse: SparseArray[str] = SparseArray()
+    sparse.add(0, "display-message 'from sparse 0'")
+    sparse.add(10, "display-message 'from sparse 10'")
+
+    session.set_hooks_bulk("session-renamed", sparse)
+
+    indices = session.get_hook_indices("session-renamed")
+    assert indices == [0, 10]
+
+    # Cleanup
+    session.clear_hook("session-renamed")
+
+
+def test_bulk_hook_method_chaining(server: Server) -> None:
+    """Test that bulk operations support method chaining."""
+    session = server.new_session(session_name="test_bulk_ops")
+
+    # Chain operations
+    result = (
+        session.set_hooks_bulk(
+            "session-renamed",
+            ["display-message 'hook 0'"],
+        )
+        .append_hook("session-renamed", "display-message 'hook 1'")
+        .append_hook("session-renamed", "display-message 'hook 2'")
+    )
+
+    # Should return the session
+    assert result is session
+
+    # Verify all hooks set
+    indices = session.get_hook_indices("session-renamed")
+    assert indices == [0, 1, 2]
+
+    # Cleanup
+    session.clear_hook("session-renamed")

From 62d39a308e242ab33f5f922a992455cffcd5e637 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 13:38:42 -0600
Subject: [PATCH 054/136] fix(tests): set correct min_version for hooks and
 options

why: CI fails on tmux 3.0a because some hooks/options don't exist in that version
what:
- client-focus-in, client-focus-out, client-active: require tmux 3.3+
- window-resized: requires tmux 3.3+
- editor option: requires tmux 3.2+
- prompt-history-limit option: requires tmux 3.3+
---
 tests/test_hooks.py   | 8 ++++----
 tests/test_options.py | 3 ++-
 2 files changed, 6 insertions(+), 5 deletions(-)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 3512ee51b..d083ea5a9 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -332,11 +332,11 @@ class HookTestCase(t.NamedTuple):
 
 # --- Client Hooks ---
 CLIENT_HOOKS: list[HookTestCase] = [
-    HookTestCase("client_active", "client-active"),
+    HookTestCase("client_active", "client-active", "3.3"),
     HookTestCase("client_attached", "client-attached"),
     HookTestCase("client_detached", "client-detached"),
-    HookTestCase("client_focus_in", "client-focus-in"),
-    HookTestCase("client_focus_out", "client-focus-out"),
+    HookTestCase("client_focus_in", "client-focus-in", "3.3"),
+    HookTestCase("client_focus_out", "client-focus-out", "3.3"),
     HookTestCase("client_resized", "client-resized"),
     HookTestCase("client_session_changed", "client-session-changed"),
 ]
@@ -352,7 +352,7 @@ class HookTestCase(t.NamedTuple):
 WINDOW_HOOKS: list[HookTestCase] = [
     HookTestCase("window_linked", "window-linked"),
     HookTestCase("window_renamed", "window-renamed"),
-    HookTestCase("window_resized", "window-resized"),
+    HookTestCase("window_resized", "window-resized", "3.3"),
     HookTestCase("window_unlinked", "window-unlinked"),
     HookTestCase("session_window_changed", "session-window-changed"),
 ]
diff --git a/tests/test_options.py b/tests/test_options.py
index a45007da2..f68eeb1e6 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -728,6 +728,7 @@ class OptionTestCase(t.NamedTuple):
         OptionScope.Server,
         50,
         int,
+        "3.3",
     ),
 ]
 
@@ -765,7 +766,7 @@ class OptionTestCase(t.NamedTuple):
         "screen-256color",
         str,
     ),
-    OptionTestCase("server_editor", "editor", OptionScope.Server, "vim", str),
+    OptionTestCase("server_editor", "editor", OptionScope.Server, "vim", str, "3.2"),
 ]
 
 # --- Session Options ---

From 7b136b0d2b45426e54644f906e2943e6dad523a4 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 14:24:23 -0600
Subject: [PATCH 055/136] fix(tests): correct min_version for additional hooks
 and options

why: CI fails on tmux 3.2a, 3.3a, and 3.5 due to incorrect version requirements
what:
- scroll-on-clear: change min_version from 3.2 to 3.3 (added in 3.3)
- allow-passthrough "all" value: change min_version from 3.3 to 3.4 (added in 3.4)
- Remove client-light-theme and client-dark-theme tests (not released yet, will be in 3.6+)
---
 tests/test_hooks.py   | 14 ++------------
 tests/test_options.py |  4 ++--
 2 files changed, 4 insertions(+), 14 deletions(-)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index d083ea5a9..5f80d7210 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -417,18 +417,8 @@ class HookTestCase(t.NamedTuple):
         "3.5",
         xfail_reason="pane-title-changed requires tmux 3.5+",
     ),
-    HookTestCase(
-        "client_light_theme",
-        "client-light-theme",
-        "3.5",
-        xfail_reason="client-light-theme requires tmux 3.5+",
-    ),
-    HookTestCase(
-        "client_dark_theme",
-        "client-dark-theme",
-        "3.5",
-        xfail_reason="client-dark-theme requires tmux 3.5+",
-    ),
+    # NOTE: client-light-theme and client-dark-theme are not in any released tmux
+    # version yet (will be in 3.6+). Add them back when 3.6 is released.
 ]
 
 # Combine all hook test cases
diff --git a/tests/test_options.py b/tests/test_options.py
index f68eeb1e6..24a02c08d 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -992,7 +992,7 @@ class OptionTestCase(t.NamedTuple):
         "pane_alternate_screen", "alternate-screen", OptionScope.Pane, "on", bool, "3.0"
     ),
     OptionTestCase(
-        "pane_scroll_on_clear", "scroll-on-clear", OptionScope.Pane, "on", bool, "3.2"
+        "pane_scroll_on_clear", "scroll-on-clear", OptionScope.Pane, "on", bool, "3.3"
     ),
     OptionTestCase(
         "pane_synchronize_panes",
@@ -1012,7 +1012,7 @@ class OptionTestCase(t.NamedTuple):
         OptionScope.Pane,
         "all",
         str,
-        "3.3",
+        "3.4",
     ),
     # remain-on-exit: "on"/"off" return bool, use "failed" for str test (3.2+)
     OptionTestCase(

From 210014a394435d51616508c4c38d5f0604fb3b48 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 14:42:52 -0600
Subject: [PATCH 056/136] docs(hooks): convert commented examples to runnable
 doctests

why: Commented code in docstrings violates project convention and provides
no documentation value since it won't run or be tested
what:
- get_hook_indices(): add full doctest with setup/teardown
- get_hook_values(): add doctest verifying SparseArray behavior
- set_hooks_bulk(): add doctests for dict, list, and clear_existing modes
- clear_hook(): add doctest demonstrating hook removal
- append_hook(): add doctest showing sequential index addition

All doctests verified to pass with pytest --doctest-modules
---
 src/libtmux/hooks.py | 95 +++++++++++++++++++++++++++++++++++---------
 1 file changed, 77 insertions(+), 18 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 2312fddc1..eed49fcd0 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -410,9 +410,17 @@ def get_hook_indices(
 
         Examples
         --------
-        >>> # After setting hooks at indices 0, 1, 5:
-        >>> # session.get_hook_indices('session-renamed')
-        >>> # [0, 1, 5]
+        >>> session.set_hook('session-renamed[0]', 'display-message "test"')
+        Session($...)
+
+        >>> session.set_hook('session-renamed[5]', 'display-message "test"')
+        Session($...)
+
+        >>> session.get_hook_indices('session-renamed')
+        [0, 5]
+
+        >>> session.clear_hook('session-renamed')
+        Session($...)
         """
         hooks_output = self._show_hook(
             hook=hook,
@@ -455,9 +463,18 @@ def get_hook_values(
 
         Examples
         --------
-        >>> # values = session.get_hook_values('session-renamed')
-        >>> # for val in values.iter_values():
-        >>> #     print(val)
+        >>> session.set_hook('session-renamed[0]', 'display-message "first"')
+        Session($...)
+
+        >>> values = session.get_hook_values('session-renamed')
+        >>> 0 in values
+        True
+
+        >>> 'display-message' in values[0]
+        True
+
+        >>> session.clear_hook('session-renamed')
+        Session($...)
         """
         hooks_output = self._show_hook(
             hook=hook,
@@ -511,21 +528,40 @@ def set_hooks_bulk(
         --------
         Set hooks with explicit indices:
 
-        >>> # session.set_hooks_bulk('session-renamed', {
-        >>> #     0: 'display-message "hook 0"',
-        >>> #     1: 'display-message "hook 1"',
-        >>> # })
+        >>> session.set_hooks_bulk('session-renamed', {
+        ...     0: 'display-message "hook 0"',
+        ...     1: 'display-message "hook 1"',
+        ... })
+        Session($...)
+
+        >>> session.get_hook_indices('session-renamed')
+        [0, 1]
 
         Set hooks from a list (sequential indices):
 
-        >>> # session.set_hooks_bulk('after-new-window', [
-        >>> #     'select-pane -t 0',
-        >>> #     'send-keys "clear" Enter',
-        >>> # ])
+        >>> session.set_hooks_bulk('after-new-window', [
+        ...     'select-pane -t 0',
+        ...     'send-keys "clear" Enter',
+        ... ])
+        Session($...)
+
+        >>> session.get_hook_indices('after-new-window')
+        [0, 1]
+
+        Replace all existing hooks with ``clear_existing=True``:
 
-        Replace all existing hooks:
+        >>> session.set_hooks_bulk('session-renamed', {0: 'display-message "new"'},
+        ...                        clear_existing=True)
+        Session($...)
 
-        >>> # session.set_hooks_bulk('session-renamed', [...], clear_existing=True)
+        >>> session.get_hook_indices('session-renamed')
+        [0]
+
+        >>> session.clear_hook('session-renamed')
+        Session($...)
+
+        >>> session.clear_hook('after-new-window')
+        Session($...)
         """
         if clear_existing:
             self.clear_hook(hook, global_=global_, scope=scope)
@@ -571,7 +607,20 @@ def clear_hook(
 
         Examples
         --------
-        >>> # session.clear_hook('session-renamed')
+        >>> session.set_hook('session-renamed[0]', 'display-message "test"')
+        Session($...)
+
+        >>> session.set_hook('session-renamed[1]', 'display-message "test2"')
+        Session($...)
+
+        >>> session.get_hook_indices('session-renamed')
+        [0, 1]
+
+        >>> session.clear_hook('session-renamed')
+        Session($...)
+
+        >>> session.get_hook_indices('session-renamed')
+        []
         """
         indices = self.get_hook_indices(
             hook,
@@ -615,7 +664,17 @@ def append_hook(
 
         Examples
         --------
-        >>> # session.append_hook('session-renamed', 'display-message "appended"')
+        >>> session.set_hook('session-renamed[0]', 'display-message "first"')
+        Session($...)
+
+        >>> session.append_hook('session-renamed', 'display-message "appended"')
+        Session($...)
+
+        >>> session.get_hook_indices('session-renamed')
+        [0, 1]
+
+        >>> session.clear_hook('session-renamed')
+        Session($...)
         """
         indices = self.get_hook_indices(
             hook,

From c49c2958047e48c5e24c6dd8f3821fcd467687de Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 16:15:30 -0600
Subject: [PATCH 057/136] refactor(tests): remove dead code and unused xfail

why: Clean up test code by removing unused/impossible code paths.
what:
- Remove unused xfail_reason from pane_title_changed (test uses
  pytest.skip() before xfail can trigger)
- Remove dead assertion block in test_options.py that contradicted
  the preceding assert (lines 445-456)
---
 tests/test_hooks.py   |  1 -
 tests/test_options.py | 13 -------------
 2 files changed, 14 deletions(-)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 5f80d7210..715898458 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -415,7 +415,6 @@ class HookTestCase(t.NamedTuple):
         "pane_title_changed",
         "pane-title-changed",
         "3.5",
-        xfail_reason="pane-title-changed requires tmux 3.5+",
     ),
     # NOTE: client-light-theme and client-dark-theme are not in any released tmux
     # version yet (will be in 3.6+). Add them back when 3.6 is released.
diff --git a/tests/test_options.py b/tests/test_options.py
index 24a02c08d..bfc2c087c 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -442,19 +442,6 @@ def test_show_option_pane_fixture(
 
     assert result == expected
 
-    if expected is None:
-        assert result is not None, (
-            f"Expected {expected} to be {type(expected)}, got None"
-        )
-
-    if isinstance(expected, dict):
-        assert isinstance(result, dict), f'Expected dict, got "{type(result)}"'
-
-        for k, v in expected.items():
-            assert k in result
-
-            assert result[k] == v
-
 
 def test_stable_baseline_options_and_hooks(server: Server) -> None:
     """Ensure stable baseline across tmux versions."""

From 49fea0694f88f213898c6030476f7ffe417ae5b0 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Wed, 26 Nov 2025 16:27:43 -0600
Subject: [PATCH 058/136] docs(internals): add SparseArray doc page

why: SparseArray internal API had no documentation page.
what:
- Create docs/internals/sparse_array.md with automodule directive
- Add sparse_array to docs/internals/index.md toctree
---
 docs/internals/index.md        |  1 +
 docs/internals/sparse_array.md | 14 ++++++++++++++
 2 files changed, 15 insertions(+)
 create mode 100644 docs/internals/sparse_array.md

diff --git a/docs/internals/index.md b/docs/internals/index.md
index c79aed0e2..0d19d3763 100644
--- a/docs/internals/index.md
+++ b/docs/internals/index.md
@@ -12,6 +12,7 @@ If you need an internal API stabilized please [file an issue](https://github.com
 dataclasses
 query_list
 constants
+sparse_array
 ```
 
 ## Environmental variables
diff --git a/docs/internals/sparse_array.md b/docs/internals/sparse_array.md
new file mode 100644
index 000000000..74ea7892d
--- /dev/null
+++ b/docs/internals/sparse_array.md
@@ -0,0 +1,14 @@
+# Internal Sparse Array - `libtmux._internal.sparse_array`
+
+:::{warning}
+Be careful with these! Internal APIs are **not** covered by version policies. They can break or be removed between minor versions!
+
+If you need an internal API stabilized please [file an issue](https://github.com/tmux-python/libtmux/issues).
+:::
+
+```{eval-rst}
+.. automodule:: libtmux._internal.sparse_array
+   :members:
+   :undoc-members:
+   :show-inheritance:
+```

From c0b3021090425d574c53fd68bb2deb520da259d8 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Thu, 27 Nov 2025 06:18:55 -0600
Subject: [PATCH 059/136] fix(tests): remove undefined TmuxArray reference

why: Test collection was failing with NameError due to undefined TmuxArray
what:
- Replace TmuxArray({...}) with plain dict literal
- Matches the pattern used by adjacent terminal-features fixture
---
 tests/test_options.py | 18 ++++++++----------
 1 file changed, 8 insertions(+), 10 deletions(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index bfc2c087c..3aaa3c6e3 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -378,16 +378,14 @@ class OptionDataclassTestFixture(t.NamedTuple):
         .split("\n"),
         dataclass_attribute="command_alias",
         tmux_option="command-alias",
-        expected=TmuxArray(
-            {
-                "split-pane": "split-window",
-                "splitp": "split-window",
-                "server-info": "show-messages -JT",
-                "info": "show-messages -JT",
-                "choose-window": "choose-tree -w",
-                "choose-session": "choose-tree -s",
-            },
-        ),
+        expected={
+            "split-pane": "split-window",
+            "splitp": "split-window",
+            "server-info": "show-messages -JT",
+            "info": "show-messages -JT",
+            "choose-window": "choose-tree -w",
+            "choose-session": "choose-tree -s",
+        },
     ),
 ]
 

From f0fac8920aae7b31e20a3059874c213a2bafafde Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 10:41:52 -0600
Subject: [PATCH 060/136] hooks(refactor): rename set_hooks_bulk -> set_hooks

why: Align with libtmux naming conventions (singular/plural pattern)
what:
- Rename method from set_hooks_bulk to set_hooks
- Update doctests to use show_hook().keys() instead of get_hook_indices
- Update module docstring bulk operations list

Squash target: d4de173 (hooks feat: add bulk operations)
---
 src/libtmux/hooks.py | 29 ++++++++++++++---------------
 1 file changed, 14 insertions(+), 15 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index eed49fcd0..c05693944 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -27,11 +27,7 @@
 -------------------
 This module provides bulk operations for managing multiple indexed hooks:
 
-- :meth:`~HooksMixin.get_hook_indices` - Get list of existing indices for a hook
-- :meth:`~HooksMixin.get_hook_values` - Get all values as SparseArray
-- :meth:`~HooksMixin.set_hooks_bulk` - Set multiple hooks at once
-- :meth:`~HooksMixin.clear_hook` - Unset all indexed values for a hook
-- :meth:`~HooksMixin.append_hook` - Append at next available index
+- :meth:`~HooksMixin.set_hooks` - Set multiple hooks at once
 """
 
 from __future__ import annotations
@@ -492,7 +488,7 @@ def get_hook_values(
         result: SparseArray[str] = hook_array
         return result
 
-    def set_hooks_bulk(
+    def set_hooks(
         self,
         hook: str,
         values: HookValues,
@@ -528,39 +524,42 @@ def set_hooks_bulk(
         --------
         Set hooks with explicit indices:
 
-        >>> session.set_hooks_bulk('session-renamed', {
+        >>> session.set_hooks('session-renamed', {
         ...     0: 'display-message "hook 0"',
         ...     1: 'display-message "hook 1"',
         ... })
         Session($...)
 
-        >>> session.get_hook_indices('session-renamed')
+        >>> hooks = session.show_hook('session-renamed')
+        >>> sorted(hooks.keys())
         [0, 1]
 
         Set hooks from a list (sequential indices):
 
-        >>> session.set_hooks_bulk('after-new-window', [
+        >>> session.set_hooks('after-new-window', [
         ...     'select-pane -t 0',
         ...     'send-keys "clear" Enter',
         ... ])
         Session($...)
 
-        >>> session.get_hook_indices('after-new-window')
+        >>> hooks = session.show_hook('after-new-window')
+        >>> sorted(hooks.keys())
         [0, 1]
 
         Replace all existing hooks with ``clear_existing=True``:
 
-        >>> session.set_hooks_bulk('session-renamed', {0: 'display-message "new"'},
-        ...                        clear_existing=True)
+        >>> session.set_hooks('session-renamed', {0: 'display-message "new"'},
+        ...                   clear_existing=True)
         Session($...)
 
-        >>> session.get_hook_indices('session-renamed')
+        >>> hooks = session.show_hook('session-renamed')
+        >>> sorted(hooks.keys())
         [0]
 
-        >>> session.clear_hook('session-renamed')
+        >>> session.unset_hook('session-renamed')
         Session($...)
 
-        >>> session.clear_hook('after-new-window')
+        >>> session.unset_hook('after-new-window')
         Session($...)
         """
         if clear_existing:

From 34796e1e18d294ccba503799794852e75d29c304 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 10:42:30 -0600
Subject: [PATCH 061/136] tests(hooks): update for set_hooks_bulk -> set_hooks
 rename

why: Tests need to match the renamed API method
what:
- Update all set_hooks_bulk calls to set_hooks
- Update comments referencing set_hooks_bulk

Squash target: ec340de (tests: bulk operations test grid)
---
 tests/test_hooks.py | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 715898458..8120aa117 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -590,7 +590,7 @@ class BulkOpTestCase(t.NamedTuple):
     ),
 ]
 
-# --- set_hooks_bulk tests ---
+# --- set_hooks tests ---
 SET_BULK_TESTS: list[BulkOpTestCase] = [
     BulkOpTestCase(
         "set_bulk_with_dict",
@@ -692,7 +692,7 @@ def test_bulk_hook_operation(server: Server, test_case: BulkOpTestCase) -> None:
     This parametrized test ensures all bulk operations work correctly:
     - get_hook_indices: returns sorted list of existing indices
     - get_hook_values: returns SparseArray with values
-    - set_hooks_bulk: sets multiple hooks at once
+    - set_hooks: sets multiple hooks at once
     - clear_hook: removes all indexed values
     - append_hook: appends at next available index
     """
@@ -716,7 +716,7 @@ def test_bulk_hook_operation(server: Server, test_case: BulkOpTestCase) -> None:
                 assert any(expected_str in v for v in values.values())
 
     elif test_case.operation == "set_bulk":
-        session.set_hooks_bulk(test_case.hook, **test_case.operation_args)
+        session.set_hooks(test_case.hook, **test_case.operation_args)
         indices = session.get_hook_indices(test_case.hook)
         assert indices == test_case.expected_indices
         if test_case.expected_contains:
@@ -765,14 +765,14 @@ def test_bulk_hook_values_iteration(server: Server) -> None:
 
 
 def test_bulk_hook_set_with_sparse_array(server: Server) -> None:
-    """Test set_hooks_bulk with SparseArray input."""
+    """Test set_hooks with SparseArray input."""
     session = server.new_session(session_name="test_bulk_ops")
 
     sparse: SparseArray[str] = SparseArray()
     sparse.add(0, "display-message 'from sparse 0'")
     sparse.add(10, "display-message 'from sparse 10'")
 
-    session.set_hooks_bulk("session-renamed", sparse)
+    session.set_hooks("session-renamed", sparse)
 
     indices = session.get_hook_indices("session-renamed")
     assert indices == [0, 10]
@@ -787,7 +787,7 @@ def test_bulk_hook_method_chaining(server: Server) -> None:
 
     # Chain operations
     result = (
-        session.set_hooks_bulk(
+        session.set_hooks(
             "session-renamed",
             ["display-message 'hook 0'"],
         )

From 6456301ab85504ad142821a23fbfbd0e30da98da Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 10:43:01 -0600
Subject: [PATCH 062/136] hooks(fix): correct show_hook return type to include
 SparseArray

why: Return type was incorrectly `str | int | None`, missing SparseArray
what:
- Fix return type to `str | int | SparseArray[str] | None`
- Add comprehensive docstring with examples
- Document that array hooks return SparseArray with .keys()/.values()

Squash target: d4de173 (hooks feat: add bulk operations)
---
 src/libtmux/hooks.py | 30 ++++++++++++++++++++++++++++--
 1 file changed, 28 insertions(+), 2 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index c05693944..fc56d47b9 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -355,17 +355,43 @@ def show_hook(
         global_: bool = False,
         scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
         ignore_errors: bool | None = None,
-    ) -> str | int | None:
-        """Return value for the hook.
+    ) -> str | int | SparseArray[str] | None:
+        """Return value for a hook.
+
+        For array hooks (e.g., ``session-renamed``), returns a
+        :class:`~libtmux._internal.sparse_array.SparseArray` with hook values
+        at their original indices. Use ``.keys()`` for indices and ``.values()``
+        for values.
 
         Parameters
         ----------
         hook : str
+            Hook name to query
+
+        Returns
+        -------
+        str | int | SparseArray[str] | None
+            Hook value. For array hooks, returns SparseArray.
 
         Raises
         ------
         :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
         :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+
+        Examples
+        --------
+        >>> session.set_hook('session-renamed[0]', 'display-message "test"')
+        Session($...)
+
+        >>> hooks = session.show_hook('session-renamed')
+        >>> isinstance(hooks, SparseArray)
+        True
+
+        >>> sorted(hooks.keys())
+        [0]
+
+        >>> session.unset_hook('session-renamed')
+        Session($...)
         """
         hooks_output = self._show_hook(
             hook=hook,

From d97a3e2dc8925fba7234a92dce67dfd80192485a Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 10:44:49 -0600
Subject: [PATCH 063/136] hooks(refactor): remove redundant bulk operations
 methods

why: These methods are redundant with existing API
what:
- Remove get_hook_indices: use show_hook().keys() instead
- Remove get_hook_values: use show_hook() directly (returns SparseArray)
- Remove clear_hook: use unset_hook() without index (clears all)
- Remove append_hook: use set_hook(..., append=True) instead
- Update set_hooks to use unset_hook instead of clear_hook

Squash target: d4de173 (hooks feat: add bulk operations)
---
 src/libtmux/hooks.py | 223 +------------------------------------------
 1 file changed, 1 insertion(+), 222 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index fc56d47b9..0f8b28a4a 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -403,117 +403,6 @@ def show_hook(
         hooks = Hooks.from_stdout(hooks_output)
         return getattr(hooks, hook.replace("-", "_"), None)
 
-    # --- Bulk operations API ---
-
-    def get_hook_indices(
-        self,
-        hook: str,
-        global_: bool = False,
-        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
-        ignore_errors: bool | None = None,
-    ) -> list[int]:
-        """Get list of indices that exist for a hook.
-
-        Parameters
-        ----------
-        hook : str
-            Hook name, e.g. 'session-renamed'
-        global_ : bool
-            Use global hooks
-        scope : OptionScope | None
-            Scope for the hook
-        ignore_errors : bool | None
-            Suppress errors
-
-        Returns
-        -------
-        list[int]
-            Sorted list of indices that exist for this hook.
-
-        Examples
-        --------
-        >>> session.set_hook('session-renamed[0]', 'display-message "test"')
-        Session($...)
-
-        >>> session.set_hook('session-renamed[5]', 'display-message "test"')
-        Session($...)
-
-        >>> session.get_hook_indices('session-renamed')
-        [0, 5]
-
-        >>> session.clear_hook('session-renamed')
-        Session($...)
-        """
-        hooks_output = self._show_hook(
-            hook=hook,
-            global_=global_,
-            scope=scope,
-            ignore_errors=ignore_errors,
-        )
-        if hooks_output is None:
-            return []
-        hooks = Hooks.from_stdout(hooks_output)
-        hook_array = getattr(hooks, hook.replace("-", "_"), None)
-        if hook_array is None or not isinstance(hook_array, SparseArray):
-            return []
-        return sorted(hook_array.keys())
-
-    def get_hook_values(
-        self,
-        hook: str,
-        global_: bool = False,
-        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
-        ignore_errors: bool | None = None,
-    ) -> SparseArray[str]:
-        """Get all indexed values for a hook as SparseArray.
-
-        Parameters
-        ----------
-        hook : str
-            Hook name, e.g. 'session-renamed'
-        global_ : bool
-            Use global hooks
-        scope : OptionScope | None
-            Scope for the hook
-        ignore_errors : bool | None
-            Suppress errors
-
-        Returns
-        -------
-        SparseArray[str]
-            SparseArray containing hook values at their original indices.
-
-        Examples
-        --------
-        >>> session.set_hook('session-renamed[0]', 'display-message "first"')
-        Session($...)
-
-        >>> values = session.get_hook_values('session-renamed')
-        >>> 0 in values
-        True
-
-        >>> 'display-message' in values[0]
-        True
-
-        >>> session.clear_hook('session-renamed')
-        Session($...)
-        """
-        hooks_output = self._show_hook(
-            hook=hook,
-            global_=global_,
-            scope=scope,
-            ignore_errors=ignore_errors,
-        )
-        if hooks_output is None:
-            return SparseArray()
-        hooks = Hooks.from_stdout(hooks_output)
-        hook_array = getattr(hooks, hook.replace("-", "_"), None)
-        if hook_array is None or not isinstance(hook_array, SparseArray):
-            return SparseArray()
-        # Type narrowing doesn't work with isinstance for generics, so cast
-        result: SparseArray[str] = hook_array
-        return result
-
     def set_hooks(
         self,
         hook: str,
@@ -589,7 +478,7 @@ def set_hooks(
         Session($...)
         """
         if clear_existing:
-            self.clear_hook(hook, global_=global_, scope=scope)
+            self.unset_hook(hook, global_=global_, scope=scope)
 
         # Convert list to dict with sequential indices
         if isinstance(values, list):
@@ -604,113 +493,3 @@ def set_hooks(
             )
 
         return self
-
-    def clear_hook(
-        self,
-        hook: str,
-        global_: bool | None = None,
-        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
-        ignore_errors: bool | None = None,
-    ) -> Self:
-        """Unset all indexed values for a hook.
-
-        Parameters
-        ----------
-        hook : str
-            Hook name, e.g. 'session-renamed'
-        global_ : bool | None
-            Use global hooks
-        scope : OptionScope | None
-            Scope for the hook
-        ignore_errors : bool | None
-            Suppress errors when unsetting
-
-        Returns
-        -------
-        Self
-            Returns self for method chaining.
-
-        Examples
-        --------
-        >>> session.set_hook('session-renamed[0]', 'display-message "test"')
-        Session($...)
-
-        >>> session.set_hook('session-renamed[1]', 'display-message "test2"')
-        Session($...)
-
-        >>> session.get_hook_indices('session-renamed')
-        [0, 1]
-
-        >>> session.clear_hook('session-renamed')
-        Session($...)
-
-        >>> session.get_hook_indices('session-renamed')
-        []
-        """
-        indices = self.get_hook_indices(
-            hook,
-            global_=global_ if global_ is not None else False,
-            scope=scope,
-            ignore_errors=ignore_errors,
-        )
-        for index in indices:
-            self.unset_hook(
-                f"{hook}[{index}]",
-                global_=global_,
-                scope=scope,
-                ignore_errors=ignore_errors,
-            )
-        return self
-
-    def append_hook(
-        self,
-        hook: str,
-        value: str,
-        global_: bool | None = None,
-        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
-    ) -> Self:
-        """Append a hook value at the next available index.
-
-        Parameters
-        ----------
-        hook : str
-            Hook name, e.g. 'session-renamed'
-        value : str
-            Hook command to append
-        global_ : bool | None
-            Use global hooks
-        scope : OptionScope | None
-            Scope for the hook
-
-        Returns
-        -------
-        Self
-            Returns self for method chaining.
-
-        Examples
-        --------
-        >>> session.set_hook('session-renamed[0]', 'display-message "first"')
-        Session($...)
-
-        >>> session.append_hook('session-renamed', 'display-message "appended"')
-        Session($...)
-
-        >>> session.get_hook_indices('session-renamed')
-        [0, 1]
-
-        >>> session.clear_hook('session-renamed')
-        Session($...)
-        """
-        indices = self.get_hook_indices(
-            hook,
-            global_=global_ if global_ is not None else False,
-            scope=scope,
-        )
-        next_index = max(indices) + 1 if indices else 0
-        self.set_hook(
-            f"{hook}[{next_index}]",
-            value,
-            global_=global_,
-            scope=scope,
-        )
-        return self

From 704563000e47f78f50db9785c4ccd054b3058f0c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 10:48:55 -0600
Subject: [PATCH 064/136] tests(hooks): update for simplified bulk operations
 API

why: Tests need to use new API after removing redundant methods
what:
- Replace get_hook_indices/get_hook_values with show_hook().keys()
- Replace clear_hook with unset_hook
- Replace append_hook with set_hook(..., append=True)
- Add test for show_hook returning SparseArray
- Add test for unset_hook clearing all indices
- Add test for set_hook append=True flag

Squash target: ec340de (tests: bulk operations test grid)
---
 tests/test_hooks.py | 300 ++++++++++++++++----------------------------
 1 file changed, 107 insertions(+), 193 deletions(-)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 8120aa117..968324c7b 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -517,84 +517,24 @@ def test_new_hooks_version_gated(server: Server, test_case: HookTestCase) -> Non
 
 
 # =============================================================================
-# Bulk Operations API Tests
+# set_hooks Tests
 # =============================================================================
 
 
-class BulkOpTestCase(t.NamedTuple):
-    """Test case for bulk hook operations."""
+class SetHooksTestCase(t.NamedTuple):
+    """Test case for set_hooks operations."""
 
     test_id: str
-    operation: str  # "get_indices", "get_values", "set_bulk", "clear", "append"
     hook: str  # Hook name to test
     setup_hooks: dict[int, str]  # Initial hooks to set (index -> value)
-    operation_args: dict[str, t.Any]  # Args for operation
+    operation_args: dict[str, t.Any]  # Args for set_hooks
     expected_indices: list[int]  # Expected indices after operation
     expected_contains: list[str] | None = None  # Strings expected in values
 
 
-# --- get_hook_indices tests ---
-GET_INDICES_TESTS: list[BulkOpTestCase] = [
-    BulkOpTestCase(
-        "get_indices_empty",
-        "get_indices",
-        "session-renamed",
-        {},
-        {},
-        [],
-    ),
-    BulkOpTestCase(
-        "get_indices_sequential",
-        "get_indices",
-        "session-renamed",
-        {
-            0: "display-message 'hook 0'",
-            1: "display-message 'hook 1'",
-            2: "display-message 'hook 2'",
-        },
-        {},
-        [0, 1, 2],
-    ),
-    BulkOpTestCase(
-        "get_indices_sparse",
-        "get_indices",
-        "session-renamed",
-        {
-            0: "display-message 'hook 0'",
-            5: "display-message 'hook 5'",
-            10: "display-message 'hook 10'",
-        },
-        {},
-        [0, 5, 10],
-    ),
-]
-
-# --- get_hook_values tests ---
-GET_VALUES_TESTS: list[BulkOpTestCase] = [
-    BulkOpTestCase(
-        "get_values_empty",
-        "get_values",
-        "session-renamed",
-        {},
-        {},
-        [],
-    ),
-    BulkOpTestCase(
-        "get_values_sparse",
-        "get_values",
-        "session-renamed",
-        {0: "display-message 'hook 0'", 5: "display-message 'hook 5'"},
-        {},
-        [0, 5],
-        ["display-message"],
-    ),
-]
-
-# --- set_hooks tests ---
-SET_BULK_TESTS: list[BulkOpTestCase] = [
-    BulkOpTestCase(
-        "set_bulk_with_dict",
-        "set_bulk",
+SET_HOOKS_TESTS: list[SetHooksTestCase] = [
+    SetHooksTestCase(
+        "set_hooks_with_dict",
         "session-renamed",
         {},
         {
@@ -607,9 +547,8 @@ class BulkOpTestCase(t.NamedTuple):
         [0, 1, 5],
         ["hook 0", "hook 1", "hook 5"],
     ),
-    BulkOpTestCase(
-        "set_bulk_with_list",
-        "set_bulk",
+    SetHooksTestCase(
+        "set_hooks_with_list",
         "session-renamed",
         {},
         {
@@ -621,9 +560,8 @@ class BulkOpTestCase(t.NamedTuple):
         },
         [0, 1, 2],
     ),
-    BulkOpTestCase(
-        "set_bulk_clear_existing",
-        "set_bulk",
+    SetHooksTestCase(
+        "set_hooks_clear_existing",
         "session-renamed",
         {0: "display-message 'old 0'", 1: "display-message 'old 1'"},
         {"values": {0: "display-message 'new 0'"}, "clear_existing": True},
@@ -632,141 +570,68 @@ class BulkOpTestCase(t.NamedTuple):
     ),
 ]
 
-# --- clear_hook tests ---
-CLEAR_TESTS: list[BulkOpTestCase] = [
-    BulkOpTestCase(
-        "clear_hook",
-        "clear",
-        "session-renamed",
-        {0: "display-message 'hook 0'", 5: "display-message 'hook 5'"},
-        {},
-        [],
-    ),
-]
-
-# --- append_hook tests ---
-APPEND_TESTS: list[BulkOpTestCase] = [
-    BulkOpTestCase(
-        "append_to_empty",
-        "append",
-        "session-renamed",
-        {},
-        {"value": "display-message 'appended'"},
-        [0],
-        ["appended"],
-    ),
-    BulkOpTestCase(
-        "append_sequential",
-        "append",
-        "session-renamed",
-        {0: "display-message 'initial'"},
-        {"value": "display-message 'appended'"},
-        [0, 1],
-    ),
-    BulkOpTestCase(
-        "append_after_sparse",
-        "append",
-        "session-renamed",
-        {0: "display-message 'at 0'", 10: "display-message 'at 10'"},
-        {"value": "display-message 'appended'"},
-        [0, 10, 11],
-        ["appended"],
-    ),
-]
-
-# Combine all bulk operation test cases
-ALL_BULK_OP_TESTS: list[BulkOpTestCase] = (
-    GET_INDICES_TESTS + GET_VALUES_TESTS + SET_BULK_TESTS + CLEAR_TESTS + APPEND_TESTS
-)
-
 
-def _build_bulk_op_params() -> list[t.Any]:
-    """Build pytest params for bulk operation tests."""
-    return [pytest.param(tc, id=tc.test_id) for tc in ALL_BULK_OP_TESTS]
+def _build_set_hooks_params() -> list[t.Any]:
+    """Build pytest params for set_hooks tests."""
+    return [pytest.param(tc, id=tc.test_id) for tc in SET_HOOKS_TESTS]
 
 
-@pytest.mark.parametrize("test_case", _build_bulk_op_params())
-def test_bulk_hook_operation(server: Server, test_case: BulkOpTestCase) -> None:
-    """Test bulk hook operations.
-
-    This parametrized test ensures all bulk operations work correctly:
-    - get_hook_indices: returns sorted list of existing indices
-    - get_hook_values: returns SparseArray with values
-    - set_hooks: sets multiple hooks at once
-    - clear_hook: removes all indexed values
-    - append_hook: appends at next available index
-    """
-    session = server.new_session(session_name="test_bulk_ops")
+@pytest.mark.parametrize("test_case", _build_set_hooks_params())
+def test_set_hooks(server: Server, test_case: SetHooksTestCase) -> None:
+    """Test set_hooks operations."""
+    session = server.new_session(session_name="test_set_hooks")
 
     # Setup initial hooks
     for idx, val in test_case.setup_hooks.items():
         session.set_hook(f"{test_case.hook}[{idx}]", val)
 
-    # Perform operation based on type
-    if test_case.operation == "get_indices":
-        result = session.get_hook_indices(test_case.hook)
-        assert result == test_case.expected_indices
-
-    elif test_case.operation == "get_values":
-        values = session.get_hook_values(test_case.hook)
-        assert isinstance(values, SparseArray)
-        assert sorted(values.keys()) == test_case.expected_indices
-        if test_case.expected_contains:
-            for expected_str in test_case.expected_contains:
-                assert any(expected_str in v for v in values.values())
-
-    elif test_case.operation == "set_bulk":
-        session.set_hooks(test_case.hook, **test_case.operation_args)
-        indices = session.get_hook_indices(test_case.hook)
-        assert indices == test_case.expected_indices
-        if test_case.expected_contains:
-            values = session.get_hook_values(test_case.hook)
-            for expected_str in test_case.expected_contains:
-                assert any(expected_str in v for v in values.values())
-
-    elif test_case.operation == "clear":
-        session.clear_hook(test_case.hook)
-        indices = session.get_hook_indices(test_case.hook)
-        assert indices == test_case.expected_indices
-
-    elif test_case.operation == "append":
-        session.append_hook(test_case.hook, test_case.operation_args["value"])
-        indices = session.get_hook_indices(test_case.hook)
-        assert indices == test_case.expected_indices
-        if test_case.expected_contains:
-            values = session.get_hook_values(test_case.hook)
-            for expected_str in test_case.expected_contains:
-                assert any(expected_str in v for v in values.values())
+    # Perform set_hooks
+    session.set_hooks(test_case.hook, **test_case.operation_args)
+
+    # Verify via show_hook
+    hooks = session.show_hook(test_case.hook)
+    assert hooks is not None
+    assert isinstance(hooks, SparseArray)
+    assert sorted(hooks.keys()) == test_case.expected_indices
+
+    if test_case.expected_contains:
+        for expected_str in test_case.expected_contains:
+            assert any(expected_str in v for v in hooks.values())
 
     # Cleanup
-    session.clear_hook(test_case.hook)
+    session.unset_hook(test_case.hook)
 
 
-def test_bulk_hook_values_iteration(server: Server) -> None:
-    """Test iterating over hook values in sorted order."""
-    session = server.new_session(session_name="test_bulk_ops")
+def test_show_hook_returns_sparse_array(server: Server) -> None:
+    """Test that show_hook returns SparseArray for array hooks."""
+    session = server.new_session(session_name="test_show_hook")
 
     # Set hooks at sparse indices (out of order)
     session.set_hook("session-renamed[5]", "display-message 'fifth'")
     session.set_hook("session-renamed[0]", "display-message 'zeroth'")
     session.set_hook("session-renamed[2]", "display-message 'second'")
 
-    values = session.get_hook_values("session-renamed")
-    value_list = list(values.iter_values())
+    hooks = session.show_hook("session-renamed")
+    assert hooks is not None
+    assert isinstance(hooks, SparseArray)
 
-    # Values should be in sorted index order
+    # Check keys (indices)
+    assert sorted(hooks.keys()) == [0, 2, 5]
+
+    # Check values via iter_values (sorted order)
+    value_list = list(hooks.iter_values())
     assert len(value_list) == 3
     assert "zeroth" in value_list[0]
     assert "second" in value_list[1]
     assert "fifth" in value_list[2]
 
     # Cleanup
-    session.clear_hook("session-renamed")
+    session.unset_hook("session-renamed")
 
 
-def test_bulk_hook_set_with_sparse_array(server: Server) -> None:
+def test_set_hooks_with_sparse_array(server: Server) -> None:
     """Test set_hooks with SparseArray input."""
-    session = server.new_session(session_name="test_bulk_ops")
+    session = server.new_session(session_name="test_set_hooks_sparse")
 
     sparse: SparseArray[str] = SparseArray()
     sparse.add(0, "display-message 'from sparse 0'")
@@ -774,33 +639,82 @@ def test_bulk_hook_set_with_sparse_array(server: Server) -> None:
 
     session.set_hooks("session-renamed", sparse)
 
-    indices = session.get_hook_indices("session-renamed")
-    assert indices == [0, 10]
+    hooks = session.show_hook("session-renamed")
+    assert hooks is not None
+    assert isinstance(hooks, SparseArray)
+    assert sorted(hooks.keys()) == [0, 10]
 
     # Cleanup
-    session.clear_hook("session-renamed")
+    session.unset_hook("session-renamed")
 
 
-def test_bulk_hook_method_chaining(server: Server) -> None:
-    """Test that bulk operations support method chaining."""
-    session = server.new_session(session_name="test_bulk_ops")
+def test_set_hooks_method_chaining(server: Server) -> None:
+    """Test that set_hooks supports method chaining."""
+    session = server.new_session(session_name="test_set_hooks_chain")
 
-    # Chain operations
+    # Chain set_hooks with set_hook (append=True)
     result = (
         session.set_hooks(
             "session-renamed",
             ["display-message 'hook 0'"],
         )
-        .append_hook("session-renamed", "display-message 'hook 1'")
-        .append_hook("session-renamed", "display-message 'hook 2'")
+        .set_hook("session-renamed", "display-message 'hook 1'", append=True)
+        .set_hook("session-renamed", "display-message 'hook 2'", append=True)
     )
 
     # Should return the session
     assert result is session
 
-    # Verify all hooks set
-    indices = session.get_hook_indices("session-renamed")
-    assert indices == [0, 1, 2]
+    # Verify all hooks set via show_hook
+    hooks = session.show_hook("session-renamed")
+    assert hooks is not None
+    assert isinstance(hooks, SparseArray)
+    assert sorted(hooks.keys()) == [0, 1, 2]
+
+    # Cleanup
+    session.unset_hook("session-renamed")
+
+
+def test_unset_hook_clears_all_indices(server: Server) -> None:
+    """Test that unset_hook without index clears all hook indices."""
+    session = server.new_session(session_name="test_unset_hook")
+
+    # Set hooks at multiple indices
+    session.set_hook("session-renamed[0]", "display-message 'hook 0'")
+    session.set_hook("session-renamed[5]", "display-message 'hook 5'")
+    session.set_hook("session-renamed[10]", "display-message 'hook 10'")
+
+    # Verify hooks exist
+    hooks = session.show_hook("session-renamed")
+    assert hooks is not None
+    assert isinstance(hooks, SparseArray)
+    assert sorted(hooks.keys()) == [0, 5, 10]
+
+    # Unset without index should clear all
+    session.unset_hook("session-renamed")
+
+    # Verify hooks are cleared
+    hooks_after = session.show_hook("session-renamed")
+    assert hooks_after is None or (
+        isinstance(hooks_after, SparseArray) and len(hooks_after) == 0
+    )
+
+
+def test_set_hook_append_flag(server: Server) -> None:
+    """Test set_hook with append=True uses tmux's -a flag."""
+    session = server.new_session(session_name="test_append_flag")
+
+    # Set initial hook
+    session.set_hook("session-renamed[0]", "display-message 'initial'")
+
+    # Append using set_hook with append=True
+    session.set_hook("session-renamed", "display-message 'appended'", append=True)
+
+    # Verify both hooks exist
+    hooks = session.show_hook("session-renamed")
+    assert hooks is not None
+    assert isinstance(hooks, SparseArray)
+    assert len(hooks) == 2
 
     # Cleanup
-    session.clear_hook("session-renamed")
+    session.unset_hook("session-renamed")

From afab0072cfb48dc3283d2c443e038f2e67241d9b Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 11:13:56 -0600
Subject: [PATCH 065/136] hooks(fix): add doctest cleanup for tmux < 3.0
 compatibility

why: On tmux 2.6-2.8, unset_hook without index doesn't clear all
array entries, causing state leakage between doctest examples
what:
- Add unset_hook cleanup after first set_hooks example
- Ensures clean state before clear_existing=True example

Squash target: 8a37592 (hooks refactor: rename set_hooks_bulk)
---
 src/libtmux/hooks.py | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 0f8b28a4a..80b9241c2 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -449,6 +449,9 @@ def set_hooks(
         >>> sorted(hooks.keys())
         [0, 1]
 
+        >>> session.unset_hook('session-renamed')
+        Session($...)
+
         Set hooks from a list (sequential indices):
 
         >>> session.set_hooks('after-new-window', [

From 70efe1dce19c0172142677e0bb510da6d36fe590 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 11:36:09 -0600
Subject: [PATCH 066/136] hooks(docs): skip set_hooks doctests for
 cross-version compat

why: Hook arrays are a tmux 3.0+ feature. On tmux < 3.0, hooks are
stored by exact name in a red-black tree, so "session-renamed[0]"
is a literal hook name, not an array index. The doctests fail on
tmux 2.6-2.8 because unset_hook('session-renamed') doesn't clear
hooks named "session-renamed[0]".

what:
- Add # doctest: +SKIP to all set_hooks examples
- Keep examples as documentation but don't run them

Ref: tmux commit dfb7bb68 (April 2019) merged hooks into options
as array options for tmux 3.0.
---
 src/libtmux/hooks.py | 29 ++++++++++++++++-------------
 1 file changed, 16 insertions(+), 13 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 80b9241c2..f39ed85f2 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -439,45 +439,48 @@ def set_hooks(
         --------
         Set hooks with explicit indices:
 
-        >>> session.set_hooks('session-renamed', {
+        >>> session.set_hooks('session-renamed', {  # doctest: +SKIP
         ...     0: 'display-message "hook 0"',
         ...     1: 'display-message "hook 1"',
         ... })
         Session($...)
 
-        >>> hooks = session.show_hook('session-renamed')
-        >>> sorted(hooks.keys())
+        >>> hooks = session.show_hook('session-renamed')  # doctest: +SKIP
+        >>> sorted(hooks.keys())  # doctest: +SKIP
         [0, 1]
 
-        >>> session.unset_hook('session-renamed')
+        >>> session.unset_hook('session-renamed')  # doctest: +SKIP
         Session($...)
 
         Set hooks from a list (sequential indices):
 
-        >>> session.set_hooks('after-new-window', [
+        >>> session.set_hooks('after-new-window', [  # doctest: +SKIP
         ...     'select-pane -t 0',
         ...     'send-keys "clear" Enter',
         ... ])
         Session($...)
 
-        >>> hooks = session.show_hook('after-new-window')
-        >>> sorted(hooks.keys())
+        >>> hooks = session.show_hook('after-new-window')  # doctest: +SKIP
+        >>> sorted(hooks.keys())  # doctest: +SKIP
         [0, 1]
 
         Replace all existing hooks with ``clear_existing=True``:
 
-        >>> session.set_hooks('session-renamed', {0: 'display-message "new"'},
-        ...                   clear_existing=True)
+        >>> session.set_hooks(  # doctest: +SKIP
+        ...     'session-renamed',
+        ...     {0: 'display-message "new"'},
+        ...     clear_existing=True,
+        ... )
         Session($...)
 
-        >>> hooks = session.show_hook('session-renamed')
-        >>> sorted(hooks.keys())
+        >>> hooks = session.show_hook('session-renamed')  # doctest: +SKIP
+        >>> sorted(hooks.keys())  # doctest: +SKIP
         [0]
 
-        >>> session.unset_hook('session-renamed')
+        >>> session.unset_hook('session-renamed')  # doctest: +SKIP
         Session($...)
 
-        >>> session.unset_hook('after-new-window')
+        >>> session.unset_hook('after-new-window')  # doctest: +SKIP
         Session($...)
         """
         if clear_existing:

From b0a89a049aa12b32764b00d71697e732bd03daf1 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 11:44:43 -0600
Subject: [PATCH 067/136] hooks(feat): add warning for set_hooks on tmux < 3.0

why: Hook arrays are a tmux 3.0+ feature. On tmux < 3.0, hooks are
stored by exact name in a red-black tree, so "session-renamed[0]"
is a literal hook name, not an array index. This causes unexpected
behavior with set_hooks and clear_existing.

what:
- Add UserWarning when set_hooks is called on tmux < 3.0
- Warning explains the limitation and references tmux commit dfb7bb68

Ref: tmux commit dfb7bb68 (April 2019) merged hooks into options
as array options for tmux 3.0.
---
 src/libtmux/hooks.py | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index f39ed85f2..fe2b74386 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -483,6 +483,18 @@ def set_hooks(
         >>> session.unset_hook('after-new-window')  # doctest: +SKIP
         Session($...)
         """
+        # Hook arrays require tmux 3.0+. On older versions, hooks are stored
+        # by exact name (e.g. "session-renamed[0]" is a literal name, not an
+        # array index). See tmux commit dfb7bb68 (April 2019).
+        if has_lt_version("3.0"):
+            warnings.warn(
+                "Hook arrays require tmux 3.0+. "
+                "On older versions, set_hooks creates hooks with literal bracket "
+                "names (e.g. 'session-renamed[0]') instead of array indices, "
+                "and clear_existing/unset_hook may not work as expected.",
+                stacklevel=2,
+            )
+
         if clear_existing:
             self.unset_hook(hook, global_=global_, scope=scope)
 

From d9d38b9234e4d9040042a6a32ccd81a6cea0ccb7 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 11:44:52 -0600
Subject: [PATCH 068/136] tests(hooks): add version compatibility tests

why: Document and test hook behavior differences between tmux < 3.0
and tmux 3.0+ to prevent regressions and help users understand the
version requirements.

what:
- Add test_hooks_compat.py with detailed module docstring explaining
  the tmux hook architecture change in 3.0
- Test warning is emitted on < 3.0 using pytest.warns
- Test no warning on 3.0+ using recwarn fixture
- Test set_hooks array functionality on 3.0+
- Reference tmux commit dfb7bb68 in documentation

Ref: tmux commit dfb7bb68 (April 2019) merged hooks into options
as array options.
---
 tests/test_hooks_compat.py | 203 +++++++++++++++++++++++++++++++++++++
 1 file changed, 203 insertions(+)
 create mode 100644 tests/test_hooks_compat.py

diff --git a/tests/test_hooks_compat.py b/tests/test_hooks_compat.py
new file mode 100644
index 000000000..35dd0ed7e
--- /dev/null
+++ b/tests/test_hooks_compat.py
@@ -0,0 +1,203 @@
+"""Tests for hook version compatibility.
+
+This module tests hook behavior differences between tmux < 3.0 and tmux 3.0+.
+
+tmux Hook Architecture Changes (3.0)
+------------------------------------
+Prior to tmux 3.0, hooks were stored in a red-black tree by exact name.
+Setting "session-renamed[0]" created a hook with that literal name (including
+brackets). The ``set-hook -u session-renamed`` command only removed a hook
+named exactly "session-renamed", NOT "session-renamed[0]".
+
+In tmux 3.0 (commit dfb7bb68, April 2019), hooks were merged into the options
+tree as array options. Now "session-renamed[0]" is index 0 of the
+"session-renamed" array, and ``set-hook -u session-renamed`` clears all
+indices of that array.
+
+This difference means that:
+- On tmux < 3.0: ``set_hooks()`` creates hooks with literal bracket names
+- On tmux < 3.0: ``unset_hook('session-renamed')`` does NOT clear indexed hooks
+- On tmux 3.0+: ``set_hooks()`` properly creates array entries
+- On tmux 3.0+: ``unset_hook('session-renamed')`` clears all array indices
+
+References
+----------
+- tmux commit: dfb7bb68 (April 26, 2019)
+- tmux CHANGES 3.0: "Hooks are now stored in the options tree as array options"
+"""
+
+from __future__ import annotations
+
+import typing as t
+
+import pytest
+
+from libtmux._internal.sparse_array import SparseArray
+from libtmux.common import has_gte_version, has_lt_version
+
+if t.TYPE_CHECKING:
+    from libtmux.server import Server
+
+
+class TestSetHooksVersionWarning:
+    """Test set_hooks warning on tmux < 3.0."""
+
+    @pytest.mark.skipif(
+        has_gte_version("3.0"),
+        reason="Warning only emitted on tmux < 3.0",
+    )
+    def test_set_hooks_warns_on_old_tmux(self, server: Server) -> None:
+        """Verify set_hooks emits warning on tmux < 3.0.
+
+        On tmux < 3.0, hook arrays don't exist. The bracket syntax creates
+        hooks with literal names like "session-renamed[0]" instead of array
+        indices. This test verifies the warning is raised to alert users.
+        """
+        session = server.new_session(session_name="test_warn")
+
+        with pytest.warns(
+            UserWarning,
+            match=r"Hook arrays require tmux 3\.0\+",
+        ):
+            session.set_hooks("session-renamed", {0: "display-message 'test'"})
+
+    @pytest.mark.skipif(
+        has_lt_version("3.0"),
+        reason="Test requires tmux 3.0+ for proper array hook support",
+    )
+    def test_set_hooks_no_warning_on_new_tmux(
+        self,
+        server: Server,
+        recwarn: pytest.WarningsRecorder,
+    ) -> None:
+        """Verify set_hooks does NOT warn on tmux 3.0+.
+
+        On tmux 3.0+, hooks are proper array options. No warning should be
+        emitted when using set_hooks.
+        """
+        session = server.new_session(session_name="test_no_warn")
+
+        # Call set_hooks - should not emit any warnings on 3.0+
+        session.set_hooks("session-renamed", {0: "display-message 'test'"})
+
+        # Filter for our specific warning (ignore other warnings)
+        hook_warnings = [
+            w for w in recwarn if "Hook arrays require tmux" in str(w.message)
+        ]
+        assert len(hook_warnings) == 0, "Should not warn on tmux 3.0+"
+
+        # Cleanup
+        session.unset_hook("session-renamed")
+
+
+class TestSetHooksArrayBehavior:
+    """Test set_hooks array behavior on tmux 3.0+."""
+
+    @pytest.mark.skipif(
+        has_lt_version("3.0"),
+        reason="Hook arrays require tmux 3.0+",
+    )
+    def test_set_hooks_creates_array_indices(self, server: Server) -> None:
+        """Verify set_hooks creates proper array indices on tmux 3.0+.
+
+        On tmux 3.0+, set_hooks should create hooks as array indices that can
+        be queried with show_hook and cleared with unset_hook.
+        """
+        session = server.new_session(session_name="test_array")
+
+        # Suppress warning in case test runs on < 3.0 (though it's skipped)
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            session.set_hooks(
+                "session-renamed",
+                {
+                    0: 'display-message "hook 0"',
+                    1: 'display-message "hook 1"',
+                },
+            )
+
+        # Verify hooks were created as array
+        hooks = session.show_hook("session-renamed")
+        assert hooks is not None
+        assert isinstance(hooks, SparseArray)
+        assert sorted(hooks.keys()) == [0, 1]
+
+        # Cleanup
+        session.unset_hook("session-renamed")
+
+    @pytest.mark.skipif(
+        has_lt_version("3.0"),
+        reason="Hook arrays require tmux 3.0+",
+    )
+    def test_set_hooks_clear_existing(self, server: Server) -> None:
+        """Verify clear_existing=True clears all indices on tmux 3.0+.
+
+        On tmux 3.0+, unset_hook('hook-name') clears all array indices.
+        The clear_existing parameter uses this to replace all existing hooks.
+        """
+        session = server.new_session(session_name="test_clear")
+
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            # Set initial hooks
+            session.set_hooks(
+                "session-renamed",
+                {0: 'display-message "old 0"', 1: 'display-message "old 1"'},
+            )
+
+            # Verify initial hooks
+            hooks = session.show_hook("session-renamed")
+            assert hooks is not None
+            assert isinstance(hooks, SparseArray)
+            assert sorted(hooks.keys()) == [0, 1]
+
+            # Replace with new hooks using clear_existing
+            session.set_hooks(
+                "session-renamed",
+                {0: 'display-message "new"'},
+                clear_existing=True,
+            )
+
+        # Verify only new hook exists
+        hooks_after = session.show_hook("session-renamed")
+        assert hooks_after is not None
+        assert isinstance(hooks_after, SparseArray)
+        assert sorted(hooks_after.keys()) == [0]
+
+        # Cleanup
+        session.unset_hook("session-renamed")
+
+    @pytest.mark.skipif(
+        has_lt_version("3.0"),
+        reason="Hook arrays require tmux 3.0+",
+    )
+    def test_set_hooks_from_list(self, server: Server) -> None:
+        """Verify set_hooks accepts list input on tmux 3.0+.
+
+        Lists are converted to dicts with sequential indices starting at 0.
+        """
+        session = server.new_session(session_name="test_list")
+
+        import warnings
+
+        with warnings.catch_warnings():
+            warnings.simplefilter("ignore")
+            session.set_hooks(
+                "after-new-window",
+                [
+                    "select-pane -t 0",
+                    'send-keys "clear" Enter',
+                ],
+            )
+
+        hooks = session.show_hook("after-new-window")
+        assert hooks is not None
+        assert isinstance(hooks, SparseArray)
+        assert sorted(hooks.keys()) == [0, 1]
+
+        # Cleanup
+        session.unset_hook("after-new-window")

From ef284a5d0d629cec80f8f9836e3f24199e9e109f Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 16:24:45 -0600
Subject: [PATCH 069/136] hooks(fix): remove < 3.0 warning and doctest skips

why: tmux < 3.2 is now deprecated (TMUX_SOFT_MIN_VERSION = "3.2a").
Hook arrays were introduced in tmux 3.0, so the compatibility
warning and doctest skips are no longer needed.

what:
- Remove warnings.warn() block for tmux < 3.0 in set_hooks
- Remove # doctest: +SKIP from all set_hooks examples
- Doctests now run on all supported tmux versions
---
 src/libtmux/hooks.py | 36 ++++++++++++------------------------
 1 file changed, 12 insertions(+), 24 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index fe2b74386..7f42d520b 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -439,62 +439,50 @@ def set_hooks(
         --------
         Set hooks with explicit indices:
 
-        >>> session.set_hooks('session-renamed', {  # doctest: +SKIP
+        >>> session.set_hooks('session-renamed', {
         ...     0: 'display-message "hook 0"',
         ...     1: 'display-message "hook 1"',
         ... })
         Session($...)
 
-        >>> hooks = session.show_hook('session-renamed')  # doctest: +SKIP
-        >>> sorted(hooks.keys())  # doctest: +SKIP
+        >>> hooks = session.show_hook('session-renamed')
+        >>> sorted(hooks.keys())
         [0, 1]
 
-        >>> session.unset_hook('session-renamed')  # doctest: +SKIP
+        >>> session.unset_hook('session-renamed')
         Session($...)
 
         Set hooks from a list (sequential indices):
 
-        >>> session.set_hooks('after-new-window', [  # doctest: +SKIP
+        >>> session.set_hooks('after-new-window', [
         ...     'select-pane -t 0',
         ...     'send-keys "clear" Enter',
         ... ])
         Session($...)
 
-        >>> hooks = session.show_hook('after-new-window')  # doctest: +SKIP
-        >>> sorted(hooks.keys())  # doctest: +SKIP
+        >>> hooks = session.show_hook('after-new-window')
+        >>> sorted(hooks.keys())
         [0, 1]
 
         Replace all existing hooks with ``clear_existing=True``:
 
-        >>> session.set_hooks(  # doctest: +SKIP
+        >>> session.set_hooks(
         ...     'session-renamed',
         ...     {0: 'display-message "new"'},
         ...     clear_existing=True,
         ... )
         Session($...)
 
-        >>> hooks = session.show_hook('session-renamed')  # doctest: +SKIP
-        >>> sorted(hooks.keys())  # doctest: +SKIP
+        >>> hooks = session.show_hook('session-renamed')
+        >>> sorted(hooks.keys())
         [0]
 
-        >>> session.unset_hook('session-renamed')  # doctest: +SKIP
+        >>> session.unset_hook('session-renamed')
         Session($...)
 
-        >>> session.unset_hook('after-new-window')  # doctest: +SKIP
+        >>> session.unset_hook('after-new-window')
         Session($...)
         """
-        # Hook arrays require tmux 3.0+. On older versions, hooks are stored
-        # by exact name (e.g. "session-renamed[0]" is a literal name, not an
-        # array index). See tmux commit dfb7bb68 (April 2019).
-        if has_lt_version("3.0"):
-            warnings.warn(
-                "Hook arrays require tmux 3.0+. "
-                "On older versions, set_hooks creates hooks with literal bracket "
-                "names (e.g. 'session-renamed[0]') instead of array indices, "
-                "and clear_existing/unset_hook may not work as expected.",
-                stacklevel=2,
-            )
-
         if clear_existing:
             self.unset_hook(hook, global_=global_, scope=scope)
 

From a59b181f1e22ae20913624df4a288c270e05a9d3 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 16:25:31 -0600
Subject: [PATCH 070/136] tests(hooks): remove < 3.0 module skip

why: tmux < 3.2 is now deprecated. The module-level skip for
tmux < 3.0 is no longer needed since all supported versions
have hook array support.

what:
- Remove module-level pytest.skip for has_lt_version("3.0")
- Remove unused has_lt_version import
---
 tests/test_hooks.py | 8 +-------
 1 file changed, 1 insertion(+), 7 deletions(-)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 968324c7b..e23f50de2 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -8,17 +8,11 @@
 
 from libtmux._internal.constants import Hooks
 from libtmux._internal.sparse_array import SparseArray
-from libtmux.common import has_gte_version, has_lt_version
+from libtmux.common import has_gte_version
 
 if t.TYPE_CHECKING:
     from libtmux.server import Server
 
-if has_lt_version("3.0"):
-    pytest.skip(
-        reason="only support hooks in tmux 3.0 and above",
-        allow_module_level=True,
-    )
-
 
 def test_hooks_raw_cmd(
     server: Server,

From 881fa39a6b24789d106ef450a27306d9487debdd Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 16:25:43 -0600
Subject: [PATCH 071/136] tests(hooks): delete version compat test file

why: tmux < 3.2 is now deprecated. The test_hooks_compat.py file
contained tests for < 3.0 vs 3.0+ behavior differences, which are
no longer relevant since all supported versions have hook arrays.

what:
- Delete tests/test_hooks_compat.py entirely
---
 tests/test_hooks_compat.py | 203 -------------------------------------
 1 file changed, 203 deletions(-)
 delete mode 100644 tests/test_hooks_compat.py

diff --git a/tests/test_hooks_compat.py b/tests/test_hooks_compat.py
deleted file mode 100644
index 35dd0ed7e..000000000
--- a/tests/test_hooks_compat.py
+++ /dev/null
@@ -1,203 +0,0 @@
-"""Tests for hook version compatibility.
-
-This module tests hook behavior differences between tmux < 3.0 and tmux 3.0+.
-
-tmux Hook Architecture Changes (3.0)
-------------------------------------
-Prior to tmux 3.0, hooks were stored in a red-black tree by exact name.
-Setting "session-renamed[0]" created a hook with that literal name (including
-brackets). The ``set-hook -u session-renamed`` command only removed a hook
-named exactly "session-renamed", NOT "session-renamed[0]".
-
-In tmux 3.0 (commit dfb7bb68, April 2019), hooks were merged into the options
-tree as array options. Now "session-renamed[0]" is index 0 of the
-"session-renamed" array, and ``set-hook -u session-renamed`` clears all
-indices of that array.
-
-This difference means that:
-- On tmux < 3.0: ``set_hooks()`` creates hooks with literal bracket names
-- On tmux < 3.0: ``unset_hook('session-renamed')`` does NOT clear indexed hooks
-- On tmux 3.0+: ``set_hooks()`` properly creates array entries
-- On tmux 3.0+: ``unset_hook('session-renamed')`` clears all array indices
-
-References
-----------
-- tmux commit: dfb7bb68 (April 26, 2019)
-- tmux CHANGES 3.0: "Hooks are now stored in the options tree as array options"
-"""
-
-from __future__ import annotations
-
-import typing as t
-
-import pytest
-
-from libtmux._internal.sparse_array import SparseArray
-from libtmux.common import has_gte_version, has_lt_version
-
-if t.TYPE_CHECKING:
-    from libtmux.server import Server
-
-
-class TestSetHooksVersionWarning:
-    """Test set_hooks warning on tmux < 3.0."""
-
-    @pytest.mark.skipif(
-        has_gte_version("3.0"),
-        reason="Warning only emitted on tmux < 3.0",
-    )
-    def test_set_hooks_warns_on_old_tmux(self, server: Server) -> None:
-        """Verify set_hooks emits warning on tmux < 3.0.
-
-        On tmux < 3.0, hook arrays don't exist. The bracket syntax creates
-        hooks with literal names like "session-renamed[0]" instead of array
-        indices. This test verifies the warning is raised to alert users.
-        """
-        session = server.new_session(session_name="test_warn")
-
-        with pytest.warns(
-            UserWarning,
-            match=r"Hook arrays require tmux 3\.0\+",
-        ):
-            session.set_hooks("session-renamed", {0: "display-message 'test'"})
-
-    @pytest.mark.skipif(
-        has_lt_version("3.0"),
-        reason="Test requires tmux 3.0+ for proper array hook support",
-    )
-    def test_set_hooks_no_warning_on_new_tmux(
-        self,
-        server: Server,
-        recwarn: pytest.WarningsRecorder,
-    ) -> None:
-        """Verify set_hooks does NOT warn on tmux 3.0+.
-
-        On tmux 3.0+, hooks are proper array options. No warning should be
-        emitted when using set_hooks.
-        """
-        session = server.new_session(session_name="test_no_warn")
-
-        # Call set_hooks - should not emit any warnings on 3.0+
-        session.set_hooks("session-renamed", {0: "display-message 'test'"})
-
-        # Filter for our specific warning (ignore other warnings)
-        hook_warnings = [
-            w for w in recwarn if "Hook arrays require tmux" in str(w.message)
-        ]
-        assert len(hook_warnings) == 0, "Should not warn on tmux 3.0+"
-
-        # Cleanup
-        session.unset_hook("session-renamed")
-
-
-class TestSetHooksArrayBehavior:
-    """Test set_hooks array behavior on tmux 3.0+."""
-
-    @pytest.mark.skipif(
-        has_lt_version("3.0"),
-        reason="Hook arrays require tmux 3.0+",
-    )
-    def test_set_hooks_creates_array_indices(self, server: Server) -> None:
-        """Verify set_hooks creates proper array indices on tmux 3.0+.
-
-        On tmux 3.0+, set_hooks should create hooks as array indices that can
-        be queried with show_hook and cleared with unset_hook.
-        """
-        session = server.new_session(session_name="test_array")
-
-        # Suppress warning in case test runs on < 3.0 (though it's skipped)
-        import warnings
-
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            session.set_hooks(
-                "session-renamed",
-                {
-                    0: 'display-message "hook 0"',
-                    1: 'display-message "hook 1"',
-                },
-            )
-
-        # Verify hooks were created as array
-        hooks = session.show_hook("session-renamed")
-        assert hooks is not None
-        assert isinstance(hooks, SparseArray)
-        assert sorted(hooks.keys()) == [0, 1]
-
-        # Cleanup
-        session.unset_hook("session-renamed")
-
-    @pytest.mark.skipif(
-        has_lt_version("3.0"),
-        reason="Hook arrays require tmux 3.0+",
-    )
-    def test_set_hooks_clear_existing(self, server: Server) -> None:
-        """Verify clear_existing=True clears all indices on tmux 3.0+.
-
-        On tmux 3.0+, unset_hook('hook-name') clears all array indices.
-        The clear_existing parameter uses this to replace all existing hooks.
-        """
-        session = server.new_session(session_name="test_clear")
-
-        import warnings
-
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            # Set initial hooks
-            session.set_hooks(
-                "session-renamed",
-                {0: 'display-message "old 0"', 1: 'display-message "old 1"'},
-            )
-
-            # Verify initial hooks
-            hooks = session.show_hook("session-renamed")
-            assert hooks is not None
-            assert isinstance(hooks, SparseArray)
-            assert sorted(hooks.keys()) == [0, 1]
-
-            # Replace with new hooks using clear_existing
-            session.set_hooks(
-                "session-renamed",
-                {0: 'display-message "new"'},
-                clear_existing=True,
-            )
-
-        # Verify only new hook exists
-        hooks_after = session.show_hook("session-renamed")
-        assert hooks_after is not None
-        assert isinstance(hooks_after, SparseArray)
-        assert sorted(hooks_after.keys()) == [0]
-
-        # Cleanup
-        session.unset_hook("session-renamed")
-
-    @pytest.mark.skipif(
-        has_lt_version("3.0"),
-        reason="Hook arrays require tmux 3.0+",
-    )
-    def test_set_hooks_from_list(self, server: Server) -> None:
-        """Verify set_hooks accepts list input on tmux 3.0+.
-
-        Lists are converted to dicts with sequential indices starting at 0.
-        """
-        session = server.new_session(session_name="test_list")
-
-        import warnings
-
-        with warnings.catch_warnings():
-            warnings.simplefilter("ignore")
-            session.set_hooks(
-                "after-new-window",
-                [
-                    "select-pane -t 0",
-                    'send-keys "clear" Enter',
-                ],
-            )
-
-        hooks = session.show_hook("after-new-window")
-        assert hooks is not None
-        assert isinstance(hooks, SparseArray)
-        assert sorted(hooks.keys()) == [0, 1]
-
-        # Cleanup
-        session.unset_hook("after-new-window")

From 0086e86955a8b04c5dff39ff1810477199e5ca7c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 16:30:21 -0600
Subject: [PATCH 072/136] tests: remove obsolete < 3.2 skipif markers

why: tmux < 3.2 is now deprecated (TMUX_SOFT_MIN_VERSION = "3.2a").
All version skipif markers for < 3.0, < 3.2, <= 3.1, and < 2.9 are
now obsolete since all supported tmux versions have these features.

what:
- Remove skipif(has_lt_version("3.0")) from environment tests
- Remove skipif(has_lt_version("3.2")) from window direction tests
- Remove skipif(has_lt_version("2.9")) from resize tests
- Remove skipif(has_lte_version("3.1")) from zoom tests
- Clean up unused imports (has_lt_version, has_lte_version)
---
 tests/legacy_api/test_window.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index 7935c192c..5c36d1c85 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -10,7 +10,7 @@
 import pytest
 
 from libtmux import exc
-from libtmux.common import has_gte_version, has_lt_version, has_version
+from libtmux.common import has_gte_version, has_version
 from libtmux.constants import OptionScope
 from libtmux.pane import Pane
 from libtmux.server import Server

From 79bdf0ae51ca647e97683d6f1f8d9ce9f1b4e3fa Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Fri, 28 Nov 2025 16:32:01 -0600
Subject: [PATCH 073/136] hooks(docs): update module docstring for 3.2+
 baseline

why: Minimum supported tmux version is now 3.2a, so documentation
should reflect available features rather than version warnings.
what:
- Replace "Version Compatibility" section with "Hook Features"
- Document hook arrays as baseline feature (available in 3.2+)
- Note newer features (3.3+, 3.5+) for future reference
---
 src/libtmux/hooks.py | 21 +++++++++------------
 1 file changed, 9 insertions(+), 12 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 7f42d520b..7e96abcc5 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -1,17 +1,14 @@
 """Helpers for tmux hooks.
 
-tmux Hook Version Compatibility
--------------------------------
-Hook array support requires tmux 3.0+.
-
-**tmux 3.0+**:
-- Hooks are array options (e.g., ``session-renamed[0]``, ``session-renamed[1]``)
-- Sparse indices supported (can have gaps: ``[0]``, ``[5]``, ``[10]``)
-- Session-level hooks available
-
-**tmux 3.2+**:
-- Window-level hooks via ``-w`` flag
-- Pane-level hooks via ``-p`` flag
+tmux Hook Features
+------------------
+Hooks are array options (e.g., ``session-renamed[0]``, ``session-renamed[1]``)
+with sparse index support (can have gaps: ``[0]``, ``[5]``, ``[10]``).
+
+All features available in libtmux's minimum supported version (tmux 3.2+):
+
+- Session, window, and pane-level hooks
+- Window hooks via ``-w`` flag, pane hooks via ``-p`` flag
 - Hook scope separation (session vs window vs pane)
 
 **tmux 3.3+**:

From a9f21f4f3932449918cb9f55e58d0fecf47992fe Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 06:52:26 -0600
Subject: [PATCH 074/136] SparseArray(fix[append]): Handle empty array case

why: Calling append() on an empty SparseArray crashed with ValueError
because max() on an empty sequence raises an exception.
what:
- Use max(self.keys(), default=-1) to return -1 for empty arrays
- First append now correctly adds at index 0
- Add doctest demonstrating empty array append behavior
---
 src/libtmux/_internal/sparse_array.py | 11 +++++++++--
 1 file changed, 9 insertions(+), 2 deletions(-)

diff --git a/src/libtmux/_internal/sparse_array.py b/src/libtmux/_internal/sparse_array.py
index 8b1ac54fe..6e783a226 100644
--- a/src/libtmux/_internal/sparse_array.py
+++ b/src/libtmux/_internal/sparse_array.py
@@ -125,8 +125,15 @@ def append(self, value: T) -> None:
         --------
         >>> from libtmux._internal.sparse_array import SparseArray
 
+        Appending to an empty array starts at index 0:
+
         >>> arr: SparseArray[str] = SparseArray()
-        >>> arr.add(0, "first")
+        >>> arr.append("first")
+        >>> arr[0]
+        'first'
+
+        Appending to a non-empty array adds at max index + 1:
+
         >>> arr.add(5, "at index 5")
         >>> arr.append("appended")
         >>> arr[6]
@@ -135,7 +142,7 @@ def append(self, value: T) -> None:
         >>> arr[7]
         'another'
         """
-        index = max(self.keys()) + 1
+        index = max(self.keys(), default=-1) + 1
         self[index] = value
 
     def iter_values(self) -> t.Iterator[T]:

From 421e736a04a0fdb4cc37f9900df552b85505c1e0 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 07:22:33 -0600
Subject: [PATCH 075/136] hooks(fix[show_hooks]): Store string hook values in
 returned dict

why: show_hooks() only stored values when val.isdigit() was True,
silently dropping all string hook values (the common case for tmux hooks).
what:
- Fix parsing to split on first whitespace only (handles multi-word values)
- Remove unused shlex import
- Add docstring with Parameters, Returns, and Examples sections
- Add parametrized test with NamedTuple for show_hooks string values
---
 src/libtmux/hooks.py | 49 +++++++++++++++++++++++++++++------
 tests/test_hooks.py  | 61 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 102 insertions(+), 8 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 7e96abcc5..728f47f5b 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -30,7 +30,6 @@
 from __future__ import annotations
 
 import logging
-import shlex
 import typing as t
 import warnings
 
@@ -254,7 +253,37 @@ def show_hooks(
         scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
         ignore_errors: bool | None = None,
     ) -> HookDict:
-        """Return a dict of hooks for the target."""
+        """Return a dict of hooks for the target.
+
+        Parameters
+        ----------
+        global_ : bool, optional
+            Pass ``-g`` flag for global hooks, default False.
+        scope : OptionScope | _DefaultOptionScope | None, optional
+            Hook scope (Server/Session/Window/Pane), defaults to object's scope.
+        ignore_errors : bool, optional
+            Suppress errors with ``-q`` flag.
+
+        Returns
+        -------
+        HookDict
+            Dictionary mapping hook names to their values.
+
+        Examples
+        --------
+        >>> session.set_hook('session-renamed[0]', 'display-message "test"')
+        Session($...)
+
+        >>> hooks = session.show_hooks()
+        >>> isinstance(hooks, dict)
+        True
+
+        >>> 'session-renamed[0]' in hooks
+        True
+
+        >>> session.unset_hook('session-renamed')
+        Session($...)
+        """
         if scope is DEFAULT_OPTION_SCOPE:
             scope = self.default_hook_scope
 
@@ -283,16 +312,20 @@ def show_hooks(
         output = cmd.stdout
         hooks: HookDict = {}
         for item in output:
-            try:
-                key, val = shlex.split(item)
-            except ValueError:
+            # Split on first whitespace only to handle multi-word hook values
+            parts = item.split(None, 1)
+            if len(parts) == 2:
+                key, val = parts
+            elif len(parts) == 1:
+                key, val = parts[0], None
+            else:
                 logger.warning(f"Error extracting hook: {item}")
-                key, val = item, None
-            assert isinstance(key, str)
-            assert isinstance(val, str) or val is None
+                continue
 
             if isinstance(val, str) and val.isdigit():
                 hooks[key] = int(val)
+            elif isinstance(val, str):
+                hooks[key] = val
 
         return hooks
 
diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index e23f50de2..7296564d1 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -712,3 +712,64 @@ def test_set_hook_append_flag(server: Server) -> None:
 
     # Cleanup
     session.unset_hook("session-renamed")
+
+
+# =============================================================================
+# show_hooks Tests
+# =============================================================================
+
+
+class ShowHooksTestCase(t.NamedTuple):
+    """Test case for show_hooks validation."""
+
+    test_id: str
+    hook: str
+    value: str
+    expected_value: str
+    expected_type: type
+    min_version: str = "3.2"
+
+
+SHOW_HOOKS_TEST_CASES: list[ShowHooksTestCase] = [
+    ShowHooksTestCase(
+        test_id="string_hook_value",
+        hook="session-renamed[0]",
+        value='display-message "test"',
+        expected_value="display-message test",  # tmux strips quotes in output
+        expected_type=str,
+    ),
+    ShowHooksTestCase(
+        test_id="multiple_hooks",
+        hook="session-renamed[1]",
+        value='display-message "another"',
+        expected_value="display-message another",  # tmux strips quotes in output
+        expected_type=str,
+    ),
+]
+
+
+def _build_show_hooks_params() -> list[t.Any]:
+    """Build pytest params for show_hooks tests."""
+    return [pytest.param(tc, id=tc.test_id) for tc in SHOW_HOOKS_TEST_CASES]
+
+
+@pytest.mark.parametrize("test_case", _build_show_hooks_params())
+def test_show_hooks_stores_string_values(
+    server: Server,
+    test_case: ShowHooksTestCase,
+) -> None:
+    """Test that show_hooks() correctly stores string hook values."""
+    if not has_gte_version(test_case.min_version):
+        pytest.skip(f"Requires tmux >= {test_case.min_version}")
+
+    session = server.new_session(session_name="test_show_hooks")
+
+    session.set_hook(test_case.hook, test_case.value)
+    hooks = session.show_hooks()
+
+    assert test_case.hook in hooks
+    assert isinstance(hooks[test_case.hook], test_case.expected_type)
+    assert hooks[test_case.hook] == test_case.expected_value
+
+    # Cleanup
+    session.unset_hook(test_case.hook.split("[")[0])

From a2c0b30455922c4ceae6cd485f167e0b5373f670 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 07:36:42 -0600
Subject: [PATCH 076/136] options(feat[show_options]): Add public
 show_options() method

why: CHANGES documented Window.show_options() as replacement for
show_window_options(), but only private _show_options() existed.
what:
- Add show_options() public method to OptionsMixin as thin wrapper
- Add doctest examples for show_options()
---
 src/libtmux/options.py | 46 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 46 insertions(+)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index 5d0441fc9..a5c81c047 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -939,6 +939,52 @@ def _show_options(
 
         return t.cast("ExplodedComplexUntypedOptionsDict", output_exploded)
 
+    def show_options(
+        self,
+        global_: bool = False,
+        scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
+        include_hooks: bool | None = None,
+        include_inherited: bool | None = None,
+    ) -> ExplodedComplexUntypedOptionsDict:
+        """Return all options for the target.
+
+        Parameters
+        ----------
+        global_ : bool, optional
+            Pass ``-g`` flag for global options, default False.
+        scope : OptionScope | _DefaultOptionScope | None, optional
+            Option scope (Server/Session/Window/Pane), defaults to object's scope.
+        include_hooks : bool, optional
+            Include hook options (``-H`` flag).
+        include_inherited : bool, optional
+            Include inherited options (``-A`` flag).
+
+        Returns
+        -------
+        ExplodedComplexUntypedOptionsDict
+            Dictionary with all options, arrays exploded and values converted.
+
+        Raises
+        ------
+        :exc:`exc.OptionError`, :exc:`exc.UnknownOption`,
+        :exc:`exc.InvalidOption`, :exc:`exc.AmbiguousOption`
+
+        Examples
+        --------
+        >>> options = server.show_options()
+        >>> isinstance(options, dict)
+        True
+
+        >>> 'buffer-limit' in options
+        True
+        """
+        return self._show_options(
+            global_=global_,
+            scope=scope,
+            include_hooks=include_hooks,
+            include_inherited=include_inherited,
+        )
+
     def _show_option_raw(
         self,
         option: str,

From 3ba80175e657bbce339cd6f940e21f848cc438ee Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 07:36:50 -0600
Subject: [PATCH 077/136] Window(refactor[show_window_options]): Update
 deprecation to use show_options()

why: Deprecation message incorrectly pointed to private _show_options().
what:
- Update docstring to reference public Window.show_options()
- Update implementation to call show_options() instead of _show_options()
---
 src/libtmux/window.py | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index b36d1d40c..8cc9dee82 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -875,11 +875,11 @@ def set_window_option(
         return self.set_option(option=option, value=value)
 
     def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
-        """Show options for tmux window. Deprecated by :meth:`Window._show_options()`.
+        """Show options for tmux window. Deprecated by :meth:`Window.show_options()`.
 
         .. deprecated:: 0.26
 
-           Deprecated by :meth:`Window._show_options()`.
+           Deprecated by :meth:`Window.show_options()`.
 
         """
         warnings.warn(
@@ -887,8 +887,8 @@ def show_window_options(self, g: bool | None = False) -> WindowOptionDict:
             category=DeprecationWarning,
             stacklevel=2,
         )
-        return self._show_options(
-            g=g,
+        return self.show_options(
+            global_=g or False,
             scope=OptionScope.Window,
         )
 

From 6b8995c82ddd97e8eb15aa45f4009d3cc5339260 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 08:16:36 -0600
Subject: [PATCH 078/136] options(fix[scope_flag]): Skip empty Session scope
 flag in tmux commands

why: When explicitly passing scope=OptionScope.Session, the empty string
from OPTION_SCOPE_FLAG_MAP was added as an argument, causing tmux
"ambiguous option" error. tmux interprets no scope flag as session scope.
what:
- Check if scope_flag is truthy before adding to flags (4 locations)
- Fixes set_option, unset_option, _show_options_raw, _show_option_raw
---
 src/libtmux/options.py | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index a5c81c047..c5b6d99da 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -676,9 +676,9 @@ def set_option(
 
         if scope is not None and not isinstance(scope, _DefaultOptionScope):
             assert scope in OPTION_SCOPE_FLAG_MAP
-            flags.append(
-                OPTION_SCOPE_FLAG_MAP[scope],
-            )
+            scope_flag = OPTION_SCOPE_FLAG_MAP[scope]
+            if scope_flag:  # Session scope has empty string, skip it
+                flags.append(scope_flag)
 
         cmd = self.cmd(
             "set-option",
@@ -764,9 +764,9 @@ def unset_option(
 
         if scope is not None and not isinstance(scope, _DefaultOptionScope):
             assert scope in OPTION_SCOPE_FLAG_MAP
-            flags.append(
-                OPTION_SCOPE_FLAG_MAP[scope],
-            )
+            scope_flag = OPTION_SCOPE_FLAG_MAP[scope]
+            if scope_flag:  # Session scope has empty string, skip it
+                flags.append(scope_flag)
 
         cmd = self.cmd(
             "set-option",
@@ -830,7 +830,9 @@ def _show_options_raw(
 
         if scope is not None and not isinstance(scope, _DefaultOptionScope):
             assert scope in OPTION_SCOPE_FLAG_MAP
-            flags += (OPTION_SCOPE_FLAG_MAP[scope],)
+            scope_flag = OPTION_SCOPE_FLAG_MAP[scope]
+            if scope_flag:  # Session scope has empty string, skip it
+                flags += (scope_flag,)
 
         if include_inherited is not None and include_inherited:
             flags += ("-A",)
@@ -1053,7 +1055,9 @@ def _show_option_raw(
 
         if scope is not None and not isinstance(scope, _DefaultOptionScope):
             assert scope in OPTION_SCOPE_FLAG_MAP
-            flags += (OPTION_SCOPE_FLAG_MAP[scope],)
+            scope_flag = OPTION_SCOPE_FLAG_MAP[scope]
+            if scope_flag:  # Session scope has empty string, skip it
+                flags += (scope_flag,)
 
         if ignore_errors is not None and ignore_errors:
             flags += ("-q",)

From 6681e75b91343ba7123290670e99ace629e7b709 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 08:16:49 -0600
Subject: [PATCH 079/136] tests(test_options[show_options]): Add parametrized
 tests for show_options()

why: Verify show_options() returns expected keys at all scopes with
global and inherited variations.
what:
- Add ShowOptionsTestCase NamedTuple with test_id pattern
- Add expected keys for Server, Session, Window scopes
- Add 6 parametrized test cases covering scope/global/inherited combos
- Tests verify specific option keys exist in returned dict
---
 tests/test_options.py | 108 ++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 108 insertions(+)

diff --git a/tests/test_options.py b/tests/test_options.py
index 3aaa3c6e3..398bb5fe1 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -1090,3 +1090,111 @@ def test_option_set_show_cycle(server: Server, test_case: OptionTestCase) -> Non
     assert isinstance(result, test_case.expected_type), (
         f"Expected {test_case.expected_type.__name__}, got {type(result).__name__}"
     )
+
+
+# =============================================================================
+# show_options Tests
+# =============================================================================
+
+# Scope-specific expected keys (verified with global_=True)
+SERVER_EXPECTED_KEYS = ["buffer-limit", "escape-time", "exit-empty", "focus-events"]
+SESSION_EXPECTED_KEYS = ["base-index", "history-limit", "status"]
+WINDOW_EXPECTED_KEYS = ["mode-keys", "pane-base-index", "automatic-rename"]
+
+
+class ShowOptionsTestCase(t.NamedTuple):
+    """Test case for show_options validation."""
+
+    test_id: str
+    scope: OptionScope
+    expected_keys: list[str]
+    global_: bool = False
+    include_inherited: bool = False
+    min_version: str = "3.2"
+
+
+SHOW_OPTIONS_TEST_CASES: list[ShowOptionsTestCase] = [
+    # Server scope tests
+    ShowOptionsTestCase(
+        test_id="server_global",
+        scope=OptionScope.Server,
+        expected_keys=SERVER_EXPECTED_KEYS,
+        global_=True,
+    ),
+    ShowOptionsTestCase(
+        test_id="server_global_inherited",
+        scope=OptionScope.Server,
+        expected_keys=SERVER_EXPECTED_KEYS,
+        global_=True,
+        include_inherited=True,
+    ),
+    # Session scope tests (require global_=True for defaults)
+    ShowOptionsTestCase(
+        test_id="session_global",
+        scope=OptionScope.Session,
+        expected_keys=SESSION_EXPECTED_KEYS,
+        global_=True,
+    ),
+    ShowOptionsTestCase(
+        test_id="session_global_inherited",
+        scope=OptionScope.Session,
+        expected_keys=SESSION_EXPECTED_KEYS,
+        global_=True,
+        include_inherited=True,
+    ),
+    # Window scope tests
+    ShowOptionsTestCase(
+        test_id="window_global",
+        scope=OptionScope.Window,
+        expected_keys=WINDOW_EXPECTED_KEYS,
+        global_=True,
+    ),
+    ShowOptionsTestCase(
+        test_id="window_global_inherited",
+        scope=OptionScope.Window,
+        expected_keys=WINDOW_EXPECTED_KEYS,
+        global_=True,
+        include_inherited=True,
+    ),
+]
+
+
+def _build_show_options_params() -> list[t.Any]:
+    """Build pytest params for show_options tests."""
+    return [pytest.param(tc, id=tc.test_id) for tc in SHOW_OPTIONS_TEST_CASES]
+
+
+@pytest.mark.parametrize("test_case", _build_show_options_params())
+def test_show_options_returns_expected_keys(
+    server: Server,
+    test_case: ShowOptionsTestCase,
+) -> None:
+    """Test that show_options() returns dict with expected scope-specific keys."""
+    if not has_gte_version(test_case.min_version):
+        pytest.skip(f"Requires tmux >= {test_case.min_version}")
+
+    session = server.new_session(session_name="test_show_options")
+    window = session.active_window
+    pane = window.active_pane
+    assert pane is not None
+
+    # Use server for all scopes (matches test_options_grid pattern)
+    options = server.show_options(
+        global_=test_case.global_,
+        scope=test_case.scope,
+        include_inherited=test_case.include_inherited,
+    )
+
+    assert isinstance(options, dict)
+    assert len(options) > 0, (
+        f"Expected non-empty dict for scope={test_case.scope.name}, "
+        f"global_={test_case.global_}"
+    )
+
+    # Verify expected keys exist (with or without * suffix for inherited)
+    for key in test_case.expected_keys:
+        # Check for key or key* (inherited marker)
+        assert key in options or f"{key}*" in options, (
+            f"Expected '{key}' in {test_case.scope.name} options, "
+            f"got keys: {list(options.keys())[:10]}..."
+        )

From 1f34b31eb01cb2cfc08d6dcbc43fb18a4da0dabc Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 08:25:08 -0600
Subject: [PATCH 080/136] tests(test_hooks[run_hook]): Add test for run_hook()
 method

why: Improve code coverage for hooks.py run_hook method.
what:
- Add test_run_hook_basic to verify run_hook() executes without error
- Test verifies method returns self for chaining
---
 tests/test_hooks.py | 25 +++++++++++++++++++++++++
 1 file changed, 25 insertions(+)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 7296564d1..943d4edf1 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -773,3 +773,28 @@ def test_show_hooks_stores_string_values(
 
     # Cleanup
     session.unset_hook(test_case.hook.split("[")[0])
+
+
+# =============================================================================
+# run_hook Tests
+# =============================================================================
+
+
+def test_run_hook_basic(server: Server) -> None:
+    """Test run_hook() method exists and can be called without error."""
+    if not has_gte_version("3.2"):
+        pytest.skip("Requires tmux >= 3.2")
+
+    session = server.new_session(session_name="test_run_hook")
+
+    # Set a hook first
+    session.set_hook("session-renamed[0]", 'display-message "test"')
+
+    # Run the hook immediately - should not raise
+    result = session.run_hook("session-renamed[0]")
+
+    # Verify returns self for chaining
+    assert result is session
+
+    # Cleanup
+    session.unset_hook("session-renamed")

From 7d344e7dce2167ef23ffbe8dbfe6760cb81d9154 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 08:25:14 -0600
Subject: [PATCH 081/136] tests(test_sparse_array): Add tests for SparseArray
 utility class

why: Improve code coverage for sparse_array module.
what:
- Add tests for is_sparse_array_list TypeGuard function
- Add tests for SparseArray.append method
- Add tests for SparseArray.iter_values method
- Add tests for SparseArray.as_list method
---
 tests/test/test_sparse_array.py | 148 ++++++++++++++++++++++++++++++++
 1 file changed, 148 insertions(+)
 create mode 100644 tests/test/test_sparse_array.py

diff --git a/tests/test/test_sparse_array.py b/tests/test/test_sparse_array.py
new file mode 100644
index 000000000..194079d9d
--- /dev/null
+++ b/tests/test/test_sparse_array.py
@@ -0,0 +1,148 @@
+"""Tests for libtmux sparse array utilities."""
+
+from __future__ import annotations
+
+import typing as t
+
+import pytest
+
+from libtmux._internal.sparse_array import SparseArray, is_sparse_array_list
+
+
+class IsSparseArrayListTestCase(t.NamedTuple):
+    """Test case for is_sparse_array_list TypeGuard function."""
+
+    test_id: str
+    input_dict: dict[str, t.Any]
+    expected: bool
+
+
+class SparseArrayAppendTestCase(t.NamedTuple):
+    """Test case for SparseArray.append method."""
+
+    test_id: str
+    initial_adds: list[tuple[int, str]]  # [(index, value), ...] to setup
+    append_values: list[str]  # values to append
+    expected_keys: list[int]  # expected keys in sorted order
+    expected_mapping: dict[int, str]  # specific index -> value checks
+
+
+class SparseArrayValuesTestCase(t.NamedTuple):
+    """Test case for iter_values and as_list methods."""
+
+    test_id: str
+    adds: list[tuple[int, str]]  # [(index, value), ...]
+    expected_values: list[str]  # values in sorted index order
+
+
+IS_SPARSE_ARRAY_LIST_TEST_CASES: list[IsSparseArrayListTestCase] = [
+    IsSparseArrayListTestCase("empty_dict", {}, True),
+    IsSparseArrayListTestCase(
+        "sparse_arrays_only",
+        {"hook1": SparseArray(), "hook2": SparseArray()},
+        True,
+    ),
+    IsSparseArrayListTestCase(
+        "mixed_values",
+        {"hook1": SparseArray(), "opt": "string"},
+        False,
+    ),
+    IsSparseArrayListTestCase(
+        "strings_only",
+        {"key1": "val1", "key2": "val2"},
+        False,
+    ),
+    IsSparseArrayListTestCase("none_value", {"key1": None}, False),
+]
+
+SPARSE_ARRAY_APPEND_TEST_CASES: list[SparseArrayAppendTestCase] = [
+    SparseArrayAppendTestCase(
+        "append_to_empty",
+        initial_adds=[],
+        append_values=["first"],
+        expected_keys=[0],
+        expected_mapping={0: "first"},
+    ),
+    SparseArrayAppendTestCase(
+        "append_after_add",
+        initial_adds=[(5, "at five")],
+        append_values=["appended"],
+        expected_keys=[5, 6],
+        expected_mapping={5: "at five", 6: "appended"},
+    ),
+    SparseArrayAppendTestCase(
+        "multiple_appends",
+        initial_adds=[],
+        append_values=["100", "200", "300"],
+        expected_keys=[0, 1, 2],
+        expected_mapping={0: "100", 1: "200", 2: "300"},
+    ),
+]
+
+SPARSE_ARRAY_VALUES_TEST_CASES: list[SparseArrayValuesTestCase] = [
+    SparseArrayValuesTestCase(
+        "sorted_order",
+        adds=[(10, "ten"), (1, "one"), (5, "five")],
+        expected_values=["one", "five", "ten"],
+    ),
+    SparseArrayValuesTestCase(
+        "empty",
+        adds=[],
+        expected_values=[],
+    ),
+    SparseArrayValuesTestCase(
+        "consecutive",
+        adds=[(3, "three"), (1, "one"), (2, "two")],
+        expected_values=["one", "two", "three"],
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in IS_SPARSE_ARRAY_LIST_TEST_CASES],
+)
+def test_is_sparse_array_list(test_case: IsSparseArrayListTestCase) -> None:
+    """Test is_sparse_array_list TypeGuard function."""
+    result = is_sparse_array_list(test_case.input_dict)
+    assert result is test_case.expected
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in SPARSE_ARRAY_APPEND_TEST_CASES],
+)
+def test_sparse_array_append(test_case: SparseArrayAppendTestCase) -> None:
+    """Test SparseArray.append method."""
+    arr: SparseArray[str] = SparseArray()
+    for index, value in test_case.initial_adds:
+        arr.add(index, value)
+    for value in test_case.append_values:
+        arr.append(value)
+    assert sorted(arr.keys()) == test_case.expected_keys
+    for index, expected_value in test_case.expected_mapping.items():
+        assert arr[index] == expected_value
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in SPARSE_ARRAY_VALUES_TEST_CASES],
+)
+def test_sparse_array_iter_values(test_case: SparseArrayValuesTestCase) -> None:
+    """Test SparseArray.iter_values method."""
+    arr: SparseArray[str] = SparseArray()
+    for index, value in test_case.adds:
+        arr.add(index, value)
+    assert list(arr.iter_values()) == test_case.expected_values
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in SPARSE_ARRAY_VALUES_TEST_CASES],
+)
+def test_sparse_array_as_list(test_case: SparseArrayValuesTestCase) -> None:
+    """Test SparseArray.as_list method."""
+    arr: SparseArray[str] = SparseArray()
+    for index, value in test_case.adds:
+        arr.add(index, value)
+    assert arr.as_list() == test_case.expected_values

From 6965fa3c3972733291da6d031b82e4cfb28d3754 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 09:25:36 -0600
Subject: [PATCH 082/136] tests(test_hooks): Add set_hook flag combination
 tests

why: Increase coverage for set_hook flag parameters (-a, -g, -R)
what:
- Add SetHookFlagTestCase NamedTuple for parametrized testing
- Test append flag behavior (adds to existing hooks)
- Test global_ flag behavior (sets global hooks)
- Test run flag behavior (-R runs immediately without storing)
- Test combined append + global flags
---
 tests/test_hooks.py | 102 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 102 insertions(+)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 943d4edf1..13e8647c7 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -798,3 +798,105 @@ def test_run_hook_basic(server: Server) -> None:
 
     # Cleanup
     session.unset_hook("session-renamed")
+
+
+# =============================================================================
+# set_hook Flag Combination Tests
+# =============================================================================
+
+
+class SetHookFlagTestCase(t.NamedTuple):
+    """Test case for set_hook flag combinations."""
+
+    test_id: str
+    flag_kwargs: dict[str, t.Any]
+    expected_behavior: str  # "sets_hook", "runs_immediately", "appends", "global"
+    min_version: str = "3.2"
+
+
+SET_HOOK_FLAG_TEST_CASES: list[SetHookFlagTestCase] = [
+    SetHookFlagTestCase(
+        "append_to_existing",
+        {"append": True},
+        "appends",
+    ),
+    SetHookFlagTestCase(
+        "global_hook",
+        {"global_": True},
+        "global",
+    ),
+    SetHookFlagTestCase(
+        "run_immediately",
+        {"run": True},
+        "runs_immediately",
+    ),
+    SetHookFlagTestCase(
+        "append_and_global",
+        {"append": True, "global_": True},
+        "appends",
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in SET_HOOK_FLAG_TEST_CASES],
+)
+def test_set_hook_flag_combinations(
+    server: Server,
+    test_case: SetHookFlagTestCase,
+) -> None:
+    """Test set_hook with various flag combinations."""
+    if not has_gte_version(test_case.min_version):
+        pytest.skip(f"Requires tmux {test_case.min_version}+")
+
+    session = server.new_session(session_name="test_flags")
+
+    hook_name = "session-renamed"
+    hook_cmd = "display-message 'flag test'"
+
+    if test_case.expected_behavior == "appends":
+        # Set initial hook first
+        session.set_hook(f"{hook_name}[0]", "display-message 'initial'")
+        session.set_hook(hook_name, hook_cmd, **test_case.flag_kwargs)
+
+        # Verify append added another entry
+        if test_case.flag_kwargs.get("global_"):
+            # Use raw command for global hooks
+            result = server.cmd("show-hooks", "-g", hook_name)
+            assert result.stdout is not None
+            parsed = Hooks.from_stdout(result.stdout)
+        else:
+            hooks = session._show_hook(hook_name)
+            assert hooks is not None
+            parsed = Hooks.from_stdout(hooks)
+
+        hook_values = parsed.session_renamed.as_list()
+        assert len(hook_values) >= 1
+
+    elif test_case.expected_behavior == "global":
+        session.set_hook(f"{hook_name}[0]", hook_cmd, **test_case.flag_kwargs)
+
+        # Global hook should be visible from server with -g flag
+        result = server.cmd("show-hooks", "-g", f"{hook_name}[0]")
+        assert result.stdout is not None
+        assert len(result.stdout) > 0
+        assert "display-message" in result.stdout[0]
+
+    elif test_case.expected_behavior == "runs_immediately":
+        # The -R flag runs hook immediately WITHOUT storing
+        # So after set_hook with run=True, hook should NOT be stored
+        session.set_hook(hook_name, hook_cmd, **test_case.flag_kwargs)
+
+        # Hook should NOT be stored (run immediately and discarded)
+        hooks = session._show_hook(hook_name)
+        # Either None or empty
+        if hooks:
+            parsed = Hooks.from_stdout(hooks)
+            # May be empty or have default empty entry
+            assert parsed.session_renamed is None or len(parsed.session_renamed) == 0
+
+    # Cleanup
+    session.unset_hook(hook_name)
+    if test_case.flag_kwargs.get("global_"):
+        server.cmd("set-hook", "-gu", hook_name)

From 04ecdd617e6ae09d38503deeaf0436a8f4d1541c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 09:26:17 -0600
Subject: [PATCH 083/136] tests(test_hooks): Add hook scope tests for
 session/window/pane

why: Increase coverage for scope handling in set_hook/show_hook
what:
- Add HookScopeTestCase NamedTuple for parametrized testing
- Test session-level hooks (default scope)
- Test window-level hooks (requires tmux 3.2+)
- Test pane-level hooks (requires tmux 3.2+)
---
 tests/test_hooks.py | 66 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 66 insertions(+)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 13e8647c7..f1abda42e 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -900,3 +900,69 @@ def test_set_hook_flag_combinations(
     session.unset_hook(hook_name)
     if test_case.flag_kwargs.get("global_"):
         server.cmd("set-hook", "-gu", hook_name)
+
+
+# =============================================================================
+# Hook Scope Tests
+# =============================================================================
+
+
+class HookScopeTestCase(t.NamedTuple):
+    """Test case for hook scope handling."""
+
+    test_id: str
+    scope: str  # "session", "window", "pane"
+    scope_flag: str  # tmux flag for show-hooks
+    min_version: str = "3.2"
+
+
+HOOK_SCOPE_TEST_CASES: list[HookScopeTestCase] = [
+    HookScopeTestCase("session_scope", "session", ""),
+    HookScopeTestCase("window_scope", "window", "-w", "3.2"),
+    HookScopeTestCase("pane_scope", "pane", "-p", "3.2"),
+]
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in HOOK_SCOPE_TEST_CASES],
+)
+def test_hook_scope_handling(
+    server: Server,
+    test_case: HookScopeTestCase,
+) -> None:
+    """Test hooks at different scopes (session, window, pane)."""
+    if not has_gte_version(test_case.min_version):
+        pytest.skip(f"Requires tmux {test_case.min_version}+")
+
+    session = server.new_session(session_name="test_scope")
+    window = session.active_window
+    assert window is not None
+    pane = window.active_pane
+    assert pane is not None
+
+    hook_name = "session-renamed"
+    hook_cmd = f"display-message '{test_case.scope} scope test'"
+
+    # Set hook at the appropriate scope
+    if test_case.scope == "session":
+        session.set_hook(f"{hook_name}[0]", hook_cmd)
+        result = session._show_hook(f"{hook_name}[0]")
+    elif test_case.scope == "window":
+        window.set_hook(f"{hook_name}[0]", hook_cmd)
+        result = window._show_hook(f"{hook_name}[0]")
+    else:  # pane
+        pane.set_hook(f"{hook_name}[0]", hook_cmd)
+        result = pane._show_hook(f"{hook_name}[0]")
+
+    assert result is not None
+    assert len(result) > 0
+    assert "display-message" in result[0]
+
+    # Cleanup
+    if test_case.scope == "session":
+        session.unset_hook(hook_name)
+    elif test_case.scope == "window":
+        window.unset_hook(hook_name)
+    else:
+        pane.unset_hook(hook_name)

From f5fe594827de3246d0e370e9fb1d33dc3c56035a Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 09:26:53 -0600
Subject: [PATCH 084/136] tests(test_hooks): Add show_hooks parsing edge case
 tests

why: Increase coverage for show_hooks output parsing
what:
- Add ShowHooksParseTestCase NamedTuple for parametrized testing
- Test normal single hook value parsing
- Test multiple indexed hooks (sparse indices)
- Test multiple different hook types
- Test empty result handling
---
 tests/test_hooks.py | 83 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 83 insertions(+)

diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index f1abda42e..22f93bb35 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -966,3 +966,86 @@ def test_hook_scope_handling(
         window.unset_hook(hook_name)
     else:
         pane.unset_hook(hook_name)
+
+
+# =============================================================================
+# show_hooks Parsing Edge Cases
+# =============================================================================
+
+
+class ShowHooksParseTestCase(t.NamedTuple):
+    """Test case for show_hooks output parsing edge cases."""
+
+    test_id: str
+    setup_commands: list[tuple[str, str]]  # List of (hook[idx], value) to set
+    expected_keys: list[str]  # Expected keys in result
+    check_values: bool = True  # Whether to verify specific values
+
+
+SHOW_HOOKS_PARSE_TEST_CASES: list[ShowHooksParseTestCase] = [
+    ShowHooksParseTestCase(
+        "normal_hook_value",
+        [("session-renamed[0]", "display-message 'test'")],
+        ["session-renamed[0]"],
+    ),
+    ShowHooksParseTestCase(
+        "multiple_indexed_hooks",
+        [
+            ("session-renamed[0]", "display-message 'first'"),
+            ("session-renamed[1]", "display-message 'second'"),
+            ("session-renamed[5]", "display-message 'fifth'"),
+        ],
+        ["session-renamed[0]", "session-renamed[1]", "session-renamed[5]"],
+    ),
+    ShowHooksParseTestCase(
+        "multiple_different_hooks",
+        [
+            ("session-renamed[0]", "display-message 'renamed'"),
+            ("after-split-window[0]", "display-message 'split'"),
+        ],
+        ["session-renamed[0]", "after-split-window[0]"],
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in SHOW_HOOKS_PARSE_TEST_CASES],
+)
+def test_show_hooks_parsing_edge_cases(
+    server: Server,
+    test_case: ShowHooksParseTestCase,
+) -> None:
+    """Test show_hooks parses various output formats correctly."""
+    session = server.new_session(session_name="test_parsing")
+
+    # Setup hooks
+    for hook, value in test_case.setup_commands:
+        session.set_hook(hook, value)
+
+    # Get all hooks via show_hooks
+    hooks = session.show_hooks()
+
+    # Verify expected keys are present
+    for key in test_case.expected_keys:
+        assert key in hooks, f"Expected key {key} not found in {list(hooks.keys())}"
+
+    if test_case.check_values:
+        for key in test_case.expected_keys:
+            assert hooks[key] is not None, f"Expected value for {key} to be non-None"
+
+    # Cleanup
+    for hook, _ in test_case.setup_commands:
+        base_hook = hook.split("[")[0]
+        session.unset_hook(base_hook)
+
+
+def test_show_hooks_empty_result(server: Server) -> None:
+    """Test show_hooks returns empty dict when no hooks are set."""
+    session = server.new_session(session_name="test_empty_hooks")
+
+    # Fresh session should have no session-level hooks
+    hooks = session.show_hooks()
+
+    # Should be a dict (possibly empty)
+    assert isinstance(hooks, dict)

From 62959162b043963ca41dc5931c020d1a251a0831 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 09:28:36 -0600
Subject: [PATCH 085/136] tests(test_options): Add convert_values SparseArray
 tests

why: Verify SparseArray conversion works via dict branch inheritance
what:
- Add ConvertValuesSparseTestCase NamedTuple for parametrized testing
- Test boolean on/off conversion in SparseArray
- Test numeric string conversion in SparseArray
- Test mixed value types in SparseArray
- Test sparse index preservation after conversion
---
 tests/test_options.py | 78 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 78 insertions(+)

diff --git a/tests/test_options.py b/tests/test_options.py
index 398bb5fe1..998d7b893 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -19,6 +19,7 @@
 from libtmux.common import has_gte_version
 from libtmux.constants import OptionScope
 from libtmux.exc import OptionError
+from libtmux.options import convert_values
 from libtmux.pane import Pane
 
 if t.TYPE_CHECKING:
@@ -1198,3 +1199,80 @@ def test_show_options_returns_expected_keys(
             f"Expected '{key}' in {test_case.scope.name} options, "
             f"got keys: {list(options.keys())[:10]}..."
         )
+
+
+# =============================================================================
+# convert_values Tests
+# =============================================================================
+
+
+class ConvertValuesSparseTestCase(t.NamedTuple):
+    """Test case for convert_values with SparseArray (via dict branch)."""
+
+    test_id: str
+    initial_values: dict[int, str]  # index -> value
+    expected_converted: dict[int, t.Any]  # index -> converted value
+
+
+CONVERT_SPARSE_TEST_CASES: list[ConvertValuesSparseTestCase] = [
+    ConvertValuesSparseTestCase(
+        "boolean_on_off",
+        {0: "on", 1: "off"},
+        {0: True, 1: False},
+    ),
+    ConvertValuesSparseTestCase(
+        "numeric_conversion",
+        {0: "50", 5: "100"},
+        {0: 50, 5: 100},
+    ),
+    ConvertValuesSparseTestCase(
+        "mixed_values",
+        {0: "on", 1: "50", 2: "text"},
+        {0: True, 1: 50, 2: "text"},
+    ),
+    ConvertValuesSparseTestCase(
+        "sparse_indices",
+        {0: "on", 10: "off", 100: "42"},
+        {0: True, 10: False, 100: 42},
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in CONVERT_SPARSE_TEST_CASES],
+)
+def test_convert_values_sparse_array(
+    test_case: ConvertValuesSparseTestCase,
+) -> None:
+    """Test convert_values handles SparseArray via dict branch.
+
+    Note: SparseArray inherits from dict, so the dict branch in convert_values
+    handles it correctly. This test verifies that behavior.
+    """
+    sparse: SparseArray[str] = SparseArray()
+    for idx, val in test_case.initial_values.items():
+        sparse.add(idx, val)
+
+    result = convert_values(sparse)
+
+    assert isinstance(result, SparseArray)
+    for idx, expected in test_case.expected_converted.items():
+        assert result[idx] == expected, f"Index {idx}: {result[idx]} != {expected}"
+
+
+def test_convert_values_preserves_sparse_keys() -> None:
+    """Test convert_values preserves sparse array indices."""
+    sparse: SparseArray[str] = SparseArray()
+    sparse.add(0, "on")
+    sparse.add(5, "off")
+    sparse.add(99, "100")
+
+    result = convert_values(sparse)
+
+    # Keys should be preserved
+    assert isinstance(result, SparseArray)
+    assert sorted(result.keys()) == [0, 5, 99]
+    assert result[0] is True
+    assert result[5] is False
+    assert result[99] == 100

From 277bda0db3013069fb2c0b083f7e82d5e020db97 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 09:37:55 -0600
Subject: [PATCH 086/136] tests(legacy_api/test_window): Remove duplicate
 test_set_and_show_options

why: Test was duplicating functionality already covered in tests/test_window.py
what:
- Remove test_set_and_show_options that tested NEW API in LEGACY test file
- Remove unused OptionScope import
- Same functionality tested in test_set_and_show_window_options (test_window.py:327)
---
 tests/legacy_api/test_window.py | 39 ---------------------------------
 1 file changed, 39 deletions(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index 5c36d1c85..c75371725 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -11,7 +11,6 @@
 
 from libtmux import exc
 from libtmux.common import has_gte_version, has_version
-from libtmux.constants import OptionScope
 from libtmux.pane import Pane
 from libtmux.server import Server
 from libtmux.window import Window
@@ -268,44 +267,6 @@ def test_set_window_and_show_window_options(session: Session) -> None:
     assert window.show_window_option("pane-border-format") == " #P "
 
 
-def test_set_and_show_options(session: Session) -> None:
-    """Window.set_option() then Window._show_options(key)."""
-    window = session.new_window(window_name="test_window")
-
-    window.set_option("main-pane-height", 20)
-    if has_gte_version("3.0"):
-        assert window._show_option("main-pane-height") == 20
-    else:
-        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 20
-
-    window.set_option("main-pane-height", 40)
-
-    if has_gte_version("3.0"):
-        assert window._show_option("main-pane-height") == 40
-    else:
-        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 40
-
-    # By default, show-options will session scope, even if target is a window
-    with pytest.raises(KeyError):
-        assert window._show_options(scope=OptionScope.Session)["main-pane-height"] == 40
-
-    if has_gte_version("3.0"):
-        assert window._show_option("main-pane-height") == 40
-    else:
-        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 40
-
-    if has_gte_version("2.3"):
-        window.set_option("pane-border-format", " #P ")
-
-        if has_gte_version("3.0"):
-            assert window._show_option("pane-border-format") == " #P "
-        else:
-            assert (
-                window._show_option("pane-border-format", scope=OptionScope.Window)
-                == " #P "
-            )
-
-
 def test_empty_window_option_returns_None(session: Session) -> None:
     """Verify unset window option returns None."""
     window = session.new_window(window_name="test_window")

From 0ccd7cdb251cdaa5695400dbad8e9ee0dcb61c7a Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 11:03:03 -0600
Subject: [PATCH 087/136] tests(test_window): Add deprecation warning tests for
 Window option methods

why: Verify that deprecated Window methods emit DeprecationWarning correctly
what:
- Add DeprecatedMethodTestCase NamedTuple for parametrized testing
- Add tests for set_window_option, show_window_options, show_window_option
- Test both default and global flag variations
- Use pytest.warns() to assert deprecation warnings are raised
---
 tests/test_window.py | 72 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 72 insertions(+)

diff --git a/tests/test_window.py b/tests/test_window.py
index e4bd04c43..43604f51a 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -722,3 +722,75 @@ def test_split_start_directory_pathlib(
     actual_path = str(pathlib.Path(new_pane.pane_current_path).resolve())
     expected_path = str(user_path.resolve())
     assert actual_path == expected_path
+
+
+# --- Deprecation Warning Tests ---
+
+
+class DeprecatedMethodTestCase(t.NamedTuple):
+    """Test case for deprecated method warnings."""
+
+    test_id: str
+    method_name: str  # Name of deprecated method to call
+    args: tuple[t.Any, ...]  # Positional args
+    kwargs: dict[str, t.Any]  # Keyword args
+    expected_warning_match: str  # Regex pattern to match warning message
+
+
+DEPRECATED_WINDOW_METHOD_TEST_CASES: list[DeprecatedMethodTestCase] = [
+    DeprecatedMethodTestCase(
+        test_id="set_window_option",
+        method_name="set_window_option",
+        args=("main-pane-height", 20),
+        kwargs={},
+        expected_warning_match=r"Window\.set_window_option\(\) is deprecated",
+    ),
+    DeprecatedMethodTestCase(
+        test_id="show_window_options",
+        method_name="show_window_options",
+        args=(),
+        kwargs={},
+        expected_warning_match=r"Window\.show_window_options\(\) is deprecated",
+    ),
+    DeprecatedMethodTestCase(
+        test_id="show_window_options_global",
+        method_name="show_window_options",
+        args=(),
+        kwargs={"g": True},
+        expected_warning_match=r"Window\.show_window_options\(\) is deprecated",
+    ),
+    DeprecatedMethodTestCase(
+        test_id="show_window_option",
+        method_name="show_window_option",
+        args=("main-pane-height",),
+        kwargs={},
+        expected_warning_match=r"Window\.show_window_option\(\) is deprecated",
+    ),
+    DeprecatedMethodTestCase(
+        test_id="show_window_option_global",
+        method_name="show_window_option",
+        args=("main-pane-height",),
+        kwargs={"g": True},
+        expected_warning_match=r"Window\.show_window_option\(\) is deprecated",
+    ),
+]
+
+
+def _build_deprecated_method_params() -> list[t.Any]:
+    """Build pytest params for deprecated method tests."""
+    return [
+        pytest.param(tc, id=tc.test_id) for tc in DEPRECATED_WINDOW_METHOD_TEST_CASES
+    ]
+
+
+@pytest.mark.parametrize("test_case", _build_deprecated_method_params())
+def test_deprecated_window_methods_emit_warning(
+    session: Session,
+    test_case: DeprecatedMethodTestCase,
+) -> None:
+    """Verify deprecated Window methods emit DeprecationWarning."""
+    window = session.new_window(window_name="test_deprecation")
+    method = getattr(window, test_case.method_name)
+
+    with pytest.warns(DeprecationWarning, match=test_case.expected_warning_match):
+        method(*test_case.args, **test_case.kwargs)

From cd2d14a22799473836f12a2d1d6dd881bca303f0 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 16:52:48 -0600
Subject: [PATCH 088/136] tests/legacy_api/test_window.py(refactor): Remove
 unused has_gte_version import

why: tmux >= 3.2a now required, import no longer needed after rebase
---
 tests/legacy_api/test_window.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tests/legacy_api/test_window.py b/tests/legacy_api/test_window.py
index c75371725..bd87f349c 100644
--- a/tests/legacy_api/test_window.py
+++ b/tests/legacy_api/test_window.py
@@ -10,7 +10,7 @@
 import pytest
 
 from libtmux import exc
-from libtmux.common import has_gte_version, has_version
+from libtmux.common import has_version
 from libtmux.pane import Pane
 from libtmux.server import Server
 from libtmux.window import Window

From f2b0d40a38df725084b9af0944a30f95eff236e2 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 16:52:49 -0600
Subject: [PATCH 089/136] tests/test_window.py(refactor): Simplify version
 conditionals

why: tmux >= 3.2a now required, has_gte_version checks always true
what:
- Remove has_gte_version("3.0") conditionals in test_set_and_show_window_options
- Remove has_gte_version("2.3") conditional
- Keep only the tmux 3.0+ code paths
---
 tests/test_window.py | 30 ++++++------------------------
 1 file changed, 6 insertions(+), 24 deletions(-)

diff --git a/tests/test_window.py b/tests/test_window.py
index 43604f51a..2a88a316e 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -310,37 +310,19 @@ def test_set_and_show_window_options(session: Session) -> None:
     window = session.new_window(window_name="test_window")
 
     window.set_option("main-pane-height", 20)
-    if has_gte_version("3.0"):
-        assert window._show_option("main-pane-height") == 20
-    else:
-        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 20
+    assert window._show_option("main-pane-height") == 20
 
     window.set_option("main-pane-height", 40)
-
-    if has_gte_version("3.0"):
-        assert window._show_option("main-pane-height") == 40
-    else:
-        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 40
+    assert window._show_option("main-pane-height") == 40
 
     # By default, show-options will session scope, even if target is a window
     with pytest.raises(KeyError):
         assert window._show_options(scope=OptionScope.Session)["main-pane-height"] == 40
 
-    if has_gte_version("3.0"):
-        assert window._show_option("main-pane-height") == 40
-    else:
-        assert window._show_option("main-pane-height", scope=OptionScope.Window) == 40
-
-    if has_gte_version("2.3"):
-        window.set_option("pane-border-format", " #P ")
-
-        if has_gte_version("3.0"):
-            assert window._show_option("pane-border-format") == " #P "
-        else:
-            assert (
-                window._show_option("pane-border-format", scope=OptionScope.Window)
-                == " #P "
-            )
+    assert window._show_option("main-pane-height") == 40
+
+    window.set_option("pane-border-format", " #P ")
+    assert window._show_option("pane-border-format") == " #P "
 
 
 def test_empty_window_option_returns_None(session: Session) -> None:

From 74c968166e5459344dc82605e45b5218ea16ffed Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 07:46:15 -0600
Subject: [PATCH 090/136] docs(CHANGES): Add release notes for options and
 hooks features

why: Document new OptionsMixin and HooksMixin features for 0.50.x release.
what:
- Add breaking changes for renamed Window option methods
- Document OptionsMixin with set_option, show_option, show_options, unset_option
- Document HooksMixin with set_hook, show_hook, unset_hook, set_hooks
- Document new Window.set_option() arguments
---
 CHANGES | 190 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 190 insertions(+)

diff --git a/CHANGES b/CHANGES
index 6a60334b7..b9983fec5 100644
--- a/CHANGES
+++ b/CHANGES
@@ -34,6 +34,167 @@ $ uvx --from 'libtmux' --prerelease allow python
 
 _Future release notes will be placed here_
 
+### Overview
+
+libtmux 0.50 brings a major enhancement to option and hook management. The new
+{class}`~options.OptionsMixin` and {class}`~hooks.HooksMixin` classes provide a
+unified, typed API for managing tmux options and hooks across all object types.
+
+**Highlights:**
+
+- **Unified Options API**: New `show_option()`, `show_options()`, `set_option()`,
+  and `unset_option()` methods available on Server, Session, Window, and Pane.
+- **Hook Management**: Full programmatic control over tmux hooks with support for
+  indexed hook arrays and bulk operations.
+- **SparseArray**: New internal data structure for handling tmux's sparse indexed
+  arrays (e.g., `command-alias[0]`, `command-alias[99]`).
+- **tmux 3.2+ baseline**: Removed support for tmux versions below 3.2a, enabling
+  cleaner code and full hook/option feature support.
+
+### What's New
+
+#### Unified Options API (#516)
+
+All tmux objects now share a consistent options interface through
+{class}`~options.OptionsMixin`:
+
+```python
+import libtmux
+
+server = libtmux.Server()
+session = server.sessions[0]
+window = session.windows[0]
+pane = window.panes[0]
+
+# Get all options as a structured dict
+session.show_options()
+# {'activity-action': 'other', 'base-index': 0, ...}
+
+# Get a single option value
+session.show_option('base-index')
+# 0
+
+# Set an option
+window.set_option('automatic-rename', True)
+
+# Unset an option (revert to default)
+window.unset_option('automatic-rename')
+```
+
+**New methods on Server, Session, Window, and Pane:**
+
+| Method | Description |
+|--------|-------------|
+| `show_options()` | Get all options as a structured dict |
+| `show_option(name)` | Get a single option value |
+| `set_option(name, value)` | Set an option |
+| `unset_option(name)` | Unset/remove an option |
+
+**New parameters for `set_option()`:**
+
+| Parameter | tmux flag | Description |
+|-----------|-----------|-------------|
+| `_format` | `-F` | Expand format strings in value |
+| `unset` | `-u` | Unset the option |
+| `global_` | `-g` | Set as global option |
+| `unset_panes` | `-U` | Also unset in child panes |
+| `prevent_overwrite` | `-o` | Don't overwrite if exists |
+| `suppress_warnings` | `-q` | Suppress warnings |
+| `append` | `-a` | Append to existing value |
+
+#### Hook Management (#516)
+
+New {class}`~hooks.HooksMixin` provides programmatic control over tmux hooks:
+
+```python
+session = server.sessions[0]
+
+# Set a hook
+session.set_hook('session-renamed', 'display-message "Renamed!"')
+
+# Get hook value
+session.show_hook('session-renamed')
+# 'display-message "Renamed!"'
+
+# Get all hooks
+session.show_hooks()
+# {'session-renamed': 'display-message "Renamed!"'}
+
+# Remove a hook
+session.unset_hook('session-renamed')
+```
+
+**Indexed hooks and bulk operations:**
+
+tmux hooks support multiple values via indices (e.g., `session-renamed[0]`,
+`session-renamed[1]`). The bulk operations API makes this easy:
+
+```python
+# Set multiple hooks at once
+session.set_hooks('session-renamed', {
+    0: 'display-message "Hook 0"',
+    1: 'display-message "Hook 1"',
+    5: 'run-shell "echo hook 5"',
+})
+
+# Get all indexed values for a hook
+session.get_hook_values('session-renamed')
+# SparseArray({0: 'display-message "Hook 0"', 1: '...', 5: '...'})
+
+# Get just the indices
+session.get_hook_indices('session-renamed')
+# [0, 1, 5]
+
+# Append at next available index
+session.append_hook('session-renamed', 'display-message "Hook 6"')
+
+# Clear all indexed values for a hook
+session.clear_hook('session-renamed')
+```
+
+**Hook methods available on Server, Session, Window, and Pane:**
+
+| Method | Description |
+|--------|-------------|
+| `set_hook(hook, value)` | Set a hook |
+| `show_hook(hook)` | Get hook value |
+| `show_hooks()` | Get all hooks |
+| `unset_hook(hook)` | Remove a hook |
+| `run_hook(hook)` | Run a hook immediately |
+| `set_hooks(hook, values)` | Set multiple indexed hooks |
+| `get_hook_indices(hook)` | Get list of indices |
+| `get_hook_values(hook)` | Get all values as SparseArray |
+| `append_hook(hook, value)` | Append at next index |
+| `clear_hook(hook)` | Remove all indexed values |
+
+#### SparseArray for Indexed Options (#516)
+
+tmux uses sparse indexed arrays for options like `command-alias[0]`,
+`command-alias[99]`, `terminal-features[0]`. Python lists can't represent
+gaps in indices, so libtmux introduces {class}`~_internal.sparse_array.SparseArray`:
+
+```python
+>>> from libtmux._internal.sparse_array import SparseArray
+
+>>> arr: SparseArray[str] = SparseArray()
+>>> arr.add(0, "first")
+>>> arr.add(99, "ninety-ninth")  # Gap in indices preserved!
+>>> arr[0]
+'first'
+>>> arr[99]
+'ninety-ninth'
+>>> list(arr.keys())
+[0, 99]
+>>> list(arr.iter_values())  # Values in index order
+['first', 'ninety-ninth']
+```
+
+#### New Constants (#516)
+
+- {class}`~constants.OptionScope` enum: `Server`, `Session`, `Window`, `Pane`
+- `OPTION_SCOPE_FLAG_MAP`: Maps scope to tmux flags (`-s`, `-w`, `-p`)
+- `HOOK_SCOPE_FLAG_MAP`: Maps scope to hook flags
+
 ## libtmux 0.49.0 (2025-11-29)
 
 ### Breaking Changes
@@ -48,6 +209,35 @@ deprecation announced in v0.48.0.
 - Removed version guards throughout the codebase
 - For users on older tmux, use libtmux v0.48.x
 
+#### Deprecated Window methods (#516)
+
+The following methods are deprecated and will be removed in a future release:
+
+| Deprecated | Replacement |
+|------------|-------------|
+| `Window.set_window_option()` | `Window.set_option()` |
+| `Window.show_window_option()` | `Window.show_option()` |
+| `Window.show_window_options()` | `Window.show_options()` |
+
+The old methods will emit a {class}`DeprecationWarning` when called:
+
+```python
+window.set_window_option('automatic-rename', 'on')
+# DeprecationWarning: Window.set_window_option() is deprecated
+
+# Use the new method instead:
+window.set_option('automatic-rename', True)
+```
+
+### tmux Version Compatibility
+
+| Feature | Minimum tmux |
+|---------|-------------|
+| All options/hooks features | 3.2+ |
+| Window/Pane hook scopes (`-w`, `-p`) | 3.2+ |
+| `client-active`, `window-resized` hooks | 3.3+ |
+| `pane-title-changed` hook | 3.5+ |
+
 ## libtmux 0.48.0 (2025-11-28)
 
 ### Breaking Changes

From 327e85eae47dee9effa7ecc3f4d967ff1d9a0faf Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 06:53:46 -0600
Subject: [PATCH 091/136] Window(fix[show_window_option]): Use public
 show_option() API

why: Deprecated method should guide users to public API, not private
what:
- Update docstring to reference show_option() instead of _show_option()
- Change method call from _show_option() to show_option()
- Aligns with show_window_options() which correctly uses show_options()
---
 src/libtmux/window.py | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/src/libtmux/window.py b/src/libtmux/window.py
index 8cc9dee82..5aab420c9 100644
--- a/src/libtmux/window.py
+++ b/src/libtmux/window.py
@@ -897,11 +897,11 @@ def show_window_option(
         option: str,
         g: bool = False,
     ) -> str | int | None:
-        """Return option for target window. Deprecated by :meth:`Window._show_option()`.
+        """Return option for target window. Deprecated by :meth:`Window.show_option()`.
 
         .. deprecated:: 0.26
 
-           Deprecated by :meth:`Window._show_option()`.
+           Deprecated by :meth:`Window.show_option()`.
 
         """
         warnings.warn(
@@ -909,7 +909,7 @@ def show_window_option(
             category=DeprecationWarning,
             stacklevel=2,
         )
-        return self._show_option(
+        return self.show_option(
             option=option,
             g=g,
             scope=OptionScope.Window,

From f82752188ea974e9679a3ed3ec47e6788b00e11a Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 07:03:44 -0600
Subject: [PATCH 092/136] OptionsMixin(fix[show_option]): Forward legacy g
 parameter

why: The g parameter was accepted but silently ignored, breaking
backward compatibility for callers using the legacy API
what:
- Forward g parameter to _show_option() via global_ or g
- Ensures show_option("foo", g=True) works as expected
---
 src/libtmux/options.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index c5b6d99da..9ab499d6a 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -1210,7 +1210,7 @@ def show_option(
         """
         return self._show_option(
             option=option,
-            global_=global_,
+            global_=global_ or g,
             scope=scope,
             ignore_errors=ignore_errors,
             include_hooks=include_hooks,

From 17c4ccdc01b439864ff77b0c126f95d0ef17e242 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 07:10:06 -0600
Subject: [PATCH 093/136] OptionsMixin(fix[show_option]): Add deprecation
 warning for g parameter

why: The g parameter should emit DeprecationWarning like set_option() does
what:
- Add deprecation warning when g parameter is used
- Follow same pattern as set_option() (lines 669-671)
- Ensures backward compatibility while guiding users to global_
---
 src/libtmux/options.py | 6 +++++-
 1 file changed, 5 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index 9ab499d6a..ceb0e57c3 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -1208,9 +1208,13 @@ def show_option(
         >>> MyServer().show_option('exit-unattached', global_=True)
         False
         """
+        if g:
+            warnings.warn("g argument is deprecated in favor of global_", stacklevel=2)
+            global_ = g
+
         return self._show_option(
             option=option,
-            global_=global_ or g,
+            global_=global_,
             scope=scope,
             ignore_errors=ignore_errors,
             include_hooks=include_hooks,

From 90757c9320edcddbd99955d3225f221a7f9ed96e Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 07:15:02 -0600
Subject: [PATCH 094/136] OptionsMixin(fix): Use DeprecationWarning for
 deprecated g parameter

why: Deprecation warnings should use proper DeprecationWarning category
to be properly filtered by Python's warning system
what:
- Update all 4 instances of g deprecation warning to use category=DeprecationWarning
- Affects set_option, _show_options_raw, _show_option_raw, show_option
---
 src/libtmux/options.py | 24 ++++++++++++++++++++----
 1 file changed, 20 insertions(+), 4 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index ceb0e57c3..59d5fde2f 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -667,7 +667,11 @@ def set_option(
             flags.append("-a")
 
         if g is not None:
-            warnings.warn("g argument is deprecated in favor of global_", stacklevel=2)
+            warnings.warn(
+                "g argument is deprecated in favor of global_",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
             global_ = g
 
         if global_ is not None and global_:
@@ -823,7 +827,11 @@ def _show_options_raw(
         flags: tuple[str, ...] = ()
 
         if g:
-            warnings.warn("g argument is deprecated in favor of global_", stacklevel=2)
+            warnings.warn(
+                "g argument is deprecated in favor of global_",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
             flags += ("-g",)
         elif global_:
             flags += ("-g",)
@@ -1048,7 +1056,11 @@ def _show_option_raw(
         flags: tuple[str | int, ...] = ()
 
         if g:
-            warnings.warn("g argument is deprecated in favor of global_", stacklevel=2)
+            warnings.warn(
+                "g argument is deprecated in favor of global_",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
             flags += ("-g",)
         elif global_:
             flags += ("-g",)
@@ -1209,7 +1221,11 @@ def show_option(
         False
         """
         if g:
-            warnings.warn("g argument is deprecated in favor of global_", stacklevel=2)
+            warnings.warn(
+                "g argument is deprecated in favor of global_",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
             global_ = g
 
         return self._show_option(

From 5afa214e86aa648b83d531356fefb52a362a276d Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 07:15:14 -0600
Subject: [PATCH 095/136] tests(test_options): Add test for g parameter
 deprecation warning

why: Verify that show_option() emits DeprecationWarning when deprecated g
parameter is used
what:
- Add test_show_option_g_parameter_emits_deprecation_warning test
- Ensures backward compatibility warning is properly raised
---
 tests/test_options.py | 10 ++++++++++
 1 file changed, 10 insertions(+)

diff --git a/tests/test_options.py b/tests/test_options.py
index 998d7b893..c8059fa76 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -26,6 +26,7 @@
     from typing_extensions import LiteralString
 
     from libtmux.server import Server
+    from libtmux.session import Session
 
 
 def test_options(server: Server) -> None:
@@ -1276,3 +1277,12 @@ def test_convert_values_preserves_sparse_keys() -> None:
     assert result[0] is True
     assert result[5] is False
     assert result[99] == 100
+
+
+def test_show_option_g_parameter_emits_deprecation_warning(
+    session: Session,
+) -> None:
+    """Test show_option() emits DeprecationWarning when g parameter is used."""
+    server = session.server
+    with pytest.warns(DeprecationWarning, match=r"g argument is deprecated"):
+        server.show_option("buffer-limit", g=True)

From e5a5b9db9e86eec290b64a7ff4525303e52f0504 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 07:15:50 -0600
Subject: [PATCH 096/136] HooksMixin(fix[show_hook]): Forward global_ parameter
 to _show_hook

why: The global_ parameter was accepted but not forwarded, preventing
users from querying server-wide hooks with -g flag
what:
- Forward global_=global_ when calling _show_hook()
---
 src/libtmux/hooks.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 728f47f5b..79865a06b 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -425,6 +425,7 @@ def show_hook(
         """
         hooks_output = self._show_hook(
             hook=hook,
+            global_=global_,
             scope=scope,
             ignore_errors=ignore_errors,
         )

From 3d375944c7693100be73dd93b39a86b605736664 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 07:16:33 -0600
Subject: [PATCH 097/136] docs(CHANGES): Remove references to unimplemented
 hook methods

why: CHANGES documented bulk hook APIs that don't exist in HooksMixin
what:
- Remove get_hook_indices, get_hook_values, append_hook, clear_hook
- These methods were documented but never implemented
- Keep only the implemented methods: set_hook, show_hook, show_hooks,
  unset_hook, run_hook, set_hooks
---
 CHANGES | 22 ++--------------------
 1 file changed, 2 insertions(+), 20 deletions(-)

diff --git a/CHANGES b/CHANGES
index b9983fec5..792466009 100644
--- a/CHANGES
+++ b/CHANGES
@@ -136,20 +136,6 @@ session.set_hooks('session-renamed', {
     1: 'display-message "Hook 1"',
     5: 'run-shell "echo hook 5"',
 })
-
-# Get all indexed values for a hook
-session.get_hook_values('session-renamed')
-# SparseArray({0: 'display-message "Hook 0"', 1: '...', 5: '...'})
-
-# Get just the indices
-session.get_hook_indices('session-renamed')
-# [0, 1, 5]
-
-# Append at next available index
-session.append_hook('session-renamed', 'display-message "Hook 6"')
-
-# Clear all indexed values for a hook
-session.clear_hook('session-renamed')
 ```
 
 **Hook methods available on Server, Session, Window, and Pane:**
@@ -157,15 +143,11 @@ session.clear_hook('session-renamed')
 | Method | Description |
 |--------|-------------|
 | `set_hook(hook, value)` | Set a hook |
-| `show_hook(hook)` | Get hook value |
+| `show_hook(hook)` | Get hook value (returns SparseArray for indexed hooks) |
 | `show_hooks()` | Get all hooks |
 | `unset_hook(hook)` | Remove a hook |
 | `run_hook(hook)` | Run a hook immediately |
-| `set_hooks(hook, values)` | Set multiple indexed hooks |
-| `get_hook_indices(hook)` | Get list of indices |
-| `get_hook_values(hook)` | Get all values as SparseArray |
-| `append_hook(hook, value)` | Append at next index |
-| `clear_hook(hook)` | Remove all indexed values |
+| `set_hooks(hook, values)` | Set multiple indexed hooks at once |
 
 #### SparseArray for Indexed Options (#516)
 

From e4722dc09f1de26dec36a82b3a2b3203e16a83ab Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:00:20 -0600
Subject: [PATCH 098/136] constants(fix[HOOK_SCOPE_FLAG_MAP]): Map Server scope
 to -g flag

why: Server.set_hook() was broken - HOOK_SCOPE_FLAG_MAP[Server] was ""
which added an empty string argument to tmux commands. Server/global
hooks require -g flag per tmux documentation.

what:
- Change OptionScope.Server from "" to "-g" in HOOK_SCOPE_FLAG_MAP
- Fixes Server.set_hook(), Server.show_hooks(), Server.run_hook()
---
 src/libtmux/constants.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/libtmux/constants.py b/src/libtmux/constants.py
index 3b23895b9..43ad3f519 100644
--- a/src/libtmux/constants.py
+++ b/src/libtmux/constants.py
@@ -78,7 +78,7 @@ class OptionScope(enum.Enum):
 }
 
 HOOK_SCOPE_FLAG_MAP: dict[OptionScope, str] = {
-    OptionScope.Server: "",
+    OptionScope.Server: "-g",
     OptionScope.Session: "",
     OptionScope.Window: "-w",
     OptionScope.Pane: "-p",

From a93d0fe69539e99e50573c0aca759bdbb7e5ef12 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:00:53 -0600
Subject: [PATCH 099/136] HooksMixin(fix[show_hook]): Strip % prefix for
 control-mode hooks

why: Control-mode hooks like %output, %window-add have % prefix that
Hooks.from_stdout() strips when creating attributes, but show_hook()
didn't strip it before lookup, causing all %-prefixed hooks to return
None.

what:
- Add lstrip("%") before replace("-", "_") in show_hook() attribute lookup
---
 src/libtmux/hooks.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 79865a06b..b496957b0 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -432,7 +432,7 @@ def show_hook(
         if hooks_output is None:
             return None
         hooks = Hooks.from_stdout(hooks_output)
-        return getattr(hooks, hook.replace("-", "_"), None)
+        return getattr(hooks, hook.lstrip("%").replace("-", "_"), None)
 
     def set_hooks(
         self,

From 4c400a2ab64275be72aa4a7261a64d9570e58295 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:01:23 -0600
Subject: [PATCH 100/136] HooksMixin(fix[set_hook]): Add deprecation warning
 for g parameter

why: The g parameter was silently ignored in set_hook(), breaking
backward compatibility. Code calling set_hook(..., g=True) would not
get global behavior.

what:
- Add DeprecationWarning when g parameter is used
- Forward g value to global_ for backward compatibility
- Matches pattern used in OptionsMixin.set_option()
---
 src/libtmux/hooks.py | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index b496957b0..159956d50 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -136,6 +136,14 @@ def set_hook(
         if scope is DEFAULT_OPTION_SCOPE:
             scope = self.default_hook_scope
 
+        if g:
+            warnings.warn(
+                "g argument is deprecated in favor of global_",
+                category=DeprecationWarning,
+                stacklevel=2,
+            )
+            global_ = g
+
         flags: list[str] = []
 
         if unset is not None and unset:

From ebb507f509513ebce48858811f7e2bd148aeb9b4 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:01:55 -0600
Subject: [PATCH 101/136] HooksMixin(feat[run_hook]): Add global_ parameter

why: Hooks set globally (with global_=True) could not be run via
run_hook() because it had no way to pass -g flag to tmux.

what:
- Add global_: bool | None = None parameter to run_hook()
- Add -g flag handling when global_ is True
---
 src/libtmux/hooks.py | 4 ++++
 1 file changed, 4 insertions(+)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 159956d50..56f9aaeb5 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -72,6 +72,7 @@ def __init__(self, default_hook_scope: OptionScope | None) -> None:
     def run_hook(
         self,
         hook: str,
+        global_: bool | None = None,
         scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
     ) -> Self:
         """Run a hook immediately. Useful for testing."""
@@ -80,6 +81,9 @@ def run_hook(
 
         flags: list[str] = ["-R"]
 
+        if global_ is not None and global_:
+            flags.append("-g")
+
         if scope is not None and not isinstance(scope, _DefaultOptionScope):
             assert scope in HOOK_SCOPE_FLAG_MAP
 

From 3fcc34d98d4cb29e63e524da7fab8fa50934a105 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:02:21 -0600
Subject: [PATCH 102/136] options(refactor[convert_values]): Remove dead
 SparseArray branch

why: The SparseArray-specific branch at lines 248-251 was unreachable
dead code. Since SparseArray inherits from dict, isinstance(value, dict)
returns True and the dict branch handles it correctly first.

what:
- Remove unreachable SparseArray branch that contained buggy logic
- Add comment explaining dict branch handles SparseArray too
---
 src/libtmux/options.py | 5 +----
 1 file changed, 1 insertion(+), 4 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index 59d5fde2f..fedd8d491 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -242,13 +242,10 @@ def convert_values(
     if value is None:
         return None
     if isinstance(value, dict):
+        # Note: SparseArray inherits from dict, so this branch handles both
         for k, v in value.items():
             value[k] = convert_value(v)
         return value
-    if isinstance(value, SparseArray):
-        for v in value.iter_values():
-            value[v] = convert_value(v)
-        return value
     if isinstance(value, list):
         for idx, v in enumerate(value):
             value[idx] = convert_value(v)

From da38b709289cb900bfae3c7cf0b740ef16d98596 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:42:57 -0600
Subject: [PATCH 103/136] hooks.py(fix[set_hook]): Remove invalid _format
 parameter

why: tmux set-hook does not accept -F flag (only set-option does).
     Verified against ~/study/c/tmux/cmd-set-option.c:65 which shows
     set-hook accepts "agpRt:uw" only.
what:
- Remove _format parameter from set_hook() signature
- Remove _format flag handling code
---
 src/libtmux/hooks.py | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 56f9aaeb5..3e3ff248d 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -111,7 +111,6 @@ def set_hook(
         self,
         hook: str,
         value: int | str,
-        _format: bool | None = None,
         unset: bool | None = None,
         run: bool | None = None,
         prevent_overwrite: bool | None = None,
@@ -158,10 +157,6 @@ def set_hook(
             assert isinstance(run, bool)
             flags.append("-R")
 
-        if _format is not None and _format:
-            assert isinstance(_format, bool)
-            flags.append("-F")
-
         if prevent_overwrite is not None and prevent_overwrite:
             assert isinstance(prevent_overwrite, bool)
             flags.append("-o")

From 2ca8063b156c59e74df836dc835129f7c6f2f1d9 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:44:13 -0600
Subject: [PATCH 104/136] hooks.py(fix[set_hook]): Remove invalid
 prevent_overwrite parameter

why: tmux set-hook does not accept -o flag (only set-option does).
     Verified against ~/study/c/tmux/cmd-set-option.c:65 which shows
     set-hook accepts "agpRt:uw" only.
what:
- Remove prevent_overwrite parameter from set_hook() signature
- Remove prevent_overwrite flag handling code
---
 src/libtmux/hooks.py | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 3e3ff248d..e4187a4b2 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -113,7 +113,6 @@ def set_hook(
         value: int | str,
         unset: bool | None = None,
         run: bool | None = None,
-        prevent_overwrite: bool | None = None,
         ignore_errors: bool | None = None,
         append: bool | None = None,
         g: bool | None = None,
@@ -157,10 +156,6 @@ def set_hook(
             assert isinstance(run, bool)
             flags.append("-R")
 
-        if prevent_overwrite is not None and prevent_overwrite:
-            assert isinstance(prevent_overwrite, bool)
-            flags.append("-o")
-
         if ignore_errors is not None and ignore_errors:
             assert isinstance(ignore_errors, bool)
             flags.append("-q")

From ff368f4788155ae5b22cb41b72d1cf62f911fb25 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:45:19 -0600
Subject: [PATCH 105/136] hooks.py(fix[set_hook]): Remove invalid ignore_errors
 parameter

why: tmux set-hook does not accept -q flag (only set-option does).
     Verified against ~/study/c/tmux/cmd-set-option.c:65 which shows
     set-hook accepts "agpRt:uw" only.
what:
- Remove ignore_errors parameter from set_hook() signature
- Remove ignore_errors flag handling code
---
 src/libtmux/hooks.py | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index e4187a4b2..bc24ef73d 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -113,7 +113,6 @@ def set_hook(
         value: int | str,
         unset: bool | None = None,
         run: bool | None = None,
-        ignore_errors: bool | None = None,
         append: bool | None = None,
         g: bool | None = None,
         global_: bool | None = None,
@@ -156,10 +155,6 @@ def set_hook(
             assert isinstance(run, bool)
             flags.append("-R")
 
-        if ignore_errors is not None and ignore_errors:
-            assert isinstance(ignore_errors, bool)
-            flags.append("-q")
-
         if append is not None and append:
             assert isinstance(append, bool)
             flags.append("-a")

From 0c3deccaad03afecabcb790140814e570b66a7d8 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:46:27 -0600
Subject: [PATCH 106/136] hooks.py(fix[unset_hook]): Remove invalid
 ignore_errors parameter

why: tmux set-hook (used with -u for unset) does not accept -q flag.
     Verified against ~/study/c/tmux/cmd-set-option.c:65 which shows
     set-hook accepts "agpRt:uw" only.
what:
- Remove ignore_errors parameter from unset_hook() signature
- Remove ignore_errors flag handling code
---
 src/libtmux/hooks.py | 5 -----
 1 file changed, 5 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index bc24ef73d..429b72a25 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -191,7 +191,6 @@ def unset_hook(
         self,
         hook: str,
         global_: bool | None = None,
-        ignore_errors: bool | None = None,
         scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
     ) -> Self:
         """Unset hook for tmux target.
@@ -213,10 +212,6 @@ def unset_hook(
 
         flags: list[str] = ["-u"]
 
-        if ignore_errors is not None and ignore_errors:
-            assert isinstance(ignore_errors, bool)
-            flags.append("-q")
-
         if global_ is not None and global_:
             assert isinstance(global_, bool)
             flags.append("-g")

From a9a5bb2ebfc1352d197600d1cd25782cc57a50a9 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:47:36 -0600
Subject: [PATCH 107/136] hooks.py(fix[show_hooks]): Remove invalid
 ignore_errors parameter

why: tmux show-hooks does not accept -q flag.
     Verified against ~/study/c/tmux/cmd-show-options.c:67 which shows
     show-hooks accepts "gpt:w" only.
what:
- Remove ignore_errors parameter from show_hooks() signature
- Remove ignore_errors flag handling code
- Remove ignore_errors from docstring parameters
---
 src/libtmux/hooks.py | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 429b72a25..750659b01 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -243,7 +243,6 @@ def show_hooks(
         self,
         global_: bool | None = False,
         scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
-        ignore_errors: bool | None = None,
     ) -> HookDict:
         """Return a dict of hooks for the target.
 
@@ -253,8 +252,6 @@ def show_hooks(
             Pass ``-g`` flag for global hooks, default False.
         scope : OptionScope | _DefaultOptionScope | None, optional
             Hook scope (Server/Session/Window/Pane), defaults to object's scope.
-        ignore_errors : bool, optional
-            Suppress errors with ``-q`` flag.
 
         Returns
         -------
@@ -296,10 +293,6 @@ def show_hooks(
             else:
                 flags += (flag,)
 
-        if ignore_errors is not None and ignore_errors:
-            assert isinstance(ignore_errors, bool)
-            flags += ("-q",)
-
         cmd = self.cmd("show-hooks", *flags)
         output = cmd.stdout
         hooks: HookDict = {}

From 7c316bf200a9e718d030aaeffdfef111c488b8d2 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 08:49:09 -0600
Subject: [PATCH 108/136] hooks.py(fix[_show_hook, show_hook]): Remove invalid
 ignore_errors parameter

why: tmux show-hooks does not accept -q flag.
     Verified against ~/study/c/tmux/cmd-show-options.c:67 which shows
     show-hooks accepts "gpt:w" only.
what:
- Remove ignore_errors parameter from _show_hook() signature
- Remove ignore_errors parameter from show_hook() signature
- Remove ignore_errors flag handling code
- Remove ignore_errors from _show_hook() call in show_hook()
---
 src/libtmux/hooks.py | 6 ------
 1 file changed, 6 deletions(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index 750659b01..db99b1f61 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -319,7 +319,6 @@ def _show_hook(
         hook: str,
         global_: bool = False,
         scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
-        ignore_errors: bool | None = None,
     ) -> list[str] | None:
         """Return value for the hook.
 
@@ -352,9 +351,6 @@ def _show_hook(
             else:
                 flags += (flag,)
 
-        if ignore_errors is not None and ignore_errors:
-            flags += ("-q",)
-
         flags += (hook,)
 
         cmd = self.cmd("show-hooks", *flags)
@@ -369,7 +365,6 @@ def show_hook(
         hook: str,
         global_: bool = False,
         scope: OptionScope | _DefaultOptionScope | None = DEFAULT_OPTION_SCOPE,
-        ignore_errors: bool | None = None,
     ) -> str | int | SparseArray[str] | None:
         """Return value for a hook.
 
@@ -412,7 +407,6 @@ def show_hook(
             hook=hook,
             global_=global_,
             scope=scope,
-            ignore_errors=ignore_errors,
         )
         if hooks_output is None:
             return None

From ec97859b9671a548a24162b3f92dc5df5fd757f8 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 09:14:23 -0600
Subject: [PATCH 109/136] tests/test_options.py(test): Add test for indexed
 array option lookup

why: Verify show_option correctly handles bracketed array indices like
'status-format[0]'. Currently returns None instead of the value.
what:
- Add ShowOptionIndexedTestCase NamedTuple with test_id pattern
- Add parametrized test_show_option_indexed_array test
- Test verifies indexed query returns value, base name returns SparseArray
- Test follows TDD RED phase (currently failing as expected)
---
 tests/test_options.py | 60 +++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 60 insertions(+)

diff --git a/tests/test_options.py b/tests/test_options.py
index c8059fa76..60682b7c8 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -1286,3 +1286,63 @@ def test_show_option_g_parameter_emits_deprecation_warning(
     server = session.server
     with pytest.warns(DeprecationWarning, match=r"g argument is deprecated"):
         server.show_option("buffer-limit", g=True)
+
+
+# =============================================================================
+# show_option with Indexed Array Tests
+# =============================================================================
+
+
+class ShowOptionIndexedTestCase(t.NamedTuple):
+    """Test case for show_option with bracketed array index."""
+
+    test_id: str
+    option: str
+    expect_sparse_array: bool  # True for base name, False for indexed
+
+
+SHOW_OPTION_INDEXED_TEST_CASES: list[ShowOptionIndexedTestCase] = [
+    ShowOptionIndexedTestCase(
+        test_id="indexed_returns_value",
+        option="status-format[0]",
+        expect_sparse_array=False,
+    ),
+    ShowOptionIndexedTestCase(
+        test_id="base_name_returns_sparse_array",
+        option="status-format",
+        expect_sparse_array=True,
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in SHOW_OPTION_INDEXED_TEST_CASES],
+)
+def test_show_option_indexed_array(
+    session: Session,
+    test_case: ShowOptionIndexedTestCase,
+) -> None:
+    """Test show_option handles bracketed array indices correctly.
+
+    When querying an option with a bracketed index (e.g., 'status-format[0]'),
+    tmux returns only that specific index's value. When querying the base name
+    (e.g., 'status-format'), tmux returns all indexed values.
+
+    This test verifies libtmux correctly:
+    - Returns a single value for indexed queries
+    - Returns a SparseArray for base name queries on array options
+    """
+    result = session.show_option(test_case.option, global_=True)
+    if test_case.expect_sparse_array:
+        assert isinstance(result, SparseArray), (
+            f"Expected SparseArray for '{test_case.option}', "
+            f"got {type(result).__name__}"
+        )
+    else:
+        assert result is not None, (
+            f"Expected a value for '{test_case.option}', got None"
+        )
+        assert not isinstance(result, SparseArray), (
+            f"Expected single value for '{test_case.option}', got SparseArray"
+        )

From c2d52ca14473dbc0be5e99fe0351a2cbd22ee44c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 09:16:08 -0600
Subject: [PATCH 110/136] options.py(fix[_show_option]): Handle bracketed array
 indices correctly

why: Querying 'status-format[0]' returned None because explode_arrays()
transforms the key to 'status-format', losing the original indexed key.
what:
- Parse raw output first before exploding arrays
- Direct lookup for indexed queries (key with brackets found in raw dict)
- For base name queries, continue with explode_arrays transformation
- Avoids duplicating regex parsing logic already in explode_arrays()
---
 src/libtmux/options.py | 19 ++++++++++---------
 1 file changed, 10 insertions(+), 9 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index fedd8d491..d6d725a01 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -1146,15 +1146,16 @@ def _show_option(
         if not len(options_output):
             return None
 
-        output_exploded = convert_values(
-            explode_complex(
-                explode_arrays(
-                    parse_options_to_dict(
-                        io.StringIO("\n".join(cmd.stdout)),
-                    ),
-                ),
-            ),
-        )
+        # Parse raw output first (preserves indexed keys like "status-format[0]")
+        output_raw = parse_options_to_dict(io.StringIO("\n".join(cmd.stdout)))
+
+        # Direct lookup for indexed queries (e.g., "status-format[0]")
+        # tmux returns only that index's value, so we handle it before exploding
+        if option in output_raw:
+            return convert_value(output_raw[option])
+
+        # For base name queries, explode arrays and return structured data
+        output_exploded = convert_values(explode_complex(explode_arrays(output_raw)))
 
         if not isinstance(output_exploded, (dict, SparseArray)):
             return t.cast("ConvertedValue", output_exploded)

From f33f5f2059a22cce97965cc3d6df599f1944601c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 09:34:04 -0600
Subject: [PATCH 111/136] tests/test_window.py(fix): Suppress secondary
 deprecation warning in test

why: The test `test_deprecated_window_methods_emit_warning[show_window_option_global]`
triggered two warnings: the expected one (Window method deprecated) and an unexpected
secondary one (g argument deprecated). The secondary warning leaked to pytest output.
what:
- Add @pytest.mark.filterwarnings to ignore "g argument is deprecated" warning
- Test still validates the primary deprecation warning via pytest.warns()
---
 tests/test_window.py | 1 +
 1 file changed, 1 insertion(+)

diff --git a/tests/test_window.py b/tests/test_window.py
index 2a88a316e..084ba407e 100644
--- a/tests/test_window.py
+++ b/tests/test_window.py
@@ -765,6 +765,7 @@ def _build_deprecated_method_params() -> list[t.Any]:
     ]
 
 
+@pytest.mark.filterwarnings("ignore:g argument is deprecated:DeprecationWarning")
 @pytest.mark.parametrize("test_case", _build_deprecated_method_params())
 def test_deprecated_window_methods_emit_warning(
     session: Session,

From fa6117e4311f539e6a31a91ede7e0bacd39c8b03 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 10:02:01 -0600
Subject: [PATCH 112/136] options.py(fix[explode_complex]): Parse multi-feature
 terminal-overrides

why: Per tmux.1, terminal-overrides entries are colon-separated strings where
the first part is a terminal pattern and remaining parts are individual
features. The previous code used `split(":", maxsplit=1)` which collapsed all
features after the pattern into a single key.
what:
- Split on all colons, not just the first
- Iterate over each feature part individually
- Add parametrized tests for multi-feature entries
---
 src/libtmux/options.py | 21 +++++++------
 tests/test_options.py  | 69 +++++++++++++++++++++++++++++++++++++++++-
 2 files changed, 80 insertions(+), 10 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index d6d725a01..bb6ca8083 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -519,18 +519,21 @@ def explode_complex(
 
                 for item in val.iter_values():
                     try:
-                        term, features = item.split(":", maxsplit=1)
+                        # Split on all colons: first part is terminal pattern,
+                        # remaining parts are individual features/capabilities
+                        parts = item.split(":")
+                        term = parts[0]
+                        features = parts[1:]
+
                         if term not in new_overrides:
                             new_overrides[term] = {}
-                        if features and "=" in features:
-                            k, v = features.split("=", 1)
-
-                            if v.isdigit():
-                                v = int(v)
 
-                            new_overrides[term][k] = v
-                        else:
-                            new_overrides[term][features] = None
+                        for feature in features:
+                            if feature and "=" in feature:
+                                k, v = feature.split("=", 1)
+                                new_overrides[term][k] = int(v) if v.isdigit() else v
+                            elif feature:
+                                new_overrides[term][feature] = None
                     except Exception:  # NOQA: PERF203
                         logger.exception("Error parsing options")
                 options[key] = new_overrides
diff --git a/tests/test_options.py b/tests/test_options.py
index 60682b7c8..27a304114 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -19,7 +19,7 @@
 from libtmux.common import has_gte_version
 from libtmux.constants import OptionScope
 from libtmux.exc import OptionError
-from libtmux.options import convert_values
+from libtmux.options import TerminalOverrides, convert_values
 from libtmux.pane import Pane
 
 if t.TYPE_CHECKING:
@@ -301,6 +301,73 @@ def test_terminal_overrides(
     assert options_["terminal-overrides"]["xterm-256color"] == {"Tc": None}
 
 
+class TerminalOverridesMultiFeatureCase(t.NamedTuple):
+    """Test fixture for terminal-overrides with multiple features per terminal."""
+
+    test_id: str
+    raw_entry: str
+    expected_term: str
+    expected_features: dict[str, str | int | None]
+
+
+@pytest.mark.parametrize(
+    TerminalOverridesMultiFeatureCase._fields,
+    [
+        TerminalOverridesMultiFeatureCase(
+            test_id="two_flags",
+            raw_entry="xterm*:smcup@:rmcup@",
+            expected_term="xterm*",
+            expected_features={"smcup@": None, "rmcup@": None},
+        ),
+        TerminalOverridesMultiFeatureCase(
+            test_id="flag_and_keyval",
+            raw_entry="xterm*:XT:Ms=clipboard",
+            expected_term="xterm*",
+            expected_features={"XT": None, "Ms": "clipboard"},
+        ),
+        TerminalOverridesMultiFeatureCase(
+            test_id="multiple_keyvals",
+            raw_entry="screen*:Tc:RGB:setab=test",
+            expected_term="screen*",
+            expected_features={
+                "Tc": None,
+                "RGB": None,
+                "setab": "test",
+            },
+        ),
+        TerminalOverridesMultiFeatureCase(
+            test_id="integer_value",
+            raw_entry="tmux*:colors=256:Tc",
+            expected_term="tmux*",
+            expected_features={"colors": 256, "Tc": None},
+        ),
+    ],
+    ids=lambda x: x.test_id if isinstance(x, TerminalOverridesMultiFeatureCase) else x,
+)
+def test_terminal_overrides_multi_feature(
+    server: Server,
+    monkeypatch: pytest.MonkeyPatch,
+    test_id: str,
+    raw_entry: str,
+    expected_term: str,
+    expected_features: dict[str, str | int | None],
+) -> None:
+    """Test terminal-overrides parsing with multiple features per terminal.
+
+    Per tmux.1 (lines 4311-4326), terminal-overrides entries are colon-separated
+    strings: terminal pattern followed by a LIST of features (not just one).
+    For example, 'xterm*:XT:Ms=value' should parse as two features: XT and Ms.
+    """
+    mock_options = [f"terminal-overrides[0] {raw_entry}"]
+    monkeypatch.setattr(server, "cmd", fake_cmd(stdout=mock_options))
+    options_ = server._show_options()
+
+    assert "terminal-overrides" in options_
+    term_overrides = t.cast(TerminalOverrides, options_["terminal-overrides"])
+    assert expected_term in term_overrides
+    assert term_overrides[expected_term] == expected_features
+
+
 def test_command_alias(
     server: Server,
     monkeypatch: pytest.MonkeyPatch,

From 6b81b0c17e37c747c8aabddeffdafac9ee7c7856 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 10:04:13 -0600
Subject: [PATCH 113/136] hooks.py(fix[show_hook]): Handle indexed hook queries
 correctly

why: When calling show_hook("session-renamed[0]"), the code attempted to find
an attribute named "session_renamed[0]" on the Hooks dataclass, which doesn't
exist. Per tmux.1, hooks are array options that can be queried by index.
what:
- Extract index from bracketed suffix before attribute lookup
- Return specific indexed value from SparseArray when present
- Add parametrized tests for indexed hook lookups
---
 src/libtmux/hooks.py | 16 ++++++++++-
 tests/test_hooks.py  | 68 ++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 83 insertions(+), 1 deletion(-)

diff --git a/src/libtmux/hooks.py b/src/libtmux/hooks.py
index db99b1f61..c94fc6755 100644
--- a/src/libtmux/hooks.py
+++ b/src/libtmux/hooks.py
@@ -30,6 +30,7 @@
 from __future__ import annotations
 
 import logging
+import re
 import typing as t
 import warnings
 
@@ -411,7 +412,20 @@ def show_hook(
         if hooks_output is None:
             return None
         hooks = Hooks.from_stdout(hooks_output)
-        return getattr(hooks, hook.lstrip("%").replace("-", "_"), None)
+
+        # Check if this is an indexed query (e.g., "session-renamed[0]")
+        # For indexed queries, return the specific value like _show_option does
+        hook_attr = hook.lstrip("%").replace("-", "_")
+        index_match = re.search(r"\[(\d+)\]$", hook_attr)
+        if index_match:
+            # Strip the index for attribute lookup
+            base_hook_attr = re.sub(r"\[\d+\]$", "", hook_attr)
+            hook_val = getattr(hooks, base_hook_attr, None)
+            if isinstance(hook_val, SparseArray):
+                return hook_val.get(int(index_match.group(1)))
+            return hook_val
+
+        return getattr(hooks, hook_attr, None)
 
     def set_hooks(
         self,
diff --git a/tests/test_hooks.py b/tests/test_hooks.py
index 22f93bb35..1e0c1b1ac 100644
--- a/tests/test_hooks.py
+++ b/tests/test_hooks.py
@@ -623,6 +623,74 @@ def test_show_hook_returns_sparse_array(server: Server) -> None:
     session.unset_hook("session-renamed")
 
 
+class IndexedHookLookupCase(t.NamedTuple):
+    """Test fixture for indexed hook lookups."""
+
+    test_id: str
+    hook_name: str
+    hook_index: int
+    hook_value: str
+
+
+@pytest.mark.parametrize(
+    IndexedHookLookupCase._fields,
+    [
+        IndexedHookLookupCase(
+            test_id="index_zero",
+            hook_name="session-renamed",
+            hook_index=0,
+            hook_value="display-message 'test zero'",
+        ),
+        IndexedHookLookupCase(
+            test_id="index_five",
+            hook_name="session-renamed",
+            hook_index=5,
+            hook_value="display-message 'test five'",
+        ),
+        IndexedHookLookupCase(
+            test_id="window_hook",
+            hook_name="window-renamed",
+            hook_index=0,
+            hook_value="display-message 'window test'",
+        ),
+    ],
+    ids=lambda x: x.test_id if isinstance(x, IndexedHookLookupCase) else x,
+)
+def test_show_hook_indexed_lookup(
+    server: Server,
+    test_id: str,
+    hook_name: str,
+    hook_index: int,
+    hook_value: str,
+) -> None:
+    """Test that show_hook with indexed hook name returns the specific value.
+
+    Per tmux.1, hooks are array options that can be queried by index.
+    When calling show_hook("session-renamed[0]"), it should return the string
+    value at that index, not a SparseArray.
+    """
+    session = server.new_session(session_name="test_indexed_lookup")
+    indexed_hook = f"{hook_name}[{hook_index}]"
+
+    # Set the hook
+    session.set_hook(indexed_hook, hook_value)
+
+    # Query with indexed name - should return the specific value, not SparseArray
+    result = session.show_hook(indexed_hook)
+    assert result is not None
+    assert isinstance(result, str), f"Expected str, got {type(result)}"
+    # tmux may normalize quotes, so check the essential parts are present
+    assert "display-message" in result
+
+    # Verify base hook query still returns SparseArray
+    base_result = session.show_hook(hook_name)
+    assert isinstance(base_result, SparseArray)
+    assert hook_index in base_result
+
+    # Cleanup
+    session.unset_hook(hook_name)
+
+
 def test_set_hooks_with_sparse_array(server: Server) -> None:
     """Test set_hooks with SparseArray input."""
     session = server.new_session(session_name="test_set_hooks_sparse")

From 18d9f804274a74976ed536a2fabb261d99afe11b Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 10:07:40 -0600
Subject: [PATCH 114/136] options.py(fix[_show_option]): Handle inherited
 option marker in lookups

why: tmux appends "*" to option names that are inherited from parent scopes
(e.g., "visual-activity*" when the value comes from global scope). The
lookup code was checking for the exact option name, missing inherited values.
what:
- Check for both exact key and key with "*" suffix in raw output lookup
- Check for inherited marker in exploded output lookup as well
- Fix test to properly capture inherited value before set/unset cycle
---
 src/libtmux/options.py | 23 ++++++++++++++++++-----
 tests/test_options.py  |  9 +++++++--
 2 files changed, 25 insertions(+), 7 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index bb6ca8083..408e194e7 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -1152,10 +1152,18 @@ def _show_option(
         # Parse raw output first (preserves indexed keys like "status-format[0]")
         output_raw = parse_options_to_dict(io.StringIO("\n".join(cmd.stdout)))
 
+        # Handle tmux's inherited option marker: tmux appends "*" to option names
+        # that are inherited from a parent scope (e.g., "visual-activity*" for an
+        # option inherited from global scope). We need to check for both the exact
+        # option name and the name with "*" suffix.
+        option_key = option
+        if option not in output_raw and f"{option}*" in output_raw:
+            option_key = f"{option}*"
+
         # Direct lookup for indexed queries (e.g., "status-format[0]")
         # tmux returns only that index's value, so we handle it before exploding
-        if option in output_raw:
-            return convert_value(output_raw[option])
+        if option_key in output_raw:
+            return convert_value(output_raw[option_key])
 
         # For base name queries, explode arrays and return structured data
         output_exploded = convert_values(explode_complex(explode_arrays(output_raw)))
@@ -1163,8 +1171,13 @@ def _show_option(
         if not isinstance(output_exploded, (dict, SparseArray)):
             return t.cast("ConvertedValue", output_exploded)
 
-        if isinstance(output_exploded, dict) and option not in output_exploded:
-            return None
+        # Check for inherited marker in exploded output as well
+        exploded_key = option
+        if isinstance(output_exploded, dict):
+            if option not in output_exploded and f"{option}*" in output_exploded:
+                exploded_key = f"{option}*"
+            if exploded_key not in output_exploded:
+                return None
 
         if isinstance(output_exploded, SparseArray):
             try:
@@ -1173,7 +1186,7 @@ def _show_option(
             except (ValueError, KeyError):
                 return None
 
-        return t.cast("ConvertedValue | None", output_exploded[option])
+        return t.cast("ConvertedValue | None", output_exploded[exploded_key])
 
     def show_option(
         self,
diff --git a/tests/test_options.py b/tests/test_options.py
index 27a304114..0275fad72 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -618,12 +618,17 @@ def test_complex_option_values(server: Server) -> None:
 
     # Test option inheritance (only for tmux >= 3.0)
     if has_gte_version("3.0"):
-        parent_val = session.show_option("status-style")
+        # Capture the inherited value (from global scope). Need include_inherited
+        # because without an explicit session-level value, show_option returns None
+        inherited_val = session.show_option("status-style", include_inherited=True)
         session.set_option("status-style", "fg=red")
         assert session.show_option("status-style") == "fg=red"
         assert session.show_option("status-style", include_inherited=True) == "fg=red"
         session.unset_option("status-style")
-        assert session.show_option("status-style", include_inherited=True) == parent_val
+        # After unsetting, should get inherited value back
+        assert (
+            session.show_option("status-style", include_inherited=True) == inherited_val
+        )
 
 
 def test_style_option_validation(server: Server) -> None:

From 39d20cc93f84482dcd14cb32288f71bcb8a4b50f Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 10:29:22 -0600
Subject: [PATCH 115/136] options.py(fix[explode_arrays]): Preserve inherited
 marker in array keys

why: When tmux outputs inherited array options with -A flag (e.g.,
"status-format[0]*"), the asterisk was being stripped during explosion.
This caused inconsistency: scalar inherited options preserved the "*"
marker but array options did not.
what:
- Update regex to capture trailing "*" in new `inherited` group
- Append "*" to base key when inherited marker is present
- Ensures inherited array options like "status-format[0]*" produce
  "status-format*" keys, consistent with scalar inherited options
---
 src/libtmux/options.py | 10 +++++++---
 1 file changed, 7 insertions(+), 3 deletions(-)

diff --git a/src/libtmux/options.py b/src/libtmux/options.py
index 408e194e7..75ed85e69 100644
--- a/src/libtmux/options.py
+++ b/src/libtmux/options.py
@@ -408,13 +408,17 @@ def explode_arrays(
 
         try:
             matchgroup = re.match(
-                r"(?P<hook>[\w-]+)(\[(?P<index>\d+)\])?",
+                r"(?P<option>[\w-]+)(\[(?P<index>\d+)\])?(?P<inherited>\*)?",
                 key,
             )
             if matchgroup is not None:
                 match = matchgroup.groupdict()
-                if match.get("hook") and match.get("index"):
-                    key = match["hook"]
+                if match.get("option") and match.get("index"):
+                    # Preserve inherited marker (*) if present
+                    base_key = match["option"]
+                    if match.get("inherited"):
+                        base_key += "*"
+                    key = base_key
                     index = int(match["index"])
 
                     if options.get(key) is None:

From b92cc73a7e7963eb464f2c0a3e59feb7aaf0efcb Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 10:30:27 -0600
Subject: [PATCH 116/136] tests/test_options.py(feat): Add inherited array
 marker preservation tests
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

why: Ensure explode_arrays correctly preserves the "*" marker for inherited
array options (e.g., "status-format[0]*" → "status-format*"), consistent
with scalar inherited options.
what:
- Add ExplodeArraysInheritedCase NamedTuple for parametrized tests
- Add 3 test cases: inherited arrays, non-inherited arrays, mixed indices
- Import explode_arrays function for direct unit testing
---
 tests/test_options.py | 78 ++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 77 insertions(+), 1 deletion(-)

diff --git a/tests/test_options.py b/tests/test_options.py
index 0275fad72..cc3e94b3f 100644
--- a/tests/test_options.py
+++ b/tests/test_options.py
@@ -19,7 +19,7 @@
 from libtmux.common import has_gte_version
 from libtmux.constants import OptionScope
 from libtmux.exc import OptionError
-from libtmux.options import TerminalOverrides, convert_values
+from libtmux.options import TerminalOverrides, convert_values, explode_arrays
 from libtmux.pane import Pane
 
 if t.TYPE_CHECKING:
@@ -1418,3 +1418,79 @@ def test_show_option_indexed_array(
         assert not isinstance(result, SparseArray), (
             f"Expected single value for '{test_case.option}', got SparseArray"
         )
+
+
+# =============================================================================
+# explode_arrays Inherited Marker Tests
+# =============================================================================
+
+
+class ExplodeArraysInheritedCase(t.NamedTuple):
+    """Test case for explode_arrays with inherited marker preservation."""
+
+    test_id: str
+    raw_input: dict[str, str | None]
+    expected_key: str
+    expected_indices: dict[int, str]
+
+
+EXPLODE_ARRAYS_INHERITED_CASES: list[ExplodeArraysInheritedCase] = [
+    ExplodeArraysInheritedCase(
+        test_id="inherited_array_marker_preserved",
+        raw_input={"status-format[0]*": "fmt0", "status-format[1]*": "fmt1"},
+        expected_key="status-format*",
+        expected_indices={0: "fmt0", 1: "fmt1"},
+    ),
+    ExplodeArraysInheritedCase(
+        test_id="non_inherited_array_no_marker",
+        raw_input={"status-format[0]": "fmt0", "status-format[1]": "fmt1"},
+        expected_key="status-format",
+        expected_indices={0: "fmt0", 1: "fmt1"},
+    ),
+    ExplodeArraysInheritedCase(
+        test_id="mixed_inherited_indices",
+        raw_input={"opt[0]*": "v0", "opt[5]*": "v5", "opt[10]*": "v10"},
+        expected_key="opt*",
+        expected_indices={0: "v0", 5: "v5", 10: "v10"},
+    ),
+]
+
+
+@pytest.mark.parametrize(
+    "test_case",
+    [pytest.param(tc, id=tc.test_id) for tc in EXPLODE_ARRAYS_INHERITED_CASES],
+)
+def test_explode_arrays_preserves_inherited_marker(
+    test_case: ExplodeArraysInheritedCase,
+) -> None:
+    """Test that explode_arrays preserves the inherited marker (*) for array options.
+
+    When tmux returns inherited array options with the -A flag, each index includes
+    a trailing asterisk (e.g., "status-format[0]*"). The explode_arrays function
+    should preserve this marker in the resulting key, producing "status-format*"
+    instead of stripping it to just "status-format".
+
+    This ensures consistency with scalar inherited options, which already preserve
+    the "*" marker (e.g., "visual-activity*" stays as "visual-activity*").
+    """
+    result = explode_arrays(test_case.raw_input)
+
+    assert test_case.expected_key in result, (
+        f"Expected key '{test_case.expected_key}' not found in result. "
+        f"Got keys: {list(result.keys())}"
+    )
+
+    array_value = result[test_case.expected_key]
+    # explode_arrays returns SparseArray for most options (dict-like with int keys)
+    assert isinstance(array_value, SparseArray), (
+        f"Expected SparseArray for array option, got {type(array_value).__name__}"
+    )
+
+    for idx, expected_val in test_case.expected_indices.items():
+        assert idx in array_value, (
+            f"Expected index {idx} not found in array. "
+            f"Got indices: {list(array_value.keys())}"
+        )
+        assert array_value[idx] == expected_val, (
+            f"Value at index {idx}: expected '{expected_val}', got '{array_value[idx]}'"
+        )

From ded89cd44e4e3c6d0435fe1ca2f25318363c616b Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 13:11:32 -0600
Subject: [PATCH 117/136] docs(MIGRATION): Add migration notes for
 options/hooks API (#516)

why: Users upgrading to 0.50.0 need clear guidance on deprecated methods
and the new unified options/hooks API.

what:
- Document new unified options API (show_options, show_option, set_option,
  unset_option) available on all tmux objects
- Document new hooks API (set_hook, show_hook, show_hooks, unset_hook)
- Add deprecation notes for Window.set_window_option(),
  Window.show_window_option(), Window.show_window_options()
- Add deprecation notes for `g` parameter in favor of `global_`
- Include before/after code examples for each migration
---
 MIGRATION | 87 +++++++++++++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 87 insertions(+)

diff --git a/MIGRATION b/MIGRATION
index 6d62cf917..77fd07dc8 100644
--- a/MIGRATION
+++ b/MIGRATION
@@ -25,6 +25,93 @@ _Detailed migration steps for the next version will be posted here._
 
 <!-- To the maintainers and contributors: please add migration details for the upcoming release here -->
 
+## libtmux 0.50.0: Unified Options and Hooks API (#516)
+
+### New unified options API
+
+All tmux objects (Server, Session, Window, Pane) now share a consistent options
+interface through {class}`~libtmux.options.OptionsMixin`:
+
+```python
+# Get all options
+session.show_options()
+
+# Get a single option
+session.show_option('base-index')
+
+# Set an option
+window.set_option('automatic-rename', True)
+
+# Unset an option
+window.unset_option('automatic-rename')
+```
+
+### New hooks API
+
+All tmux objects now support hook management through
+{class}`~libtmux.hooks.HooksMixin`:
+
+```python
+# Set a hook
+session.set_hook('session-renamed', 'display-message "Renamed!"')
+
+# Get hook value
+session.show_hook('session-renamed')
+
+# Get all hooks
+session.show_hooks()
+
+# Remove a hook
+session.unset_hook('session-renamed')
+```
+
+### Deprecated Window methods
+
+The following `Window` methods are deprecated and will be removed in a future
+release:
+
+| Deprecated | Replacement |
+|------------|-------------|
+| `Window.set_window_option()` | {meth}`Window.set_option() <libtmux.Window.set_option>` |
+| `Window.show_window_option()` | {meth}`Window.show_option() <libtmux.Window.show_option>` |
+| `Window.show_window_options()` | {meth}`Window.show_options() <libtmux.Window.show_options>` |
+
+**Before (deprecated):**
+
+```python
+window.set_window_option('automatic-rename', 'on')
+window.show_window_option('automatic-rename')
+window.show_window_options()
+```
+
+**After (0.50.0+):**
+
+```python
+window.set_option('automatic-rename', True)
+window.show_option('automatic-rename')
+window.show_options()
+```
+
+### Deprecated `g` parameter
+
+The `g` parameter for global options is deprecated in favor of `global_`:
+
+**Before (deprecated):**
+
+```python
+session.show_option('status', g=True)
+session.set_option('status', 'off', g=True)
+```
+
+**After (0.50.0+):**
+
+```python
+session.show_option('status', global_=True)
+session.set_option('status', 'off', global_=True)
+```
+
+Using the old `g` parameter will emit a {class}`DeprecationWarning`.
+
 ## libtmux 0.46.0 (2025-02-25)
 
 #### Imports removed from libtmux.test (#580)

From 94400659dac1b80c976a6969a82270f2062a7fea Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 13:13:44 -0600
Subject: [PATCH 118/136] docs(topics): Add options and hooks topic guide
 (#516)

why: Users need a conceptual guide explaining the unified options/hooks
API, when to use different methods, and how to work with indexed hooks.

what:
- Create docs/topics/options_and_hooks.md with comprehensive guide
- Cover getting/setting options with show_options(), show_option(),
  set_option(), unset_option()
- Cover hooks API with set_hook(), show_hook(), show_hooks(), unset_hook()
- Document indexed hooks and SparseArray return type
- Include bulk hook operations with set_hooks()
- Add tmux version compatibility table
- Add options_and_hooks to topics/index.md toctree
- All doctests pass via pytest --doctest-glob
---
 docs/topics/index.md             |   1 +
 docs/topics/options_and_hooks.md | 162 +++++++++++++++++++++++++++++++
 2 files changed, 163 insertions(+)
 create mode 100644 docs/topics/options_and_hooks.md

diff --git a/docs/topics/index.md b/docs/topics/index.md
index 0653bb57b..88bfc9860 100644
--- a/docs/topics/index.md
+++ b/docs/topics/index.md
@@ -10,4 +10,5 @@ Explore libtmux’s core functionalities and underlying principles at a high lev
 
 context_managers
 traversal
+options_and_hooks
 ```
diff --git a/docs/topics/options_and_hooks.md b/docs/topics/options_and_hooks.md
new file mode 100644
index 000000000..b95eeeda9
--- /dev/null
+++ b/docs/topics/options_and_hooks.md
@@ -0,0 +1,162 @@
+(options-and-hooks)=
+
+# Options and Hooks
+
+libtmux provides a unified API for managing tmux options and hooks across all
+object types (Server, Session, Window, Pane).
+
+## Options
+
+tmux options control the behavior and appearance of sessions, windows, and
+panes. libtmux provides a consistent interface through
+{class}`~libtmux.options.OptionsMixin`.
+
+### Getting options
+
+Use {meth}`~libtmux.options.OptionsMixin.show_options` to get all options:
+
+```python
+>>> session.show_options()  # doctest: +ELLIPSIS
+{...}
+```
+
+Use {meth}`~libtmux.options.OptionsMixin.show_option` to get a single option:
+
+```python
+>>> server.show_option('buffer-limit')
+50
+```
+
+### Setting options
+
+Use {meth}`~libtmux.options.OptionsMixin.set_option` to set an option:
+
+```python
+>>> window.set_option('automatic-rename', False)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> window.show_option('automatic-rename')
+False
+```
+
+### Unsetting options
+
+Use {meth}`~libtmux.options.OptionsMixin.unset_option` to revert an option to
+its default:
+
+```python
+>>> window.unset_option('automatic-rename')  # doctest: +ELLIPSIS
+Window(@... ...)
+```
+
+### Option scopes
+
+tmux options exist at different scopes. Use the `scope` parameter to specify:
+
+```python
+>>> from libtmux.constants import OptionScope
+
+>>> # Get window-scoped options from a session
+>>> session.show_options(scope=OptionScope.Window)  # doctest: +ELLIPSIS
+{...}
+```
+
+### Global options
+
+Use `global_=True` to work with global options:
+
+```python
+>>> server.show_option('buffer-limit', global_=True)
+50
+```
+
+## Hooks
+
+tmux hooks allow you to run commands when specific events occur. libtmux
+provides hook management through {class}`~libtmux.hooks.HooksMixin`.
+
+### Setting and getting hooks
+
+Use {meth}`~libtmux.hooks.HooksMixin.set_hook` to set a hook and
+{meth}`~libtmux.hooks.HooksMixin.show_hook` to get its value:
+
+```python
+>>> session.set_hook('session-renamed', 'display-message "Session renamed"')  # doctest: +ELLIPSIS
+Session(...)
+
+>>> session.show_hook('session-renamed')  # doctest: +ELLIPSIS
+{0: 'display-message "Session renamed"'}
+
+>>> session.show_hooks()  # doctest: +ELLIPSIS
+{...}
+```
+
+Note that hooks are stored as indexed arrays in tmux, so `show_hook()` returns a
+{class}`~libtmux._internal.sparse_array.SparseArray` (dict-like) with index keys.
+
+### Removing hooks
+
+Use {meth}`~libtmux.hooks.HooksMixin.unset_hook` to remove a hook:
+
+```python
+>>> session.unset_hook('session-renamed')  # doctest: +ELLIPSIS
+Session(...)
+```
+
+### Indexed hooks
+
+tmux hooks support multiple values via indices (e.g., `session-renamed[0]`,
+`session-renamed[1]`). This allows multiple commands to run for the same event:
+
+```python
+>>> session.set_hook('after-split-window[0]', 'display-message "Split 0"')  # doctest: +ELLIPSIS
+Session(...)
+
+>>> session.set_hook('after-split-window[1]', 'display-message "Split 1"')  # doctest: +ELLIPSIS
+Session(...)
+
+>>> hooks = session.show_hook('after-split-window')
+>>> sorted(hooks.keys())
+[0, 1]
+```
+
+The return value is a {class}`~libtmux._internal.sparse_array.SparseArray`,
+which preserves sparse indices (e.g., indices 0 and 5 with no 1-4).
+
+### Bulk hook operations
+
+Use {meth}`~libtmux.hooks.HooksMixin.set_hooks` to set multiple indexed hooks:
+
+```python
+>>> session.set_hooks('window-linked', {
+...     0: 'display-message "Window linked 0"',
+...     1: 'display-message "Window linked 1"',
+... })  # doctest: +ELLIPSIS
+Session(...)
+
+>>> # Clean up
+>>> session.unset_hook('after-split-window[0]')  # doctest: +ELLIPSIS
+Session(...)
+>>> session.unset_hook('after-split-window[1]')  # doctest: +ELLIPSIS
+Session(...)
+>>> session.unset_hook('window-linked[0]')  # doctest: +ELLIPSIS
+Session(...)
+>>> session.unset_hook('window-linked[1]')  # doctest: +ELLIPSIS
+Session(...)
+```
+
+## tmux version compatibility
+
+| Feature | Minimum tmux |
+|---------|-------------|
+| All options/hooks features | 3.2+ |
+| Window/Pane hook scopes (`-w`, `-p`) | 3.2+ |
+| `client-active`, `window-resized` hooks | 3.3+ |
+| `pane-title-changed` hook | 3.5+ |
+
+:::{seealso}
+- {ref}`api` for the full API reference
+- {class}`~libtmux.options.OptionsMixin` for options methods
+- {class}`~libtmux.hooks.HooksMixin` for hooks methods
+- {class}`~libtmux._internal.sparse_array.SparseArray` for sparse array handling
+:::

From d24226eeab179cbdbc3411eaf50ec484fc879944 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 13:14:16 -0600
Subject: [PATCH 119/136] docs(quickstart): Add options section with examples
 (#516)

why: Users following the quickstart guide need to see basic options
usage alongside other common operations like creating windows and panes.

what:
- Add "Working with options" section before "Final notes"
- Include examples for show_option(), show_options(), set_option(),
  unset_option()
- Add seealso reference to the detailed options-and-hooks topic guide
- All doctests pass via pytest --doctest-glob
---
 docs/quickstart.md | 32 ++++++++++++++++++++++++++++++++
 1 file changed, 32 insertions(+)

diff --git a/docs/quickstart.md b/docs/quickstart.md
index 3d2790133..2350bdf97 100644
--- a/docs/quickstart.md
+++ b/docs/quickstart.md
@@ -441,6 +441,38 @@ automatically sent, the leading space character prevents adding it to the user's
 shell history. Omitting `enter=false` means the default behavior (sending the
 command) is done, without needing to use `pane.enter()` after.
 
+## Working with options
+
+libtmux provides a unified API for managing tmux options across Server, Session,
+Window, and Pane objects.
+
+### Getting options
+
+```python
+>>> server.show_option('buffer-limit')
+50
+
+>>> window.show_options()  # doctest: +ELLIPSIS
+{...}
+```
+
+### Setting options
+
+```python
+>>> window.set_option('automatic-rename', False)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> window.show_option('automatic-rename')
+False
+
+>>> window.unset_option('automatic-rename')  # doctest: +ELLIPSIS
+Window(@... ...)
+```
+
+:::{seealso}
+See {ref}`options-and-hooks` for more details on options and hooks.
+:::
+
 ## Final notes
 
 These objects created use tmux's internal usage of ID's to make servers,

From 5b573a1e3673afc2a917b20cf0c438d1226ffc42 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 13:23:02 -0600
Subject: [PATCH 120/136] py(deps[dev]) Bump dev packages

---
 uv.lock | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/uv.lock b/uv.lock
index 4578758f6..9655a2094 100644
--- a/uv.lock
+++ b/uv.lock
@@ -52,15 +52,15 @@ wheels = [
 
 [[package]]
 name = "beautifulsoup4"
-version = "4.14.2"
+version = "4.14.3"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
     { name = "soupsieve" },
     { name = "typing-extensions" },
 ]
-sdist = { url = "https://files.pythonhosted.org/packages/77/e9/df2358efd7659577435e2177bfa69cba6c33216681af51a707193dec162a/beautifulsoup4-4.14.2.tar.gz", hash = "sha256:2a98ab9f944a11acee9cc848508ec28d9228abfd522ef0fad6a02a72e0ded69e", size = 625822, upload-time = "2025-09-29T10:05:42.613Z" }
+sdist = { url = "https://files.pythonhosted.org/packages/c3/b0/1c6a16426d389813b48d95e26898aff79abbde42ad353958ad95cc8c9b21/beautifulsoup4-4.14.3.tar.gz", hash = "sha256:6292b1c5186d356bba669ef9f7f051757099565ad9ada5dd630bd9de5fa7fb86", size = 627737, upload-time = "2025-11-30T15:08:26.084Z" }
 wheels = [
-    { url = "https://files.pythonhosted.org/packages/94/fe/3aed5d0be4d404d12d36ab97e2f1791424d9ca39c2f754a6285d59a3b01d/beautifulsoup4-4.14.2-py3-none-any.whl", hash = "sha256:5ef6fa3a8cbece8488d66985560f97ed091e22bbc4e9c2338508a9d5de6d4515", size = 106392, upload-time = "2025-09-29T10:05:43.771Z" },
+    { url = "https://files.pythonhosted.org/packages/1a/39/47f9197bdd44df24d67ac8893641e16f386c984a0619ef2ee4c51fbbc019/beautifulsoup4-4.14.3-py3-none-any.whl", hash = "sha256:0918bfe44902e6ad8d57732ba310582e98da931428d231a5ecb9e7c703a735bb", size = 107721, upload-time = "2025-11-30T15:08:24.087Z" },
 ]
 
 [[package]]

From 31787f80c15b1f45c1f62f916f8c51e4503e5bd3 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 13:45:24 -0600
Subject: [PATCH 121/136] docs(conf) Note changes coming through 2026

---
 docs/conf.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/docs/conf.py b/docs/conf.py
index 2297a3898..db39b88fc 100644
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -92,7 +92,7 @@
     "source_repository": f"{about['__github__']}/",
     "source_branch": "master",
     "source_directory": "docs/",
-    "announcement": "<em>Friendly reminder:</em> 📌 Pin the package, libtmux is pre-1.0 and APIs will be <a href='https://github.com/migration.html'>changing</a> throughout 2025.",
+    "announcement": "<em>Friendly reminder:</em> 📌 Pin the package, libtmux is pre-1.0 and APIs will be <a href='https://github.com/migration.html'>changing</a> throughout 2026.",
 }
 html_sidebars = {
     "**": [

From 22bfe4e2f0397da25f14609dd2632da74415c488 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 14:02:07 -0600
Subject: [PATCH 122/136] docs(topics): Add pane interaction guide with
 doctests

why: Core pane automation patterns needed for agentic workflow users
what:
- Add send_keys, capture_pane, display_message examples
- Add output waiting and polling patterns
- Add resize and clear operations
- Add practical recipes for command execution
- All examples are runnable doctests
---
 docs/topics/pane_interaction.md | 354 ++++++++++++++++++++++++++++++++
 1 file changed, 354 insertions(+)
 create mode 100644 docs/topics/pane_interaction.md

diff --git a/docs/topics/pane_interaction.md b/docs/topics/pane_interaction.md
new file mode 100644
index 000000000..e0ee05c43
--- /dev/null
+++ b/docs/topics/pane_interaction.md
@@ -0,0 +1,354 @@
+(pane-interaction)=
+
+# Pane Interaction
+
+libtmux provides powerful methods for interacting with tmux panes programmatically.
+This is especially useful for automation, testing, and orchestrating terminal-based
+workflows.
+
+Open two terminals:
+
+Terminal one: start tmux in a separate terminal:
+
+```console
+$ tmux
+```
+
+Terminal two, `python` or `ptpython` if you have it:
+
+```console
+$ python
+```
+
+## Sending Commands
+
+The {meth}`~libtmux.Pane.send_keys` method sends text to a pane, optionally pressing
+Enter to execute it.
+
+### Basic command execution
+
+```python
+>>> pane = window.split(shell='sh')
+
+>>> pane.send_keys('echo "Hello from libtmux"')
+
+>>> import time; time.sleep(0.1)  # Allow command to execute
+
+>>> output = pane.capture_pane()
+>>> 'Hello from libtmux' in '\\n'.join(output)
+True
+```
+
+### Send without pressing Enter
+
+Use `enter=False` to type text without executing:
+
+```python
+>>> pane.send_keys('echo "waiting"', enter=False)
+
+>>> # Text is typed but not executed
+>>> output = pane.capture_pane()
+>>> 'waiting' in '\\n'.join(output)
+True
+```
+
+Press Enter separately with {meth}`~libtmux.Pane.enter`:
+
+```python
+>>> import time
+
+>>> # First type something without pressing Enter
+>>> pane.send_keys('echo "execute me"', enter=False)
+
+>>> pane.enter()  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+
+>>> time.sleep(0.2)
+
+>>> output = pane.capture_pane()
+>>> 'execute me' in '\\n'.join(output)
+True
+```
+
+### Literal mode for special characters
+
+Use `literal=True` to send special characters without interpretation:
+
+```python
+>>> import time
+
+>>> pane.send_keys('echo "Tab:\\tNewline:\\n"', literal=True)
+
+>>> time.sleep(0.1)
+```
+
+### Suppress shell history
+
+Use `suppress_history=True` to prepend a space (prevents command from being
+saved in shell history):
+
+```python
+>>> import time
+
+>>> pane.send_keys('echo "secret command"', suppress_history=True)
+
+>>> time.sleep(0.1)
+```
+
+## Capturing Output
+
+The {meth}`~libtmux.Pane.capture_pane` method captures text from a pane's buffer.
+
+### Basic capture
+
+```python
+>>> import time
+
+>>> pane.send_keys('echo "Line 1"; echo "Line 2"; echo "Line 3"')
+
+>>> time.sleep(0.1)
+
+>>> output = pane.capture_pane()
+>>> isinstance(output, list)
+True
+>>> any('Line 2' in line for line in output)
+True
+```
+
+### Capture with line ranges
+
+Capture specific line ranges using `start` and `end` parameters:
+
+```python
+>>> # Capture last 5 lines of visible pane
+>>> recent = pane.capture_pane(start=-5, end='-')
+>>> isinstance(recent, list)
+True
+
+>>> # Capture from start of history to current
+>>> full_history = pane.capture_pane(start='-', end='-')
+>>> len(full_history) >= 0
+True
+```
+
+## Waiting for Output
+
+A common pattern in automation is waiting for a command to complete.
+
+### Polling for completion marker
+
+```python
+>>> import time
+
+>>> pane.send_keys('sleep 0.2; echo "TASK_COMPLETE"')
+
+>>> # Poll for completion
+>>> for _ in range(30):
+...     output = pane.capture_pane()
+...     if 'TASK_COMPLETE' in '\\n'.join(output):
+...         break
+...     time.sleep(0.1)
+
+>>> 'TASK_COMPLETE' in '\\n'.join(output)
+True
+```
+
+### Helper function for waiting
+
+```python
+>>> import time
+
+>>> def wait_for_text(pane, text, timeout=5.0):
+...     """Wait for text to appear in pane output."""
+...     start = time.time()
+...     while time.time() - start < timeout:
+...         output = pane.capture_pane()
+...         if text in '\\n'.join(output):
+...             return True
+...         time.sleep(0.1)
+...     return False
+
+>>> pane.send_keys('echo "READY"')
+>>> wait_for_text(pane, 'READY', timeout=2.0)
+True
+```
+
+## Querying Pane State
+
+The {meth}`~libtmux.Pane.display_message` method queries tmux format variables.
+
+### Get pane dimensions
+
+```python
+>>> width = pane.display_message('#{pane_width}', get_text=True)
+>>> isinstance(width, list) and len(width) > 0
+True
+
+>>> height = pane.display_message('#{pane_height}', get_text=True)
+>>> isinstance(height, list) and len(height) > 0
+True
+```
+
+### Get pane information
+
+```python
+>>> # Current working directory
+>>> cwd = pane.display_message('#{pane_current_path}', get_text=True)
+>>> isinstance(cwd, list)
+True
+
+>>> # Pane ID
+>>> pane_id = pane.display_message('#{pane_id}', get_text=True)
+>>> pane_id[0].startswith('%')
+True
+```
+
+### Common format variables
+
+| Variable | Description |
+|----------|-------------|
+| `#{pane_width}` | Pane width in characters |
+| `#{pane_height}` | Pane height in characters |
+| `#{pane_current_path}` | Current working directory |
+| `#{pane_pid}` | PID of the pane's shell |
+| `#{pane_id}` | Unique pane ID (e.g., `%0`) |
+| `#{pane_index}` | Pane index in window |
+
+## Resizing Panes
+
+The {meth}`~libtmux.Pane.resize` method adjusts pane dimensions.
+
+### Resize by specific dimensions
+
+```python
+>>> # Make pane larger
+>>> pane.resize(height=20, width=80)  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+```
+
+### Resize by adjustment
+
+```python
+>>> from libtmux.constants import ResizeAdjustmentDirection
+
+>>> # Increase height by 5 rows
+>>> pane.resize(adjustment_direction=ResizeAdjustmentDirection.Up, adjustment=5)  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+
+>>> # Decrease width by 10 columns
+>>> pane.resize(adjustment_direction=ResizeAdjustmentDirection.Left, adjustment=10)  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+```
+
+### Zoom toggle
+
+```python
+>>> # Zoom pane to fill window
+>>> pane.resize(zoom=True)  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+
+>>> # Unzoom
+>>> pane.resize(zoom=True)  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+```
+
+## Clearing the Pane
+
+The {meth}`~libtmux.Pane.clear` method clears the pane's screen:
+
+```python
+>>> pane.clear()  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+```
+
+## Killing Panes
+
+The {meth}`~libtmux.Pane.kill` method destroys a pane:
+
+```python
+>>> # Create a temporary pane
+>>> temp_pane = pane.split()
+>>> temp_pane in window.panes
+True
+
+>>> # Kill it
+>>> temp_pane.kill()
+>>> temp_pane not in window.panes
+True
+```
+
+### Kill all except current
+
+```python
+>>> # Setup: create multiple panes
+>>> pane.window.resize(height=60, width=120)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> keep_pane = pane.split()
+>>> extra1 = pane.split()
+>>> extra2 = pane.split()
+
+>>> # Kill all except keep_pane
+>>> keep_pane.kill(all_except=True)
+
+>>> keep_pane in window.panes
+True
+>>> extra1 not in window.panes
+True
+>>> extra2 not in window.panes
+True
+
+>>> # Cleanup
+>>> keep_pane.kill()
+```
+
+## Practical Recipes
+
+### Recipe: Run command and capture output
+
+```python
+>>> import time
+
+>>> def run_and_capture(pane, command, marker='__DONE__', timeout=5.0):
+...     """Run a command and return its output."""
+...     pane.send_keys(f'{command}; echo {marker}')
+...     start = time.time()
+...     while time.time() - start < timeout:
+...         output = pane.capture_pane()
+...         output_str = '\\n'.join(output)
+...         if marker in output_str:
+...             return output  # Return all captured output
+...         time.sleep(0.1)
+...     raise TimeoutError(f'Command did not complete within {timeout}s')
+
+>>> result = run_and_capture(pane, 'echo "captured text"', timeout=2.0)
+>>> 'captured text' in '\\n'.join(result)
+True
+```
+
+### Recipe: Check for error patterns
+
+```python
+>>> import time
+
+>>> def check_for_errors(pane, error_patterns=None):
+...     """Check pane output for error patterns."""
+...     if error_patterns is None:
+...         error_patterns = ['error:', 'Error:', 'ERROR', 'failed', 'FAILED']
+...     output = '\\n'.join(pane.capture_pane())
+...     for pattern in error_patterns:
+...         if pattern in output:
+...             return True
+...     return False
+
+>>> pane.send_keys('echo "All good"')
+>>> time.sleep(0.1)
+>>> check_for_errors(pane)
+False
+```
+
+:::{seealso}
+- {ref}`api` for the full API reference
+- {class}`~libtmux.Pane` for all pane methods
+- {ref}`automation-patterns` for advanced orchestration patterns
+:::

From 86a0e33d4db34ec8d54bef55cfda019798d2a309 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 14:02:14 -0600
Subject: [PATCH 123/136] docs(topics): Add workspace setup guide with doctests

why: Multi-pane workspace creation essential for parallel task execution
what:
- Add window creation patterns with attach options
- Add pane splitting (vertical/horizontal) examples
- Add layout management (tiled, even-horizontal, main-vertical)
- Add practical recipes for dev workspace and pane grids
- All examples are runnable doctests
---
 docs/topics/workspace_setup.md | 353 +++++++++++++++++++++++++++++++++
 1 file changed, 353 insertions(+)
 create mode 100644 docs/topics/workspace_setup.md

diff --git a/docs/topics/workspace_setup.md b/docs/topics/workspace_setup.md
new file mode 100644
index 000000000..673e26db9
--- /dev/null
+++ b/docs/topics/workspace_setup.md
@@ -0,0 +1,353 @@
+(workspace-setup)=
+
+# Workspace Setup
+
+libtmux makes it easy to create and configure multi-pane workspaces programmatically.
+This is useful for setting up development environments, running parallel tasks,
+and orchestrating terminal-based workflows.
+
+Open two terminals:
+
+Terminal one: start tmux in a separate terminal:
+
+```console
+$ tmux
+```
+
+Terminal two, `python` or `ptpython` if you have it:
+
+```console
+$ python
+```
+
+## Creating Windows
+
+The {meth}`~libtmux.Session.new_window` method creates new windows within a session.
+
+### Basic window creation
+
+```python
+>>> new_window = session.new_window(window_name='workspace')
+>>> new_window  # doctest: +ELLIPSIS
+Window(@... ...:workspace, Session($... ...))
+
+>>> # Window is part of the session
+>>> new_window in session.windows
+True
+```
+
+### Create without attaching
+
+Use `attach=False` to create a window in the background:
+
+```python
+>>> background_window = session.new_window(
+...     window_name='background-task',
+...     attach=False,
+... )
+>>> background_window  # doctest: +ELLIPSIS
+Window(@... ...:background-task, Session($... ...))
+
+>>> # Clean up
+>>> background_window.kill()
+```
+
+### Create with specific shell
+
+```python
+>>> shell_window = session.new_window(
+...     window_name='shell-test',
+...     attach=False,
+...     window_shell='sh -c "echo Hello; exec sh"',
+... )
+>>> shell_window  # doctest: +ELLIPSIS
+Window(@... ...:shell-test, Session($... ...))
+
+>>> # Clean up
+>>> shell_window.kill()
+```
+
+## Splitting Panes
+
+The {meth}`~libtmux.Window.split` method divides windows into multiple panes.
+
+### Vertical split (top/bottom)
+
+```python
+>>> import time
+>>> from libtmux.constants import PaneDirection
+
+>>> # Create a window with enough space
+>>> v_split_window = session.new_window(window_name='v-split-demo', attach=False)
+>>> v_split_window.resize(height=40, width=120)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> # Default split is vertical (creates pane below)
+>>> top_pane = v_split_window.active_pane
+>>> bottom_pane = v_split_window.split()
+>>> bottom_pane  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+
+>>> len(v_split_window.panes)
+2
+
+>>> # Clean up
+>>> v_split_window.kill()
+```
+
+### Horizontal split (left/right)
+
+```python
+>>> from libtmux.constants import PaneDirection
+
+>>> # Create a fresh window for this demo
+>>> h_split_window = session.new_window(window_name='h-split', attach=False)
+>>> h_split_window.resize(height=40, width=120)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> left_pane = h_split_window.active_pane
+>>> right_pane = left_pane.split(direction=PaneDirection.Right)
+>>> right_pane  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+
+>>> len(h_split_window.panes)
+2
+
+>>> # Clean up
+>>> h_split_window.kill()
+```
+
+### Split with specific size
+
+```python
+>>> # Create a fresh window for size demo
+>>> size_window = session.new_window(window_name='size-demo', attach=False)
+>>> size_window.resize(height=40, width=120)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> main_pane = size_window.active_pane
+>>> # Create pane with specific percentage
+>>> small_pane = main_pane.split(size='20%')
+>>> small_pane  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+
+>>> # Clean up
+>>> size_window.kill()
+```
+
+## Layout Management
+
+The {meth}`~libtmux.Window.select_layout` method arranges panes using built-in layouts.
+
+### Available layouts
+
+tmux provides five built-in layouts:
+
+| Layout | Description |
+|--------|-------------|
+| `even-horizontal` | Panes spread evenly left to right |
+| `even-vertical` | Panes spread evenly top to bottom |
+| `main-horizontal` | Large pane on top, others below |
+| `main-vertical` | Large pane on left, others on right |
+| `tiled` | Panes spread evenly in rows and columns |
+
+### Applying layouts
+
+```python
+>>> # Create window with multiple panes
+>>> layout_window = session.new_window(window_name='layout-demo', attach=False)
+>>> layout_window.resize(height=60, width=120)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> pane1 = layout_window.active_pane
+>>> pane2 = layout_window.split()
+>>> pane3 = layout_window.split()
+>>> pane4 = layout_window.split()
+
+>>> # Apply tiled layout
+>>> layout_window.select_layout('tiled')  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> # Apply even-horizontal layout
+>>> layout_window.select_layout('even-horizontal')  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> # Apply main-vertical layout
+>>> layout_window.select_layout('main-vertical')  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> # Clean up
+>>> layout_window.kill()
+```
+
+## Renaming and Organizing
+
+### Rename windows
+
+```python
+>>> rename_window = session.new_window(window_name='old-name', attach=False)
+>>> rename_window.rename_window('new-name')  # doctest: +ELLIPSIS
+Window(@... ...:new-name, Session($... ...))
+
+>>> rename_window.window_name
+'new-name'
+
+>>> # Clean up
+>>> rename_window.kill()
+```
+
+### Access window properties
+
+```python
+>>> demo_window = session.new_window(window_name='props-demo', attach=False)
+
+>>> # Window index
+>>> demo_window.window_index  # doctest: +ELLIPSIS
+'...'
+
+>>> # Window ID
+>>> demo_window.window_id  # doctest: +ELLIPSIS
+'@...'
+
+>>> # Parent session
+>>> demo_window.session  # doctest: +ELLIPSIS
+Session($... ...)
+
+>>> # Clean up
+>>> demo_window.kill()
+```
+
+## Practical Recipes
+
+### Recipe: Create a development workspace
+
+```python
+>>> import time
+>>> from libtmux.constants import PaneDirection
+
+>>> def create_dev_workspace(session, name='dev'):
+...     """Create a typical development workspace layout."""
+...     window = session.new_window(window_name=name, attach=False)
+...     window.resize(height=50, width=160)
+...
+...     # Main editing pane (large, left side)
+...     main_pane = window.active_pane
+...
+...     # Terminal pane (bottom)
+...     terminal_pane = main_pane.split(size='30%')
+...
+...     # Logs pane (right side of terminal)
+...     log_pane = terminal_pane.split(direction=PaneDirection.Right)
+...
+...     return {
+...         'window': window,
+...         'main': main_pane,
+...         'terminal': terminal_pane,
+...         'logs': log_pane,
+...     }
+
+>>> workspace = create_dev_workspace(session, 'my-project')
+>>> len(workspace['window'].panes)
+3
+
+>>> # Clean up
+>>> workspace['window'].kill()
+```
+
+### Recipe: Create a grid of panes
+
+```python
+>>> from libtmux.constants import PaneDirection
+
+>>> def create_pane_grid(session, rows=2, cols=2, name='grid'):
+...     """Create an NxM grid of panes."""
+...     window = session.new_window(window_name=name, attach=False)
+...     window.resize(height=50, width=160)
+...
+...     panes = []
+...     base_pane = window.active_pane
+...     panes.append(base_pane)
+...
+...     # Create first row of panes
+...     current = base_pane
+...     for _ in range(cols - 1):
+...         new_pane = current.split(direction=PaneDirection.Right)
+...         panes.append(new_pane)
+...         current = new_pane
+...
+...     # Create additional rows
+...     for _ in range(rows - 1):
+...         row_start = panes[-cols]
+...         current = row_start
+...         for col in range(cols):
+...             new_pane = panes[-cols + col].split(direction=PaneDirection.Below)
+...             panes.append(new_pane)
+...
+...     # Apply tiled layout for even distribution
+...     window.select_layout('tiled')
+...     return window, panes
+
+>>> grid_window, grid_panes = create_pane_grid(session, rows=2, cols=2, name='test-grid')
+>>> len(grid_panes) >= 4
+True
+
+>>> # Clean up
+>>> grid_window.kill()
+```
+
+### Recipe: Run commands in multiple panes
+
+```python
+>>> import time
+
+>>> def run_in_panes(panes, commands):
+...     """Run different commands in each pane."""
+...     for pane, cmd in zip(panes, commands):
+...         pane.send_keys(cmd)
+
+>>> multi_window = session.new_window(window_name='multi-cmd', attach=False)
+>>> multi_window.resize(height=40, width=120)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> pane_a = multi_window.active_pane
+>>> pane_b = multi_window.split()
+>>> pane_c = multi_window.split()
+
+>>> run_in_panes(
+...     [pane_a, pane_b, pane_c],
+...     ['echo "Task A"', 'echo "Task B"', 'echo "Task C"'],
+... )
+
+>>> # Give commands time to execute
+>>> time.sleep(0.2)
+
+>>> # Verify all commands ran
+>>> 'Task A' in '\\n'.join(pane_a.capture_pane())
+True
+
+>>> # Clean up
+>>> multi_window.kill()
+```
+
+## Window Context Managers
+
+Windows can be used as context managers for automatic cleanup:
+
+```python
+>>> with session.new_window(window_name='temp-window') as temp_win:
+...     pane = temp_win.active_pane
+...     pane.send_keys('echo "temporary workspace"')
+...     temp_win in session.windows
+True
+
+>>> # Window is automatically killed after exiting context
+>>> temp_win not in session.windows
+True
+```
+
+:::{seealso}
+- {ref}`pane-interaction` for working with pane content
+- {ref}`automation-patterns` for advanced orchestration
+- {class}`~libtmux.Window` for all window methods
+- {class}`~libtmux.Session` for session management
+:::

From 77362362cd3c747bed41d96b1f235094b72d5ac6 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 14:02:21 -0600
Subject: [PATCH 124/136] docs(topics): Add automation patterns guide with
 doctests

why: Advanced orchestration patterns needed for agentic workflow users
what:
- Add process control and status checking patterns
- Add output monitoring with completion markers
- Add multi-pane orchestration for parallel tasks
- Add timeout handling and retry patterns
- Add task queue and state machine examples
- All examples are runnable doctests
---
 docs/topics/automation_patterns.md | 481 +++++++++++++++++++++++++++++
 1 file changed, 481 insertions(+)
 create mode 100644 docs/topics/automation_patterns.md

diff --git a/docs/topics/automation_patterns.md b/docs/topics/automation_patterns.md
new file mode 100644
index 000000000..c0d00eb79
--- /dev/null
+++ b/docs/topics/automation_patterns.md
@@ -0,0 +1,481 @@
+(automation-patterns)=
+
+# Automation Patterns
+
+libtmux is ideal for automating terminal workflows, orchestrating multiple processes,
+and building agentic systems that interact with terminal applications. This guide covers
+practical patterns for automation use cases.
+
+Open two terminals:
+
+Terminal one: start tmux in a separate terminal:
+
+```console
+$ tmux
+```
+
+Terminal two, `python` or `ptpython` if you have it:
+
+```console
+$ python
+```
+
+## Process Control
+
+### Starting long-running processes
+
+```python
+>>> import time
+
+>>> proc_window = session.new_window(window_name='process', attach=False)
+>>> proc_pane = proc_window.active_pane
+
+>>> # Start a background process
+>>> proc_pane.send_keys('sleep 2 && echo "Process complete"')
+
+>>> # Process is running
+>>> time.sleep(0.1)
+>>> proc_window.window_name
+'process'
+
+>>> # Clean up
+>>> proc_window.kill()
+```
+
+### Checking process status
+
+```python
+>>> import time
+
+>>> status_window = session.new_window(window_name='status-check', attach=False)
+>>> status_pane = status_window.active_pane
+
+>>> def is_process_running(pane, marker='RUNNING'):
+...     """Check if a marker indicates process is still running."""
+...     output = pane.capture_pane()
+...     return marker in '\\n'.join(output)
+
+>>> # Start and mark a process
+>>> status_pane.send_keys('echo "RUNNING"; sleep 0.3; echo "DONE"')
+>>> time.sleep(0.1)
+
+>>> # Check while running
+>>> 'RUNNING' in '\\n'.join(status_pane.capture_pane())
+True
+
+>>> # Wait for completion
+>>> time.sleep(0.5)
+>>> 'DONE' in '\\n'.join(status_pane.capture_pane())
+True
+
+>>> # Clean up
+>>> status_window.kill()
+```
+
+## Output Monitoring
+
+### Waiting for specific output
+
+```python
+>>> import time
+
+>>> monitor_window = session.new_window(window_name='monitor', attach=False)
+>>> monitor_pane = monitor_window.active_pane
+
+>>> def wait_for_output(pane, text, timeout=5.0, poll_interval=0.1):
+...     """Wait for specific text to appear in pane output."""
+...     start = time.time()
+...     while time.time() - start < timeout:
+...         output = '\\n'.join(pane.capture_pane())
+...         if text in output:
+...             return True
+...         time.sleep(poll_interval)
+...     return False
+
+>>> monitor_pane.send_keys('sleep 0.2; echo "READY"')
+>>> wait_for_output(monitor_pane, 'READY', timeout=2.0)
+True
+
+>>> # Clean up
+>>> monitor_window.kill()
+```
+
+### Detecting errors in output
+
+```python
+>>> import time
+
+>>> error_window = session.new_window(window_name='error-check', attach=False)
+>>> error_pane = error_window.active_pane
+
+>>> def check_for_errors(pane, patterns=None):
+...     """Check pane output for error patterns."""
+...     if patterns is None:
+...         patterns = ['Error:', 'error:', 'ERROR', 'FAILED', 'Exception']
+...     output = '\\n'.join(pane.capture_pane())
+...     for pattern in patterns:
+...         if pattern in output:
+...             return pattern
+...     return None
+
+>>> # Test with successful output
+>>> error_pane.send_keys('echo "Success!"')
+>>> time.sleep(0.1)
+>>> check_for_errors(error_pane) is None
+True
+
+>>> # Clean up
+>>> error_window.kill()
+```
+
+### Capturing output between markers
+
+```python
+>>> import time
+
+>>> capture_window = session.new_window(window_name='capture', attach=False)
+>>> capture_pane = capture_window.active_pane
+
+>>> def capture_after_marker(pane, marker, timeout=5.0):
+...     """Capture output after a marker appears."""
+...     start_time = time.time()
+...     while time.time() - start_time < timeout:
+...         lines = pane.capture_pane()
+...         output = '\\n'.join(lines)
+...         if marker in output:
+...             # Return all lines after the marker
+...             found = False
+...             result = []
+...             for line in lines:
+...                 if marker in line:
+...                     found = True
+...                     continue
+...                 if found:
+...                     result.append(line)
+...             return result
+...         time.sleep(0.1)
+...     return None
+
+>>> # Test marker capture
+>>> capture_pane.send_keys('echo "MARKER"; echo "captured data"')
+>>> time.sleep(0.3)
+>>> result = capture_after_marker(capture_pane, 'MARKER', timeout=2.0)
+>>> any('captured' in line for line in (result or []))
+True
+
+>>> # Clean up
+>>> capture_window.kill()
+```
+
+## Multi-Pane Orchestration
+
+### Running parallel tasks
+
+```python
+>>> import time
+>>> from libtmux.constants import PaneDirection
+
+>>> parallel_window = session.new_window(window_name='parallel', attach=False)
+>>> parallel_window.resize(height=40, width=120)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> pane1 = parallel_window.active_pane
+>>> pane2 = pane1.split(direction=PaneDirection.Right)
+>>> pane3 = pane1.split(direction=PaneDirection.Below)
+
+>>> # Start tasks in parallel
+>>> tasks = [
+...     (pane1, 'echo "Task 1"; sleep 0.2; echo "DONE1"'),
+...     (pane2, 'echo "Task 2"; sleep 0.1; echo "DONE2"'),
+...     (pane3, 'echo "Task 3"; sleep 0.3; echo "DONE3"'),
+... ]
+
+>>> for pane, cmd in tasks:
+...     pane.send_keys(cmd)
+
+>>> # Wait for all tasks
+>>> time.sleep(0.5)
+
+>>> # Verify all completed
+>>> all('DONE' in '\\n'.join(p.capture_pane()) for p, _ in tasks)
+True
+
+>>> # Clean up
+>>> parallel_window.kill()
+```
+
+### Monitoring multiple panes for completion
+
+```python
+>>> import time
+>>> from libtmux.constants import PaneDirection
+
+>>> multi_window = session.new_window(window_name='multi-monitor', attach=False)
+>>> multi_window.resize(height=40, width=120)  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> panes = [multi_window.active_pane]
+>>> panes.append(panes[0].split(direction=PaneDirection.Right))
+>>> panes.append(panes[0].split(direction=PaneDirection.Below))
+
+>>> def wait_all_complete(panes, marker='COMPLETE', timeout=10.0):
+...     """Wait for all panes to show completion marker."""
+...     start = time.time()
+...     remaining = set(range(len(panes)))
+...     while remaining and time.time() - start < timeout:
+...         for i in list(remaining):
+...             if marker in '\\n'.join(panes[i].capture_pane()):
+...                 remaining.remove(i)
+...         time.sleep(0.1)
+...     return len(remaining) == 0
+
+>>> # Start tasks with different durations
+>>> for i, pane in enumerate(panes):
+...     pane.send_keys(f'sleep 0.{i+1}; echo "COMPLETE"')
+
+>>> # Wait for all
+>>> wait_all_complete(panes, 'COMPLETE', timeout=2.0)
+True
+
+>>> # Clean up
+>>> multi_window.kill()
+```
+
+## Context Manager Patterns
+
+### Temporary session for isolated work
+
+```python
+>>> # Create isolated session for a task
+>>> with server.new_session(session_name='temp-work') as temp_session:
+...     window = temp_session.new_window(window_name='task')
+...     pane = window.active_pane
+...     pane.send_keys('echo "Isolated work"')
+...     # Session exists during work
+...     temp_session in server.sessions
+True
+
+>>> # Session automatically killed after context
+>>> temp_session not in server.sessions
+True
+```
+
+### Temporary window for subtask
+
+```python
+>>> import time
+
+>>> with session.new_window(window_name='subtask') as sub_window:
+...     pane = sub_window.active_pane
+...     pane.send_keys('echo "Subtask running"')
+...     time.sleep(0.1)
+...     'Subtask' in '\\n'.join(pane.capture_pane())
+True
+
+>>> # Window cleaned up automatically
+>>> sub_window not in session.windows
+True
+```
+
+## Timeout Handling
+
+### Command with timeout
+
+```python
+>>> import time
+
+>>> timeout_window = session.new_window(window_name='timeout-demo', attach=False)
+>>> timeout_pane = timeout_window.active_pane
+
+>>> class CommandTimeout(Exception):
+...     """Raised when a command times out."""
+...     pass
+
+>>> def run_with_timeout(pane, command, marker='__DONE__', timeout=5.0):
+...     """Run command and wait for completion with timeout."""
+...     pane.send_keys(f'{command}; echo {marker}')
+...     start = time.time()
+...     while time.time() - start < timeout:
+...         output = '\\n'.join(pane.capture_pane())
+...         if marker in output:
+...             return output
+...         time.sleep(0.1)
+...     raise CommandTimeout(f'Command timed out after {timeout}s')
+
+>>> # Test successful command
+>>> result = run_with_timeout(timeout_pane, 'echo "fast"', timeout=2.0)
+>>> 'fast' in result
+True
+
+>>> # Clean up
+>>> timeout_window.kill()
+```
+
+### Retry pattern
+
+```python
+>>> import time
+
+>>> retry_window = session.new_window(window_name='retry-demo', attach=False)
+>>> retry_pane = retry_window.active_pane
+
+>>> def retry_until_success(pane, command, success_marker, max_retries=3, delay=0.5):
+...     """Retry command until success marker appears."""
+...     for attempt in range(max_retries):
+...         pane.send_keys(command)
+...         time.sleep(delay)
+...         output = '\\n'.join(pane.capture_pane())
+...         if success_marker in output:
+...             return True, attempt + 1
+...     return False, max_retries
+
+>>> # Test retry
+>>> success, attempts = retry_until_success(
+...     retry_pane, 'echo "OK"', 'OK', max_retries=3, delay=0.2
+... )
+>>> success
+True
+>>> attempts
+1
+
+>>> # Clean up
+>>> retry_window.kill()
+```
+
+## Agentic Workflow Patterns
+
+### Task queue processor
+
+```python
+>>> import time
+
+>>> queue_window = session.new_window(window_name='queue', attach=False)
+>>> queue_pane = queue_window.active_pane
+
+>>> def process_task_queue(pane, tasks, completion_marker='TASK_DONE'):
+...     """Process a queue of tasks sequentially."""
+...     results = []
+...     for i, task in enumerate(tasks):
+...         pane.send_keys(f'{task}; echo "{completion_marker}_{i}"')
+...         # Wait for this task to complete
+...         start = time.time()
+...         while time.time() - start < 5.0:
+...             output = '\\n'.join(pane.capture_pane())
+...             if f'{completion_marker}_{i}' in output:
+...                 results.append((i, True))
+...                 break
+...             time.sleep(0.1)
+...         else:
+...             results.append((i, False))
+...     return results
+
+>>> tasks = ['echo "Step 1"', 'echo "Step 2"', 'echo "Step 3"']
+>>> results = process_task_queue(queue_pane, tasks)
+>>> all(success for _, success in results)
+True
+
+>>> # Clean up
+>>> queue_window.kill()
+```
+
+### State machine runner
+
+```python
+>>> import time
+
+>>> state_window = session.new_window(window_name='state-machine', attach=False)
+>>> state_pane = state_window.active_pane
+
+>>> def run_state_machine(pane, states, timeout_per_state=2.0):
+...     """Run through a series of states with transitions."""
+...     current_state = 0
+...     history = []
+...
+...     while current_state < len(states):
+...         state_name, command, next_marker = states[current_state]
+...         pane.send_keys(command)
+...
+...         start = time.time()
+...         while time.time() - start < timeout_per_state:
+...             output = '\\n'.join(pane.capture_pane())
+...             if next_marker in output:
+...                 history.append(state_name)
+...                 current_state += 1
+...                 break
+...             time.sleep(0.1)
+...         else:
+...             return history, False  # Timeout
+...
+...     return history, True
+
+>>> states = [
+...     ('init', 'echo "INIT_DONE"', 'INIT_DONE'),
+...     ('process', 'echo "PROCESS_DONE"', 'PROCESS_DONE'),
+...     ('cleanup', 'echo "CLEANUP_DONE"', 'CLEANUP_DONE'),
+... ]
+
+>>> history, success = run_state_machine(state_pane, states)
+>>> success
+True
+>>> len(history)
+3
+
+>>> # Clean up
+>>> state_window.kill()
+```
+
+## Best Practices
+
+### 1. Always use markers for completion detection
+
+Instead of relying on timing, use explicit markers:
+
+```python
+>>> bp_window = session.new_window(window_name='best-practice', attach=False)
+>>> bp_pane = bp_window.active_pane
+
+>>> # Good: Use completion marker
+>>> bp_pane.send_keys('long_command; echo "__DONE__"')
+
+>>> # Then poll for marker
+>>> import time
+>>> time.sleep(0.2)
+>>> '__DONE__' in '\\n'.join(bp_pane.capture_pane())
+True
+
+>>> bp_window.kill()
+```
+
+### 2. Clean up resources
+
+Always clean up windows and sessions when done:
+
+```python
+>>> cleanup_window = session.new_window(window_name='cleanup-demo', attach=False)
+>>> cleanup_window  # doctest: +ELLIPSIS
+Window(@... ...)
+
+>>> # Do work...
+
+>>> # Always clean up
+>>> cleanup_window.kill()
+>>> cleanup_window not in session.windows
+True
+```
+
+### 3. Use context managers for automatic cleanup
+
+```python
+>>> # Context managers ensure cleanup even on exceptions
+>>> with session.new_window(window_name='safe-work') as safe_window:
+...     pane = safe_window.active_pane
+...     # Work happens here
+...     pass  # Even if exception occurs, window is cleaned up
+```
+
+:::{seealso}
+- {ref}`pane-interaction` for basic pane operations
+- {ref}`workspace-setup` for creating workspace layouts
+- {ref}`context-managers` for resource management patterns
+- {class}`~libtmux.Pane` for all pane methods
+:::

From 76aa8d790552a9a80c9dffc4d23235cebba16033 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 14:02:28 -0600
Subject: [PATCH 125/136] docs(topics): Add new guides to toctree

why: New topic guides need to be discoverable in documentation
what:
- Add pane_interaction to toctree
- Add workspace_setup to toctree
- Add automation_patterns to toctree
- Order topics in logical learning progression
---
 docs/topics/index.md | 7 +++++--
 1 file changed, 5 insertions(+), 2 deletions(-)

diff --git a/docs/topics/index.md b/docs/topics/index.md
index 88bfc9860..81a383942 100644
--- a/docs/topics/index.md
+++ b/docs/topics/index.md
@@ -4,11 +4,14 @@ orphan: true
 
 # Topics
 
-Explore libtmux’s core functionalities and underlying principles at a high level, while providing essential context and detailed explanations to help you understand its design and usage.
+Explore libtmux's core functionalities and underlying principles at a high level, while providing essential context and detailed explanations to help you understand its design and usage.
 
 ```{toctree}
 
-context_managers
 traversal
+pane_interaction
+workspace_setup
+automation_patterns
+context_managers
 options_and_hooks
 ```

From deef8bfc8de036b43dbcf8d725710b9313be3fb6 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 14:49:11 -0600
Subject: [PATCH 126/136] docs(topics): add QueryList filtering topic

why: Following libvcs pattern, document the Django-style filtering API
that powers session/window/pane collections.

what:
- Add comprehensive filtering.md topic with working doctests
- Cover all lookup operators: exact, contains, startswith, endswith,
  regex, in/nin, and case-insensitive variants
- Show chaining filters, get() with defaults, list membership
- Include real-world examples (editor windows, naming conventions)
- Add to topics index after traversal
- All 12 doctests pass
---
 docs/topics/filtering.md | 263 +++++++++++++++++++++++++++++++++++++++
 docs/topics/index.md     |   1 +
 2 files changed, 264 insertions(+)
 create mode 100644 docs/topics/filtering.md

diff --git a/docs/topics/filtering.md b/docs/topics/filtering.md
new file mode 100644
index 000000000..bb71f81b7
--- /dev/null
+++ b/docs/topics/filtering.md
@@ -0,0 +1,263 @@
+(querylist-filtering)=
+
+# QueryList Filtering
+
+libtmux uses `QueryList` to enable Django-style filtering on tmux objects.
+Every collection (`server.sessions`, `session.windows`, `window.panes`) returns
+a `QueryList`, letting you filter sessions, windows, and panes with a fluent,
+chainable API.
+
+## Basic Filtering
+
+The `filter()` method accepts keyword arguments with optional lookup suffixes:
+
+```python
+>>> server.sessions  # doctest: +ELLIPSIS
+[Session($... ...)]
+```
+
+### Exact Match
+
+The default lookup is `exact`:
+
+```python
+>>> # These are equivalent
+>>> server.sessions.filter(session_name=session.session_name)  # doctest: +ELLIPSIS
+[Session($... ...)]
+>>> server.sessions.filter(session_name__exact=session.session_name)  # doctest: +ELLIPSIS
+[Session($... ...)]
+```
+
+### Contains and Startswith
+
+Use suffixes for partial matching:
+
+```python
+>>> # Create windows for this example
+>>> w1 = session.new_window(window_name="api-server")
+>>> w2 = session.new_window(window_name="api-worker")
+>>> w3 = session.new_window(window_name="web-frontend")
+
+>>> # Windows containing 'api'
+>>> api_windows = session.windows.filter(window_name__contains='api')
+>>> len(api_windows) >= 2
+True
+
+>>> # Windows starting with 'web'
+>>> web_windows = session.windows.filter(window_name__startswith='web')
+>>> len(web_windows) >= 1
+True
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+## Available Lookups
+
+| Lookup | Description |
+|--------|-------------|
+| `exact` | Exact match (default) |
+| `iexact` | Case-insensitive exact match |
+| `contains` | Substring match |
+| `icontains` | Case-insensitive substring |
+| `startswith` | Prefix match |
+| `istartswith` | Case-insensitive prefix |
+| `endswith` | Suffix match |
+| `iendswith` | Case-insensitive suffix |
+| `in` | Value in list |
+| `nin` | Value not in list |
+| `regex` | Regular expression match |
+| `iregex` | Case-insensitive regex |
+
+## Getting a Single Item
+
+Use `get()` to retrieve exactly one matching item:
+
+```python
+>>> window = session.windows.get(window_id=session.active_window.window_id)
+>>> window  # doctest: +ELLIPSIS
+Window(@... ..., Session($... ...))
+```
+
+If no match or multiple matches are found, `get()` raises an exception:
+
+- `ObjectDoesNotExist` - no matching object found
+- `MultipleObjectsReturned` - more than one object matches
+
+You can provide a default value to avoid the exception:
+
+```python
+>>> session.windows.get(window_name="nonexistent", default=None) is None
+True
+```
+
+## Chaining Filters
+
+Filters can be chained for complex queries:
+
+```python
+>>> # Create windows for this example
+>>> w1 = session.new_window(window_name="feature-login")
+>>> w2 = session.new_window(window_name="feature-signup")
+>>> w3 = session.new_window(window_name="bugfix-typo")
+
+>>> # Multiple conditions in one filter (AND)
+>>> session.windows.filter(
+...     window_name__startswith='feature',
+...     window_name__endswith='signup'
+... )  # doctest: +ELLIPSIS
+[Window(@... ...:feature-signup, Session($... ...))]
+
+>>> # Chained filters (also AND)
+>>> session.windows.filter(
+...     window_name__contains='feature'
+... ).filter(
+...     window_name__contains='login'
+... )  # doctest: +ELLIPSIS
+[Window(@... ...:feature-login, Session($... ...))]
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+## Case-Insensitive Filtering
+
+Use `i` prefix variants for case-insensitive matching:
+
+```python
+>>> # Create windows with mixed case
+>>> w1 = session.new_window(window_name="MyApp-Server")
+>>> w2 = session.new_window(window_name="myapp-worker")
+
+>>> # Case-insensitive contains
+>>> myapp_windows = session.windows.filter(window_name__icontains='MYAPP')
+>>> len(myapp_windows) >= 2
+True
+
+>>> # Case-insensitive startswith
+>>> session.windows.filter(window_name__istartswith='myapp')  # doctest: +ELLIPSIS
+[Window(@... ...:MyApp-Server, Session($... ...)), Window(@... ...:myapp-worker, Session($... ...))]
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+```
+
+## Regex Filtering
+
+For complex patterns, use regex lookups:
+
+```python
+>>> # Create windows with version-like names
+>>> w1 = session.new_window(window_name="app-v1.0")
+>>> w2 = session.new_window(window_name="app-v2.0")
+>>> w3 = session.new_window(window_name="app-beta")
+
+>>> # Match version pattern
+>>> versioned = session.windows.filter(window_name__regex=r'v\d+\.\d+$')
+>>> len(versioned) >= 2
+True
+
+>>> # Case-insensitive regex
+>>> session.windows.filter(window_name__iregex=r'BETA')  # doctest: +ELLIPSIS
+[Window(@... ...:app-beta, Session($... ...))]
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+## Filtering by List Membership
+
+Use `in` and `nin` (not in) for list-based filtering:
+
+```python
+>>> # Create test windows
+>>> w1 = session.new_window(window_name="dev")
+>>> w2 = session.new_window(window_name="staging")
+>>> w3 = session.new_window(window_name="prod")
+
+>>> # Filter windows in a list of names
+>>> target_envs = ["dev", "prod"]
+>>> session.windows.filter(window_name__in=target_envs)  # doctest: +ELLIPSIS
+[Window(@... ...:dev, Session($... ...)), Window(@... ...:prod, Session($... ...))]
+
+>>> # Filter windows NOT in a list
+>>> non_prod = session.windows.filter(window_name__nin=["prod"])
+>>> any(w.window_name == "prod" for w in non_prod)
+False
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+## Filtering Across the Hierarchy
+
+Filter at any level of the tmux hierarchy:
+
+```python
+>>> # All panes across all windows in the server
+>>> server.panes  # doctest: +ELLIPSIS
+[Pane(%... Window(@... ..., Session($... ...)))]
+
+>>> # Filter panes by their window's name
+>>> pane = session.active_pane
+>>> pane  # doctest: +ELLIPSIS
+Pane(%... Window(@... ..., Session($... ...)))
+```
+
+## Real-World Examples
+
+### Find all editor windows
+
+```python
+>>> # Create sample windows
+>>> w1 = session.new_window(window_name="vim-main")
+>>> w2 = session.new_window(window_name="nvim-config")
+>>> w3 = session.new_window(window_name="shell")
+
+>>> # Find vim/nvim windows
+>>> editors = session.windows.filter(window_name__iregex=r'n?vim')
+>>> len(editors) >= 2
+True
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+### Find windows by naming convention
+
+```python
+>>> # Create windows following a naming convention
+>>> w1 = session.new_window(window_name="project:frontend")
+>>> w2 = session.new_window(window_name="project:backend")
+>>> w3 = session.new_window(window_name="logs")
+
+>>> # Find all project windows
+>>> project_windows = session.windows.filter(window_name__startswith='project:')
+>>> len(project_windows) >= 2
+True
+
+>>> # Get specific project window
+>>> backend = session.windows.get(window_name='project:backend')
+>>> backend.window_name
+'project:backend'
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+## API Reference
+
+See {class}`~libtmux._internal.query_list.QueryList` for the complete API.
diff --git a/docs/topics/index.md b/docs/topics/index.md
index 81a383942..f22e7f81b 100644
--- a/docs/topics/index.md
+++ b/docs/topics/index.md
@@ -9,6 +9,7 @@ Explore libtmux's core functionalities and underlying principles at a high level
 ```{toctree}
 
 traversal
+filtering
 pane_interaction
 workspace_setup
 automation_patterns

From e36069b7a2fa78ec36cd531b9d5a1420dd5ad291 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 14:50:12 -0600
Subject: [PATCH 127/136] docs(topics/traversal): add rich filtering examples

why: The traversal topic had minimal filtering coverage. Users need
practical examples of partial matching, case-insensitive search,
regex patterns, and filter chaining.

what:
- Add cross-reference to new filtering topic
- Add partial matching examples (__contains, __startswith, __endswith)
- Add case-insensitive matching examples (__istartswith)
- Add regex filtering examples (__regex)
- Add filter chaining examples (multiple conditions, chained calls)
- Add get() with default parameter example
- All 23 traversal doctests pass
---
 docs/topics/traversal.md | 110 ++++++++++++++++++++++++++++++++++++++-
 1 file changed, 109 insertions(+), 1 deletion(-)

diff --git a/docs/topics/traversal.md b/docs/topics/traversal.md
index 5493ae7c4..214bbc861 100644
--- a/docs/topics/traversal.md
+++ b/docs/topics/traversal.md
@@ -136,7 +136,12 @@ True
 
 ## Filtering and Finding Objects
 
-Find windows by index:
+libtmux collections support Django-style filtering with `filter()` and `get()`.
+For comprehensive coverage of all lookup operators, see {ref}`querylist-filtering`.
+
+### Basic Filtering
+
+Find windows by exact attribute match:
 
 ```python
 >>> session.windows.filter(window_index=window.window_index)  # doctest: +ELLIPSIS
@@ -150,6 +155,109 @@ Get a specific pane by ID:
 Pane(%... Window(@... ..., Session($... ...)))
 ```
 
+### Partial Matching
+
+Use lookup suffixes like `__contains`, `__startswith`, `__endswith`:
+
+```python
+>>> # Create windows to demonstrate filtering
+>>> w1 = session.new_window(window_name="app-frontend")
+>>> w2 = session.new_window(window_name="app-backend")
+>>> w3 = session.new_window(window_name="logs")
+
+>>> # Find windows starting with 'app-'
+>>> session.windows.filter(window_name__startswith='app-')  # doctest: +ELLIPSIS
+[Window(@... ...:app-frontend, Session($... ...)), Window(@... ...:app-backend, Session($... ...))]
+
+>>> # Find windows containing 'end'
+>>> session.windows.filter(window_name__contains='end')  # doctest: +ELLIPSIS
+[Window(@... ...:app-frontend, Session($... ...)), Window(@... ...:app-backend, Session($... ...))]
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+### Case-Insensitive Matching
+
+Prefix any lookup with `i` for case-insensitive matching:
+
+```python
+>>> # Create windows with mixed case
+>>> w1 = session.new_window(window_name="MyApp")
+>>> w2 = session.new_window(window_name="myapp-worker")
+
+>>> # Case-insensitive search
+>>> session.windows.filter(window_name__istartswith='myapp')  # doctest: +ELLIPSIS
+[Window(@... ...:MyApp, Session($... ...)), Window(@... ...:myapp-worker, Session($... ...))]
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+```
+
+### Regex Filtering
+
+For complex patterns, use `__regex` or `__iregex`:
+
+```python
+>>> # Create versioned windows
+>>> w1 = session.new_window(window_name="release-v1.0")
+>>> w2 = session.new_window(window_name="release-v2.0")
+>>> w3 = session.new_window(window_name="dev")
+
+>>> # Match semantic version pattern
+>>> session.windows.filter(window_name__regex=r'v\d+\.\d+')  # doctest: +ELLIPSIS
+[Window(@... ...:release-v1.0, Session($... ...)), Window(@... ...:release-v2.0, Session($... ...))]
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+### Chaining Filters
+
+Multiple conditions can be combined:
+
+```python
+>>> # Create windows for chaining example
+>>> w1 = session.new_window(window_name="api-prod")
+>>> w2 = session.new_window(window_name="api-staging")
+>>> w3 = session.new_window(window_name="web-prod")
+
+>>> # Multiple conditions in one call (AND)
+>>> session.windows.filter(
+...     window_name__startswith='api',
+...     window_name__endswith='prod'
+... )  # doctest: +ELLIPSIS
+[Window(@... ...:api-prod, Session($... ...))]
+
+>>> # Chained calls (also AND)
+>>> session.windows.filter(
+...     window_name__contains='api'
+... ).filter(
+...     window_name__contains='staging'
+... )  # doctest: +ELLIPSIS
+[Window(@... ...:api-staging, Session($... ...))]
+
+>>> # Clean up
+>>> w1.kill()
+>>> w2.kill()
+>>> w3.kill()
+```
+
+### Get with Default
+
+Avoid exceptions when an object might not exist:
+
+```python
+>>> # Returns None instead of raising ObjectDoesNotExist
+>>> session.windows.get(window_name="nonexistent", default=None) is None
+True
+```
+
 ## Checking Relationships
 
 Check if objects are related:

From 4380cb358358fea0f5e816e1bf78fa2362f8c829 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sat, 29 Nov 2025 18:26:23 -0600
Subject: [PATCH 128/136] docs(README): add hero, pitch, and install quickstart

---
 README.md | 358 ++++++++++++++++++++++++++++--------------------------
 1 file changed, 183 insertions(+), 175 deletions(-)

diff --git a/README.md b/README.md
index efd324b67..3b2956ef5 100644
--- a/README.md
+++ b/README.md
@@ -1,51 +1,101 @@
-# libtmux
+<div align="center">
+  <h1>⚙️ libtmux</h1>
+  <p><strong>Drive tmux from Python: typed, object-oriented control over servers, sessions, windows, and panes.</strong></p>
+  <p>
+    <a href="https://libtmux.git-pull.com/"><img src="https://raw.githubusercontent.com/tmux-python/libtmux/master/docs/_static/img/libtmux.svg" alt="libtmux logo" height="120"></a>
+  </p>
+  <p>
+    <a href="https://pypi.org/project/libtmux/"><img src="https://img.shields.io/pypi/v/libtmux.svg" alt="PyPI version"></a>
+    <a href="https://libtmux.git-pull.com/"><img src="https://github.com/tmux-python/libtmux/workflows/docs/badge.svg" alt="Docs status"></a>
+    <a href="https://github.com/tmux-python/libtmux/actions"><img src="https://github.com/tmux-python/libtmux/workflows/tests/badge.svg" alt="Tests status"></a>
+    <a href="https://codecov.io/gh/tmux-python/libtmux"><img src="https://codecov.io/gh/tmux-python/libtmux/branch/master/graph/badge.svg" alt="Coverage"></a>
+    <a href="https://github.com/tmux-python/libtmux/blob/master/LICENSE"><img src="https://img.shields.io/github/license/tmux-python/libtmux.svg" alt="License"></a>
+  </p>
+</div>
 
-`libtmux` is a [typed](https://docs.python.org/3/library/typing.html) Python library that provides a wrapper for interacting programmatically with tmux, a terminal multiplexer. You can use it to manage tmux servers,
-sessions, windows, and panes. Additionally, `libtmux` powers [tmuxp], a tmux workspace manager.
+---
 
-[![Python Package](https://img.shields.io/pypi/v/libtmux.svg)](https://pypi.org/project/libtmux/)
-[![Docs](https://github.com/tmux-python/libtmux/workflows/docs/badge.svg)](https://libtmux.git-pull.com/)
-[![Build Status](https://github.com/tmux-python/libtmux/workflows/tests/badge.svg)](https://github.com/tmux-python/libtmux/actions?query=workflow%3A%22tests%22)
-[![Code Coverage](https://codecov.io/gh/tmux-python/libtmux/branch/master/graph/badge.svg)](https://codecov.io/gh/tmux-python/libtmux)
-[![License](https://img.shields.io/github/license/tmux-python/libtmux.svg)](https://github.com/tmux-python/libtmux/blob/master/LICENSE)
+## 🐍 What is libtmux?
 
-libtmux builds upon tmux's
-[target](http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#COMMANDS) and
-[formats](http://man.openbsd.org/OpenBSD-5.9/man1/tmux.1#FORMATS) to
-create an object mapping to traverse, inspect and interact with live
-tmux sessions.
+libtmux is a typed Python API over [tmux], the terminal multiplexer. Stop shelling out and parsing `tmux ls`. Instead, interact with real Python objects: `Server`, `Session`, `Window`, and `Pane`. The same API powers [tmuxp], so it stays battle-tested in real-world workflows.
 
-View the [documentation](https://libtmux.git-pull.com/),
-[API](https://libtmux.git-pull.com/api.html) information and
-[architectural details](https://libtmux.git-pull.com/about.html).
+### ✨ Features
 
-# Install
+- Typed, object-oriented control of tmux state
+- Query and traverse live sessions, windows, and panes
+- Raw escape hatch via `.cmd(...)` on any object
+- Works with multiple tmux sockets and servers
+- Context managers for automatic cleanup
+- pytest plugin for isolated tmux fixtures
+- Proven in production via tmuxp and other tooling
 
-```console
-$ pip install --user libtmux
+## Requirements & support
+
+- tmux: >= 3.2a
+- Python: >= 3.10 (CPython and PyPy)
+
+Maintenance-only backports (no new fixes):
+
+- Python 2.x: [`v0.8.x`](https://github.com/tmux-python/libtmux/tree/v0.8.x)
+- tmux 1.8-3.1c: [`v0.48.x`](https://github.com/tmux-python/libtmux/tree/v0.48.x)
+
+## 📦 Installation
+
+Stable release:
+
+```bash
+pip install libtmux
 ```
 
-# Open a tmux session
+With pipx:
 
-Session name `foo`, window name `bar`
+```bash
+pipx install libtmux
+```
 
-```console
-$ tmux new-session -s foo -n bar
+With uv / uvx:
+
+```bash
+uv add libtmux
+uvx --from "libtmux" python
 ```
 
-# Pilot your tmux session via python
+From the main branch (bleeding edge):
 
-```console
-$ python
+```bash
+pip install 'git+https://github.com/tmux-python/libtmux.git'
+```
+
+Tip: libtmux is pre-1.0. Pin a range in projects to avoid surprises:
+
+requirements.txt:
+
+```ini
+libtmux==0.49.*
+```
+
+pyproject.toml:
+
+```toml
+libtmux = "0.49.*"
 ```
 
-Use [ptpython], [ipython], etc. for a nice shell with autocompletions:
+## 🚀 Quickstart
+
+### Open a tmux session
+
+First, start a tmux session to connect to:
 
 ```console
-$ pip install --user ptpython
+$ tmux new-session -s foo -n bar
 ```
 
+### Pilot your tmux session via Python
+
+Use [ptpython], [ipython], etc. for a nice REPL with autocompletions:
+
 ```console
+$ pip install --user ptpython
 $ ptpython
 ```
 
@@ -58,17 +108,16 @@ Connect to a live tmux session:
 Server(socket_path=/tmp/tmux-.../default)
 ```
 
-Tip: You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your
-current tmux server / session / window pane.
+**Tip:** You can also use [tmuxp]'s [`tmuxp shell`] to drop straight into your
+current tmux server / session / window / pane.
 
-[tmuxp]: https://tmuxp.git-pull.com/
-[`tmuxp shell`]: https://tmuxp.git-pull.com/cli/shell.html
 [ptpython]: https://github.com/prompt-toolkit/ptpython
 [ipython]: https://ipython.org/
+[`tmuxp shell`]: https://tmuxp.git-pull.com/cli/shell.html
 
-Run any tmux command, respective of context:
+### Run any tmux command
 
-Honors tmux socket name and path:
+Every object has a `.cmd()` escape hatch that honors socket name and path:
 
 ```python
 >>> server = Server(socket_name='libtmux_doctest')
@@ -76,205 +125,164 @@ Honors tmux socket name and path:
 <libtmux...>
 ```
 
-New session:
+Create a new session:
 
 ```python
 >>> server.cmd('new-session', '-d', '-P', '-F#{session_id}').stdout[0]
-'$2'
-```
-
-```python
->>> session.cmd('new-window', '-P').stdout[0]
-'libtmux...:2.0'
-```
-
-From raw command output, to a rich `Window` object (in practice and as shown
-later, you'd use `Session.new_window()`):
-
-```python
->>> Window.from_window_id(window_id=session.cmd('new-window', '-P', '-F#{window_id}').stdout[0], server=session.server)
-Window(@2 2:..., Session($1 libtmux_...))
-```
-
-Create a pane from a window:
-
-```python
->>> window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0]
-'%2'
-```
-
-Raw output directly to a `Pane`:
-
-```python
->>> Pane.from_pane_id(pane_id=window.cmd('split-window', '-P', '-F#{pane_id}').stdout[0], server=window.server)
-Pane(%... Window(@1 1:..., Session($1 libtmux_...)))
+'$...'
 ```
 
-List sessions:
+### List and filter sessions
 
 ```python
 >>> server.sessions
-[Session($1 ...), Session($0 ...)]
+[Session($... ...), ...]
 ```
 
-Filter sessions by attribute:
+Filter by attribute:
 
 ```python
 >>> server.sessions.filter(history_limit='2000')
-[Session($1 ...), Session($0 ...)]
+[Session($... ...), ...]
 ```
 
 Direct lookup:
 
 ```python
->>> server.sessions.get(session_id="$1")
-Session($1 ...)
+>>> server.sessions.get(session_id=session.session_id)
+Session($... ...)
 ```
 
-Filter sessions:
+### Control sessions and windows
 
 ```python
->>> server.sessions[0].rename_session('foo')
-Session($1 foo)
->>> server.sessions.filter(session_name="foo")
-[Session($1 foo)]
->>> server.sessions.get(session_name="foo")
-Session($1 foo)
-```
-
-Control your session:
-
-```python
->>> session
-Session($1 ...)
-
 >>> session.rename_session('my-session')
-Session($1 my-session)
+Session($... my-session)
 ```
 
 Create new window in the background (don't switch to it):
 
 ```python
->>> bg_window = session.new_window(attach=False, window_name="ha in the bg")
+>>> bg_window = session.new_window(attach=False, window_name="bg-work")
 >>> bg_window
-Window(@... 2:ha in the bg, Session($1 ...))
+Window(@... ...:bg-work, Session($... ...))
 
-# Session can search the window
->>> session.windows.filter(window_name__startswith="ha")
-[Window(@... 2:ha in the bg, Session($1 ...))]
+>>> session.windows.filter(window_name__startswith="bg")
+[Window(@... ...:bg-work, Session($... ...))]
 
-# Directly
->>> session.windows.get(window_name__startswith="ha")
-Window(@... 2:ha in the bg, Session($1 ...))
+>>> session.windows.get(window_name__startswith="bg")
+Window(@... ...:bg-work, Session($... ...))
 
-# Clean up
 >>> bg_window.kill()
 ```
 
-Close window:
-
-```python
->>> w = session.active_window
->>> w.kill()
-```
-
-Grab remaining tmux window:
-
-```python
->>> window = session.active_window
->>> window.split(attach=False)
-Pane(%2 Window(@1 1:... Session($1 ...)))
-```
-
-Rename window:
-
-```python
->>> window.rename_window('libtmuxower')
-Window(@1 1:libtmuxower, Session($1 ...))
-```
-
-Split window (create a new pane):
+### Split windows and send keys
 
 ```python
->>> pane = window.split()
->>> pane = window.split(attach=False)
->>> pane.select()
-Pane(%3 Window(@1 1:..., Session($1 ...)))
->>> window = session.new_window(attach=False, window_name="test")
->>> window
-Window(@2 2:test, Session($1 ...))
 >>> pane = window.split(attach=False)
 >>> pane
-Pane(%5 Window(@2 2:test, Session($1 ...)))
+Pane(%... Window(@... ...:..., Session($... ...)))
 ```
 
-Type inside the pane (send key strokes):
+Type inside the pane (send keystrokes):
 
 ```python
->>> pane.send_keys('echo hey send now')
-
+>>> pane.send_keys('echo hello')
 >>> pane.send_keys('echo hey', enter=False)
 >>> pane.enter()
-Pane(%1 ...)
+Pane(%... ...)
 ```
 
-Grab the output of pane:
+### Capture pane output
 
 ```python
->>> pane.clear()  # clear the pane
-Pane(%1 ...)
->>> pane.send_keys("cowsay 'hello'", enter=True)
->>> print('\n'.join(pane.cmd('capture-pane', '-p').stdout))  # doctest: +SKIP
-$ cowsay 'hello'
- _______
-< hello >
- -------
-        \   ^__^
-         \  (oo)\_______
-            (__)\       )\/\
-                ||----w |
-                ||     ||
-...
+>>> pane.clear()
+Pane(%... ...)
+>>> pane.send_keys("echo 'hello world'", enter=True)
+>>> pane.cmd('capture-pane', '-p').stdout  # doctest: +SKIP
+["$ echo 'hello world'", 'hello world', '$']
 ```
 
-Traverse and navigate:
+### Traverse the hierarchy
+
+Navigate from pane up to window to session:
 
 ```python
 >>> pane.window
-Window(@1 1:..., Session($1 ...))
+Window(@... ...:..., Session($... ...))
 >>> pane.window.session
-Session($1 ...)
+Session($... ...)
 ```
 
-# Backports
-
-Unsupported / no security releases or bug fixes:
+## Core concepts
 
-- Python 2.x: The backports branch is
-  [`v0.8.x`](https://github.com/tmux-python/libtmux/tree/v0.8.x).
-- tmux 1.8 to 3.1c: The backports branch is
-  [`v0.48.x`](https://github.com/tmux-python/libtmux/tree/v0.48.x).
+| libtmux object | tmux concept                | Notes                          |
+|----------------|-----------------------------|--------------------------------|
+| `Server`       | tmux server / socket        | Entry point; owns sessions     |
+| `Session`      | tmux session (`$0`, `$1`,...) | Owns windows                   |
+| `Window`       | tmux window (`@1`, `@2`,...)  | Owns panes                     |
+| `Pane`         | tmux pane (`%1`, `%2`,...)    | Where commands run             |
 
-# Donations
+Collections are live and queryable:
 
-Your donations fund development of new features, testing and support.
-Your money will go directly to maintenance and development of the
-project. If you are an individual, feel free to give whatever feels
-right for the value you get out of the project.
-
-See donation options at <https://tony.sh/support.html>.
-
-# Project details
+```python
+server = libtmux.Server()
+session = server.sessions.get(session_name="demo")
+api_windows = session.windows.filter(window_name__startswith="api")
+pane = session.active_window.active_pane
+pane.send_keys("echo 'hello from libtmux'", enter=True)
+```
 
-- tmux support: >= 3.2a
-- python support: >= 3.10, pypy, pypy3
-- Source: <https://github.com/tmux-python/libtmux>
-- Docs: <https://libtmux.git-pull.com>
-- API: <https://libtmux.git-pull.com/api.html>
-- Changelog: <https://libtmux.git-pull.com/history.html>
-- Issues: <https://github.com/tmux-python/libtmux/issues>
-- Test Coverage: <https://codecov.io/gh/tmux-python/libtmux>
-- pypi: <https://pypi.python.org/pypi/libtmux>
-- Open Hub: <https://www.openhub.net/p/libtmux-python>
-- Repology: <https://repology.org/project/python:libtmux/versions>
-- License: [MIT](http://opensource.org/licenses/MIT).
+## tmux vs libtmux vs tmuxp
+
+| Tool    | Layer                      | Typical use case                                   |
+|---------|----------------------------|----------------------------------------------------|
+| tmux    | CLI / terminal multiplexer | Everyday terminal usage, manual control            |
+| libtmux | Python API over tmux       | Programmatic control, automation, testing          |
+| tmuxp   | App on top of libtmux      | Declarative tmux workspaces from YAML / TOML       |
+
+## Testing & fixtures
+
+- [pytest plugin][pytest-plugin] provides fresh tmux server/session/window/pane fixtures
+- Temporary HOME and tmux config fixtures keep indices stable
+- `TestServer` helper spins up multiple isolated tmux servers
+
+[pytest-plugin]: https://libtmux.git-pull.com/pytest-plugin/index.html
+
+## When you might not need libtmux
+
+- Layouts are static and live entirely in tmux config files
+- You do not need to introspect or control running tmux from other tools
+- Python is unavailable where tmux is running
+
+## Project links
+
+- Docs: [docs]
+- API reference: [api]
+- Architecture: [architecture]
+- Changelog: [history]
+- Migration notes: [migration]
+- Issues: [issues]
+- Test coverage: [coverage]
+- Releases: [releases]
+- License: [license]
+- Support: [support]
+- **[The Tao of tmux][tao]** — deep-dive book on tmux fundamentals
+
+## Contributing & support
+
+Contributions are welcome. Please open an issue or PR if you find a bug or want to improve the API or docs. If libtmux helps you ship, consider sponsoring development via [support].
+
+[docs]: https://libtmux.git-pull.com
+[api]: https://libtmux.git-pull.com/api.html
+[architecture]: https://libtmux.git-pull.com/about.html
+[history]: https://libtmux.git-pull.com/history.html
+[migration]: https://libtmux.git-pull.com/migration.html
+[issues]: https://github.com/tmux-python/libtmux/issues
+[coverage]: https://codecov.io/gh/tmux-python/libtmux
+[releases]: https://pypi.org/project/libtmux/
+[license]: https://github.com/tmux-python/libtmux/blob/master/LICENSE
+[support]: https://tony.sh/support.html
+[tao]: https://leanpub.com/the-tao-of-tmux
+[tmuxp]: https://tmuxp.git-pull.com
+[tmux]: https://github.com/tmux/tmux

From 122ecdfdaed235481d24d0941996a642f60a67d1 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 14:46:23 -0600
Subject: [PATCH 129/136] docs(README): add topic links and pytest fixture
 example

why: Following libvcs pattern, each code example should link to
deeper documentation for users who want to learn more.

what:
- Add "Learn more" links to quickstart sections (workspace setup,
  pane interaction, traversal, pytest plugin)
- Add inline links in features list (traverse, context managers, pytest)
- Add pytest fixture code example showing session fixture usage
- Reorganize project links into Topics / Reference / Project groups
- Link all 6 topic pages: traversal, pane_interaction, workspace_setup,
  automation_patterns, context_managers, options_and_hooks
---
 README.md | 66 +++++++++++++++++++++++++++++++++++++++++--------------
 1 file changed, 49 insertions(+), 17 deletions(-)

diff --git a/README.md b/README.md
index 3b2956ef5..c945f7537 100644
--- a/README.md
+++ b/README.md
@@ -22,11 +22,11 @@ libtmux is a typed Python API over [tmux], the terminal multiplexer. Stop shelli
 ### ✨ Features
 
 - Typed, object-oriented control of tmux state
-- Query and traverse live sessions, windows, and panes
+- Query and [traverse](https://libtmux.git-pull.com/topics/traversal.html) live sessions, windows, and panes
 - Raw escape hatch via `.cmd(...)` on any object
 - Works with multiple tmux sockets and servers
-- Context managers for automatic cleanup
-- pytest plugin for isolated tmux fixtures
+- [Context managers](https://libtmux.git-pull.com/topics/context_managers.html) for automatic cleanup
+- [pytest plugin](https://libtmux.git-pull.com/pytest-plugin/index.html) for isolated tmux fixtures
 - Proven in production via tmuxp and other tooling
 
 ## Requirements & support
@@ -155,6 +155,8 @@ Session($... ...)
 
 ### Control sessions and windows
 
+[**Learn more about Workspace Setup**](https://libtmux.git-pull.com/topics/workspace_setup.html)
+
 ```python
 >>> session.rename_session('my-session')
 Session($... my-session)
@@ -178,6 +180,8 @@ Window(@... ...:bg-work, Session($... ...))
 
 ### Split windows and send keys
 
+[**Learn more about Pane Interaction**](https://libtmux.git-pull.com/topics/pane_interaction.html)
+
 ```python
 >>> pane = window.split(attach=False)
 >>> pane
@@ -205,6 +209,8 @@ Pane(%... ...)
 
 ### Traverse the hierarchy
 
+[**Learn more about Traversal**](https://libtmux.git-pull.com/topics/traversal.html)
+
 Navigate from pane up to window to session:
 
 ```python
@@ -243,12 +249,25 @@ pane.send_keys("echo 'hello from libtmux'", enter=True)
 
 ## Testing & fixtures
 
-- [pytest plugin][pytest-plugin] provides fresh tmux server/session/window/pane fixtures
+[**Learn more about the pytest plugin**](https://libtmux.git-pull.com/pytest-plugin/index.html)
+
+Writing a tool that interacts with tmux? Use our fixtures to keep your tests clean and isolated.
+
+```python
+def test_my_tmux_tool(session):
+    # session is a real tmux session in an isolated server
+    window = session.new_window(window_name="test")
+    pane = window.active_pane
+    pane.send_keys("echo 'hello from test'", enter=True)
+
+    assert window.window_name == "test"
+    # Fixtures handle cleanup automatically
+```
+
+- Fresh tmux server/session/window/pane fixtures per test
 - Temporary HOME and tmux config fixtures keep indices stable
 - `TestServer` helper spins up multiple isolated tmux servers
 
-[pytest-plugin]: https://libtmux.git-pull.com/pytest-plugin/index.html
-
 ## When you might not need libtmux
 
 - Layouts are static and live entirely in tmux config files
@@ -257,17 +276,30 @@ pane.send_keys("echo 'hello from libtmux'", enter=True)
 
 ## Project links
 
-- Docs: [docs]
-- API reference: [api]
-- Architecture: [architecture]
-- Changelog: [history]
-- Migration notes: [migration]
-- Issues: [issues]
-- Test coverage: [coverage]
-- Releases: [releases]
-- License: [license]
-- Support: [support]
-- **[The Tao of tmux][tao]** — deep-dive book on tmux fundamentals
+**Topics:**
+[Traversal](https://libtmux.git-pull.com/topics/traversal.html) ·
+[Pane Interaction](https://libtmux.git-pull.com/topics/pane_interaction.html) ·
+[Workspace Setup](https://libtmux.git-pull.com/topics/workspace_setup.html) ·
+[Automation Patterns](https://libtmux.git-pull.com/topics/automation_patterns.html) ·
+[Context Managers](https://libtmux.git-pull.com/topics/context_managers.html) ·
+[Options & Hooks](https://libtmux.git-pull.com/topics/options_and_hooks.html)
+
+**Reference:**
+[Docs][docs] ·
+[API][api] ·
+[pytest plugin](https://libtmux.git-pull.com/pytest-plugin/index.html) ·
+[Architecture][architecture] ·
+[Changelog][history] ·
+[Migration][migration]
+
+**Project:**
+[Issues][issues] ·
+[Coverage][coverage] ·
+[Releases][releases] ·
+[License][license] ·
+[Support][support]
+
+**[The Tao of tmux][tao]** — deep-dive book on tmux fundamentals
 
 ## Contributing & support
 

From afe87198cd3eb3565180e3fe27b81fbaadc92e96 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 15:03:32 -0600
Subject: [PATCH 130/136] docs(README): add filtering topic link

why: New filtering topic should be discoverable from README.

what:
- Add "Learn more about Filtering" link in List and filter sessions section
- Add Filtering to Topics list in Project links
---
 README.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/README.md b/README.md
index c945f7537..3ccfa47ff 100644
--- a/README.md
+++ b/README.md
@@ -134,6 +134,8 @@ Create a new session:
 
 ### List and filter sessions
 
+[**Learn more about Filtering**](https://libtmux.git-pull.com/topics/filtering.html)
+
 ```python
 >>> server.sessions
 [Session($... ...), ...]
@@ -278,6 +280,7 @@ def test_my_tmux_tool(session):
 
 **Topics:**
 [Traversal](https://libtmux.git-pull.com/topics/traversal.html) ·
+[Filtering](https://libtmux.git-pull.com/topics/filtering.html) ·
 [Pane Interaction](https://libtmux.git-pull.com/topics/pane_interaction.html) ·
 [Workspace Setup](https://libtmux.git-pull.com/topics/workspace_setup.html) ·
 [Automation Patterns](https://libtmux.git-pull.com/topics/automation_patterns.html) ·

From ee64727f2313409a4f372ff90ef6aa1b796e64d4 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 15:04:43 -0600
Subject: [PATCH 131/136] docs(README): link core concepts to API docs

why: Users should be able to jump directly to API reference from
the core concepts table.

what:
- Link Server/Session/Window/Pane to their respective API pages
- Add note about Options and Hooks abstractions with links
---
 README.md | 10 ++++++----
 1 file changed, 6 insertions(+), 4 deletions(-)

diff --git a/README.md b/README.md
index 3ccfa47ff..560e92f51 100644
--- a/README.md
+++ b/README.md
@@ -226,10 +226,12 @@ Session($... ...)
 
 | libtmux object | tmux concept                | Notes                          |
 |----------------|-----------------------------|--------------------------------|
-| `Server`       | tmux server / socket        | Entry point; owns sessions     |
-| `Session`      | tmux session (`$0`, `$1`,...) | Owns windows                   |
-| `Window`       | tmux window (`@1`, `@2`,...)  | Owns panes                     |
-| `Pane`         | tmux pane (`%1`, `%2`,...)    | Where commands run             |
+| [`Server`](https://libtmux.git-pull.com/api/servers.html) | tmux server / socket | Entry point; owns sessions |
+| [`Session`](https://libtmux.git-pull.com/api/sessions.html) | tmux session (`$0`, `$1`,...) | Owns windows |
+| [`Window`](https://libtmux.git-pull.com/api/windows.html) | tmux window (`@1`, `@2`,...) | Owns panes |
+| [`Pane`](https://libtmux.git-pull.com/api/panes.html) | tmux pane (`%1`, `%2`,...) | Where commands run |
+
+Also available: [`Options`](https://libtmux.git-pull.com/api/options.html) and [`Hooks`](https://libtmux.git-pull.com/api/hooks.html) abstractions for tmux configuration.
 
 Collections are live and queryable:
 

From 3c28852497392f321df85f3b60717e7f12c7eb3b Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 15:05:59 -0600
Subject: [PATCH 132/136] docs(index): skip README header div, add libtmux
 title

why: The centered logo/badges div from README shouldn't bleed into
the sphinx docs - use :start-after: to skip it.

what:
- Add "# libtmux" as page title
- Use :start-after: </div> to skip the centered header section
---
 docs/index.md | 4 +++-
 1 file changed, 3 insertions(+), 1 deletion(-)

diff --git a/docs/index.md b/docs/index.md
index 76c4796b6..812510f8d 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -4,8 +4,10 @@ hide-toc: true
 
 (index)=
 
-```{include} ../README.md
+# libtmux
 
+```{include} ../README.md
+:start-after: </div>
 ```
 
 ## Table of Contents

From bdb7a7c39456642d05af7973beecf213abc5dc41 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 15:07:12 -0600
Subject: [PATCH 133/136] docs(README): remove HR after header div

why: The horizontal rule appears in sphinx docs when using
:start-after: </div> - not needed since header is visually distinct.
---
 README.md | 2 --
 1 file changed, 2 deletions(-)

diff --git a/README.md b/README.md
index 560e92f51..8a8e3bbe7 100644
--- a/README.md
+++ b/README.md
@@ -13,8 +13,6 @@
   </p>
 </div>
 
----
-
 ## 🐍 What is libtmux?
 
 libtmux is a typed Python API over [tmux], the terminal multiplexer. Stop shelling out and parsing `tmux ls`. Instead, interact with real Python objects: `Server`, `Session`, `Window`, and `Pane`. The same API powers [tmuxp], so it stays battle-tested in real-world workflows.

From 0c54bd8fbb43d10e23d8f4115109fb94c2b247f3 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 15:10:53 -0600
Subject: [PATCH 134/136] docs(index): fix toctree formatting, remove hide-toc

why: The hide-toc frontmatter was suppressing the sidebar ToC,
and the toctree directive was malformed (stray :hidden: outside block).

what:
- Remove hide-toc: true frontmatter
- Remove stray "## Table of Contents" and ":hidden:" text
- Add :hidden: to first toctree directive (matches libvcs pattern)
---
 docs/index.md | 9 +--------
 1 file changed, 1 insertion(+), 8 deletions(-)

diff --git a/docs/index.md b/docs/index.md
index 812510f8d..341532ee9 100644
--- a/docs/index.md
+++ b/docs/index.md
@@ -1,7 +1,3 @@
----
-hide-toc: true
----
-
 (index)=
 
 # libtmux
@@ -10,12 +6,9 @@ hide-toc: true
 :start-after: </div>
 ```
 
-## Table of Contents
-
-:hidden:
-
 ```{toctree}
 :maxdepth: 2
+:hidden:
 
 quickstart
 about

From 48022fd804db53a3232fb464dd09a73fa2edd501 Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 15:32:02 -0600
Subject: [PATCH 135/136] Tag v0.50.0a0

---
 pyproject.toml           | 2 +-
 src/libtmux/__about__.py | 2 +-
 uv.lock                  | 2 +-
 3 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/pyproject.toml b/pyproject.toml
index 3f60b27ee..9b7bf593c 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "libtmux"
-version = "0.49.0"
+version = "0.50.0a0"
 description = "Typed library that provides an ORM wrapper for tmux, a terminal multiplexer."
 requires-python = ">=3.10,<4.0"
 authors = [
diff --git a/src/libtmux/__about__.py b/src/libtmux/__about__.py
index 6175e07c8..55bc20ebf 100644
--- a/src/libtmux/__about__.py
+++ b/src/libtmux/__about__.py
@@ -4,7 +4,7 @@
 
 __title__ = "libtmux"
 __package_name__ = "libtmux"
-__version__ = "0.49.0"
+__version__ = "0.50.0a0"
 __description__ = "Typed scripting library / ORM / API wrapper for tmux"
 __email__ = "tony@git-pull.com"
 __author__ = "Tony Narlock"
diff --git a/uv.lock b/uv.lock
index 9655a2094..01b4eea69 100644
--- a/uv.lock
+++ b/uv.lock
@@ -482,7 +482,7 @@ wheels = [
 
 [[package]]
 name = "libtmux"
-version = "0.49.0"
+version = "0.50.0a0"
 source = { editable = "." }
 
 [package.dev-dependencies]

From 84175d01845bb46a9ce837339432114b1f39521c Mon Sep 17 00:00:00 2001
From: Tony Narlock <tony@git-pull.com>
Date: Sun, 30 Nov 2025 15:35:53 -0600
Subject: [PATCH 136/136] Tag v0.50.0

---
 CHANGES                  | 4 +++-
 pyproject.toml           | 2 +-
 src/libtmux/__about__.py | 2 +-
 uv.lock                  | 4 ++--
 4 files changed, 7 insertions(+), 5 deletions(-)

diff --git a/CHANGES b/CHANGES
index 792466009..56139c68a 100644
--- a/CHANGES
+++ b/CHANGES
@@ -28,12 +28,14 @@ $ uv add libtmux --prerelease allow
 $ uvx --from 'libtmux' --prerelease allow python
 ```
 
-## libtmux 0.50.x (Yet to be released)
+## libtmux 0.51.x (Yet to be released)
 
 <!-- To maintainers and contributors: Please add notes for the forthcoming version below -->
 
 _Future release notes will be placed here_
 
+## libtmux 0.50.0 (2025-11-30)
+
 ### Overview
 
 libtmux 0.50 brings a major enhancement to option and hook management. The new
diff --git a/pyproject.toml b/pyproject.toml
index 9b7bf593c..2462b9592 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -1,6 +1,6 @@
 [project]
 name = "libtmux"
-version = "0.50.0a0"
+version = "0.50.0"
 description = "Typed library that provides an ORM wrapper for tmux, a terminal multiplexer."
 requires-python = ">=3.10,<4.0"
 authors = [
diff --git a/src/libtmux/__about__.py b/src/libtmux/__about__.py
index 55bc20ebf..ec485ab9f 100644
--- a/src/libtmux/__about__.py
+++ b/src/libtmux/__about__.py
@@ -4,7 +4,7 @@
 
 __title__ = "libtmux"
 __package_name__ = "libtmux"
-__version__ = "0.50.0a0"
+__version__ = "0.50.0"
 __description__ = "Typed scripting library / ORM / API wrapper for tmux"
 __email__ = "tony@git-pull.com"
 __author__ = "Tony Narlock"
diff --git a/uv.lock b/uv.lock
index 01b4eea69..b585c21cc 100644
--- a/uv.lock
+++ b/uv.lock
@@ -313,7 +313,7 @@ name = "exceptiongroup"
 version = "1.3.1"
 source = { registry = "https://pypi.org/simple" }
 dependencies = [
-    { name = "typing-extensions", marker = "python_full_version < '3.13'" },
+    { name = "typing-extensions", marker = "python_full_version < '3.11'" },
 ]
 sdist = { url = "https://files.pythonhosted.org/packages/50/79/66800aadf48771f6b62f7eb014e352e5d06856655206165d775e675a02c9/exceptiongroup-1.3.1.tar.gz", hash = "sha256:8b412432c6055b0b7d14c310000ae93352ed6754f70fa8f7c34141f91c4e3219", size = 30371, upload-time = "2025-11-21T23:01:54.787Z" }
 wheels = [
@@ -482,7 +482,7 @@ wheels = [
 
 [[package]]
 name = "libtmux"
-version = "0.50.0a0"
+version = "0.50.0"
 source = { editable = "." }
 
 [package.dev-dependencies]