mcp(feat[window_tools]): add get_window_info for single-window metadata

why: get_pane_info and get_server_info exist, but the window and
session peers do not. Agents given a window_id and asked "what are
this window's dimensions?" have to call list_panes or list_windows
and filter — wasteful. Adding get_window_info closes one half of the
core-tmux-hierarchy symmetry (get_session_info follows next).

The symmetry argument is deliberately bounded to the four-level core
hierarchy (Server > Session > Window > Pane). This is NOT a license
to add get_buffer_info / get_hook_info / get_option_info — those
scopes are outside the hierarchy and the existing show_*/load_*
tools already cover their reads. An inline comment on the function
memorializes that boundary so future contributors don't re-relitigate
it.

what:
- Add get_window_info(window_id, window_index, session_name,
  session_id, socket_name) returning WindowInfo. Reuses
  _resolve_window (accepts window_id OR window_index+session) and
  _serialize_window — no new helpers.
- Register with ANNOTATIONS_RO + TAG_READONLY, placed next to
  list_panes in the Window tool group.
- Add test_get_window_info (resolves by window_id) and
  test_get_window_info_by_index (resolves by index+session) mirroring
  the minimal-assertion style used by test_list_panes.
- Add docs/tools/window/get-window-info.md modeled after
  get-pane-info.md; insert the new page into the Window tools index
  grid and toctree.
- Append get_window_info to the README tool catalog Window row.

Author: tony

README.md

@@ -17,7 +17,7 @@ Give your AI agent hands inside the terminal — create sessions, run commands,
 |--------|-------|
 | **Server** | `list_sessions`, `create_session`, `kill_server`, `get_server_info` |
 | **Session** | `list_windows`, `create_window`, `rename_session`, `select_window`, `kill_session` |
-| **Window** | `list_panes`, `split_window`, `rename_window`, `select_layout`, `resize_window`, `move_window`, `kill_window` |
+| **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` |
 | **Environment** | `show_environment`, `set_environment` |

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

@@ -0,0 +1,58 @@
+# Get window info
+
+```{fastmcp-tool} window_tools.get_window_info
+```
+
+**Use when** you need metadata for a single window (name, index, layout,
+dimensions, pane count) and you already know the `window_id` or
+`window_index`. Avoids the `list_windows` + filter dance.
+
+**Avoid when** you need every window in a session — call `list_panes` with
+`session_id` or iterate through the session's windows via the
+`tmux://sessions/{name}/windows` resource.
+
+**Side effects:** None. Readonly.
+
+**Example:**
+
+```json
+{
+  "tool": "get_window_info",
+  "arguments": {
+    "window_id": "@1"
+  }
+}
+```
+
+Response:
+
+```json
+{
+  "window_id": "@1",
+  "window_name": "editor",
+  "window_index": "1",
+  "session_id": "$0",
+  "session_name": "dev",
+  "pane_count": 2,
+  "window_layout": "7f9f,80x24,0,0[80x15,0,0,0,80x8,0,16,1]",
+  "window_active": "1",
+  "window_width": "80",
+  "window_height": "24"
+}
+```
+
+Resolve by `window_index` when only the index is known — requires
+`session_name` or `session_id` to disambiguate:
+
+```json
+{
+  "tool": "get_window_info",
+  "arguments": {
+    "window_index": "1",
+    "session_name": "dev"
+  }
+}
+```
+
+```{fastmcp-tool-input} window_tools.get_window_info
+```

docs/tools/window/index.md

@@ -9,6 +9,10 @@ Window-scoped tools — enumerate panes, split / rename / relayout / resize / mo
 Enumerate panes inside a window.
 :::
 
+:::{grid-item-card} {tooliconl}`get-window-info`
+Read metadata for one window.
+:::
+
 :::{grid-item-card} {tooliconl}`split-window`
 Split a window into a new pane.
 :::
@@ -40,6 +44,7 @@ Terminate a window. Destructive.
 :maxdepth: 1
 
 list-panes
