engine(refactor): Add ServerContext and Engine.bind()

Add ServerContext dataclass to capture server connection details
(socket_name, socket_path, config_file) in an immutable container.

Add Engine.bind() method called by Server.__init__ to provide
connection details to engines. This enables engines to execute
commands without requiring server_args on every hook call.

Foundation for standardizing hook signatures in next step.

Author: tony

src/libtmux/_internal/engines/base.py

@@ -13,6 +13,30 @@
     from libtmux.session import Session
 
 
+@dataclasses.dataclass(frozen=True)
+class ServerContext:
+    """Immutable server connection context.
+
+    Passed to :meth:`Engine.bind` so engines can execute commands
+    without requiring `server_args` on every hook call.
+    """
+
+    socket_name: str | None = None
+    socket_path: str | None = None
+    config_file: str | None = None
+
+    def to_args(self) -> tuple[str, ...]:
+        """Convert context to tmux server argument tuple."""
+        args: list[str] = []
+        if self.socket_name:
+            args.extend(["-L", self.socket_name])
+        if self.socket_path:
+            args.extend(["-S", str(self.socket_path)])
+        if self.config_file:
+            args.extend(["-f", str(self.config_file)])
+        return tuple(args)
+
+
 class ExitStatus(enum.Enum):
     """Exit status returned by tmux control mode commands."""
 
@@ -123,6 +147,22 @@ class Engine(ABC):
     a strong reason to override both.
     """
 
+    _server_context: ServerContext | None = None
+
+    def bind(self, context: ServerContext) -> None:
+        """Bind engine to server context.
+
+        Called by :class:`Server.__init__` to provide connection details.
+        Engines can use this to run commands without requiring ``server_args``
+        on every hook call.
+
+        Parameters
+        ----------
+        context : ServerContext
+            Immutable server connection context.
+        """
+        self._server_context = context
+
     def run(
         self,
         cmd: str,

src/libtmux/server.py

@@ -16,6 +16,7 @@
 import warnings
 
 from libtmux import exc, formats
+from libtmux._internal.engines.base import ServerContext
 from libtmux._internal.engines.subprocess_engine import SubprocessEngine
 from libtmux._internal.query_list import QueryList
 from libtmux.common import tmux_cmd
@@ -173,6 +174,15 @@ def __init__(
         if colors:
             self.colors = colors
 
+        # Bind engine to server context for hook calls
+        self.engine.bind(
+            ServerContext(
+                socket_name=self.socket_name,
+                socket_path=str(self.socket_path) if self.socket_path else None,
+                config_file=self.config_file,
+            ),
+        )
+
         if on_init is not None:
             on_init(self)