mcp(feat[session_tools]): add get_session_info for single-session metadata

why: completes the symmetry started by get_window_info. Agents given
a session_id and asked "how many windows does this session have?" no
longer need to call list_sessions and filter.

The bounded-to-core-hierarchy rule from get_window_info applies here
too — inline comment memorializes it.

what:
- Add get_session_info(session_id, session_name, socket_name)
  returning SessionInfo. Reuses _resolve_session and
  _serialize_session; no new helpers.
- Register with ANNOTATIONS_RO + TAG_READONLY, placed next to
  list_windows in the Session tool group.
- Add test_get_session_info (by id) and test_get_session_info_by_name
  mirroring the test_list_windows style.
- Add docs/tools/session/get-session-info.md modeled after the peer
  get-window-info page; insert the new page into the Session index
  grid and toctree.
- Append get_session_info to the README tool catalog Session row.

Author: tony

README.md

@@ -16,7 +16,7 @@ Give your AI agent hands inside the terminal — create sessions, run commands,
 | Module | Tools |
 |--------|-------|
 | **Server** | `list_sessions`, `create_session`, `kill_server`, `get_server_info` |
-| **Session** | `list_windows`, `create_window`, `rename_session`, `select_window`, `kill_session` |
+| **Session** | `list_windows`, `get_session_info`, `create_window`, `rename_session`, `select_window`, `kill_session` |
 | **Window** | `list_panes`, `get_window_info`, `split_window`, `rename_window`, `select_layout`, `resize_window`, `move_window`, `kill_window` |
 | **Pane** | `send_keys`, `paste_text`, `capture_pane`, `snapshot_pane`, `search_panes`, `get_pane_info`, `wait_for_text`, `wait_for_content_change`, `display_message`, `select_pane`, `swap_pane`, `resize_pane`, `set_pane_title`, `clear_pane`, `pipe_pane`, `enter_copy_mode`, `exit_copy_mode`, `kill_pane` |
 | **Options** | `show_option`, `set_option` |

docs/tools/session/get-session-info.md

@@ -0,0 +1,51 @@
+# Get session info
+
+```{fastmcp-tool} session_tools.get_session_info
+```
+
+**Use when** you need metadata for a single session (ID, name, window
+count, attachment status, activity timestamp) and you already know its
+`session_id` or `session_name`. Avoids the `list_sessions` + filter dance.
+
+**Avoid when** you need every session — call `list_sessions` or iterate
+via the `tmux://sessions` resource.
+
+**Side effects:** None. Readonly.
+
+**Example:**
+
+```json
+{
+  "tool": "get_session_info",
+  "arguments": {
+    "session_id": "$0"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "session_id": "$0",
+  "session_name": "dev",
+  "window_count": 3,
+  "session_attached": "1",
+  "session_created": "1713600000",
+  "active_pane_id": "%0"
+}
+```
+
+Resolve by name when only the session_name is known:
+
+```json
+{
+  "tool": "get_session_info",
+  "arguments": {
+    "session_name": "dev"
+  }
+}
+```
+
+```{fastmcp-tool-input} session_tools.get_session_info
+```

docs/tools/session/index.md

@@ -9,6 +9,10 @@ Session-scoped tools — enumerate windows, rename or kill a session, switch win
 Enumerate windows inside a session.
 :::
 
+:::{grid-item-card} {tooliconl}`get-session-info`
+Read metadata for one session.
+:::
+
 :::{grid-item-card} {tooliconl}`select-window`
 Switch to a window by id, index, or direction.
 :::
@@ -32,6 +36,7 @@ Terminate a session. Destructive.
 :maxdepth: 1
 
 list-windows
+get-session-info
 select-window
 create-window
 rename-session

src/libtmux_mcp/tools/session_tools.py

@@ -71,6 +71,40 @@ def list_windows(
     return _apply_filters(windows, filters, _serialize_window)
 
 
+# get_session_info completes the core-tmux-hierarchy symmetry alongside
+# get_window_info / get_pane_info / get_server_info. Bounded to the four
+# hierarchy levels — see the same note in window_tools.get_window_info.
+@handle_tool_errors
+def get_session_info(
+    session_id: str | None = None,
+    session_name: str | None = None,
+    socket_name: str | None = None,
+) -> SessionInfo:
+    """Return metadata for a single tmux session (ID, name, window count, activity).
+
+    Use this instead of list_sessions + filter when you only need one
+    session's info. Resolves by session_id first; falls back to
+    session_name.
+
+    Parameters
+    ----------
+    session_id : str, optional
+        Session ID (e.g. '$0').
+    session_name : str, optional
+        Session name.
+    socket_name : str, optional
+        tmux socket name.
+
+    Returns
+    -------
+    SessionInfo
+        Serialized session metadata.
+    """
+    server = _get_server(socket_name=socket_name)
+    session = _resolve_session(server, session_name=session_name, session_id=session_id)
+    return _serialize_session(session)
+
+
 @handle_tool_errors
 def create_window(
     session_name: str | None = None,
@@ -298,6 +332,9 @@ def register(mcp: FastMCP) -> None:
     mcp.tool(title="List Windows", annotations=ANNOTATIONS_RO, tags={TAG_READONLY})(
         list_windows
     )
+    mcp.tool(title="Get Session Info", annotations=ANNOTATIONS_RO, tags={TAG_READONLY})(
+        get_session_info
+    )
     mcp.tool(
         title="Create Window", annotations=ANNOTATIONS_CREATE, tags={TAG_MUTATING}
     )(create_window)

tests/test_session_tools.py

@@ -9,6 +9,7 @@
 
 from libtmux_mcp.tools.session_tools import (
     create_window,
+    get_session_info,
     kill_session,
     list_windows,
     rename_session,
@@ -40,6 +41,27 @@ def test_list_windows_by_id(mcp_server: Server, mcp_session: Session) -> None:
     assert len(result) >= 1
 
 
+def test_get_session_info(mcp_server: Server, mcp_session: Session) -> None:
+    """get_session_info returns a SessionInfo for a single session."""
+    result = get_session_info(
+        session_id=mcp_session.session_id,
+        socket_name=mcp_server.socket_name,
+    )
+    assert result.session_id == mcp_session.session_id
+    assert result.session_name == mcp_session.session_name
+    assert result.window_count >= 1
+
+
+def test_get_session_info_by_name(mcp_server: Server, mcp_session: Session) -> None:
+    """get_session_info resolves by session_name when no ID is given."""
+    assert mcp_session.session_name is not None
+    result = get_session_info(
+        session_name=mcp_session.session_name,
+        socket_name=mcp_server.socket_name,
+    )
+    assert result.session_id == mcp_session.session_id
+
+
 def test_create_window(mcp_server: Server, mcp_session: Session) -> None:
     """create_window creates a new window in a session."""
     result = create_window(