+get-window-info
 split-window
 rename-window
 select-layout

src/libtmux_mcp/tools/window_tools.py

@@ -98,6 +98,56 @@ def list_panes(
     return _apply_filters(panes, filters, _serialize_pane)
 
 
+# get_window_info completes the core-tmux-hierarchy symmetry of get_*_info
+# tools: the four hierarchy levels (server, session, window, pane) now each
+# have a targeted single-object read. This is deliberately NOT a license to
+# add get_buffer_info / get_hook_info / get_option_info — those scopes are
+# not part of the hierarchy and the existing show_*/load_* tools already
+# cover their reads. See the brainstorm-and-refine audit §7.1.
+@handle_tool_errors
+def get_window_info(
+    window_id: str | None = None,
+    window_index: str | None = None,
+    session_name: str | None = None,
+    session_id: str | None = None,
+    socket_name: str | None = None,
+) -> WindowInfo:
+    """Return metadata for a single tmux window (ID, name, layout, dimensions).
+
+    Use this instead of list_windows + filter when you only need one
+    window's info. Resolves the window by window_id first; falls back
+    to window_index within a session if window_id is not given.
+
+    Parameters
+    ----------
+    window_id : str, optional
+        Window ID (e.g. '@1').
+    window_index : str, optional
+        Window index within the session. Requires session_name or
+        session_id to disambiguate.
+    session_name : str, optional
+        Session name for window_index lookup.
+    session_id : str, optional
+        Session ID for window_index lookup.
+    socket_name : str, optional
+        tmux socket name.
+
+    Returns
+    -------
+    WindowInfo
+        Serialized window metadata.
+    """
+    server = _get_server(socket_name=socket_name)
+    window = _resolve_window(
+        server,
+        window_id=window_id,
+        window_index=window_index,
+        session_name=session_name,
+        session_id=session_id,
+    )
+    return _serialize_window(window)
+
+
 @handle_tool_errors
 def split_window(
     pane_id: str | None = None,
@@ -425,6 +475,9 @@ def register(mcp: FastMCP) -> None:
     mcp.tool(title="List Panes", annotations=ANNOTATIONS_RO, tags={TAG_READONLY})(
         list_panes
     )
+    mcp.tool(title="Get Window Info", annotations=ANNOTATIONS_RO, tags={TAG_READONLY})(
+        get_window_info
+    )
     mcp.tool(title="Split Window", annotations=ANNOTATIONS_CREATE, tags={TAG_MUTATING})(
         split_window
     )

tests/test_window_tools.py

@@ -8,6 +8,7 @@
 from fastmcp.exceptions import ToolError
 
 from libtmux_mcp.tools.window_tools import (
+    get_window_info,
     kill_window,
     list_panes,
     move_window,
@@ -34,6 +35,31 @@ def test_list_panes(mcp_server: Server, mcp_session: Session) -> None:
     assert result[0].pane_id is not None
 
 
+def test_get_window_info(mcp_server: Server, mcp_session: Session) -> None:
+    """get_window_info returns a WindowInfo for a single window."""
+    window = mcp_session.active_window
+    result = get_window_info(
+        window_id=window.window_id,
+        socket_name=mcp_server.socket_name,
+    )
+    assert result.window_id == window.window_id
+    assert result.window_name is not None
+    assert result.pane_count >= 1
+    assert result.session_id == mcp_session.session_id
+
+
+def test_get_window_info_by_index(mcp_server: Server, mcp_session: Session) -> None:
+    """get_window_info resolves by window_index when session is named."""
+    window = mcp_session.active_window
+    assert window.window_index is not None
+    result = get_window_info(
+        window_index=window.window_index,
+        session_name=mcp_session.session_name,
+        socket_name=mcp_server.socket_name,
+    )
+    assert result.window_id == window.window_id
+
+
 def test_split_window(mcp_server: Server, mcp_session: Session) -> None:
     """split_window creates a new pane."""
     window = mcp_session.active_window