feat(tools): Add 11 new MCP tools for agent workflows (#11)

Expands the MCP surface with tools that unblock common agent
workflows the initial tool set couldn't serve cleanly: rich pane
introspection, waiting on unspecified output, pane and window
navigation, layout rearrangement, scrollback and copy-mode
control, bracketed multi-line paste, generic tmux format-string
queries, and pane output logging. All tools ship with Pydantic
output models, user-facing documentation, and tests that run
against every tmux version in the CI matrix (3.2a through
master).

**New pane tools:**
- `snapshot_pane` — one-call capture returning content plus
  cursor position, mode, scroll state, and pane metadata
- `wait_for_content_change` — block until any on-screen change;
  complements `wait_for_text` when expected output is unknown
- `select_pane` — focus by pane_id or by direction
  (up/down/left/right/last/next/previous)
- `swap_pane` — exchange two panes' positions within a window
- `pipe_pane` — start or stop streaming pane output to a file
- `display_message` — query arbitrary tmux format strings
- `enter_copy_mode` / `exit_copy_mode` — control scrollback
  access, with optional immediate scroll-up on entry
- `paste_text` — deliver multi-line text via isolated tmux
  buffers

**New session tool:**
- `select_window` — focus by id, index, or direction
  (next / previous / last)

**New window tool:**
- `move_window` — reorder within a session or move across
  sessions

**New models:** `PaneSnapshot` and `ContentChangeResult`, both
with full field-level typing for the richer return shapes.

**Correctness guarantees validated by test:**
- Directional navigation in `select_pane` and `select_window`
  routes through absolute pane_ids and session-scoped tmux
  subcommands, so targeting a non-active window or non-current
  session cannot misroute focus to whatever the attached client
  happens to have focused.
- `move_window` refreshes the window after the move, so
  cross-session returns never carry stale session metadata
  (libtmux's in-memory update skips refresh on the
  destination-index-plus-session branch).
- `snapshot_pane` uses the printable Unicode `␞` delimiter —
  the same choice as libtmux's `FORMAT_SEPARATOR` — so parsing
  is immune to tmux's version-dependent control-character
  escaping in `display-message` output.
- `pipe_pane` shell-quotes output paths and rejects empty
  strings at the tool boundary instead of letting tmux emit a
  broken pipe silently.
- `paste_text` uses per-call UUID-named tmux buffers, surfaces
  load-buffer stderr as `ToolError`, and cleans up both the
  named buffer and the temp file on every exit path.
- MCP annotation tiers corrected for non-idempotent operations:
  `swap_pane`, `enter_copy_mode`, and `pipe_pane` advertise
  `idempotentHint=false`.

**Docs:** per-module pages in `docs/tools/*.md` with usage
guidance, JSON examples, and parameter tables for every tool;
the tools index carries an expanded "Which tool do I want?"
decision guide; the README Tools table lists the full new
roster; the docs landing page highlights the headline
capabilities.

Author: tony

CHANGES

@@ -6,6 +6,13 @@
 _Notes on upcoming releases will be added here_
 <!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
 
+### What's new
+
+- New pane tools: `snapshot_pane`, `wait_for_content_change`, `select_pane`, `swap_pane`, `pipe_pane`, `display_message`, `enter_copy_mode`, `exit_copy_mode`, and `paste_text` (#11)
+- New session tool: `select_window` — navigate by ID, index, or direction (#11)
+- New window tool: `move_window` — reorder within a session or move across sessions (#11)
+- New models: `PaneSnapshot` and `ContentChangeResult` (#11)
+
 ### Documentation
 
 - Visual improvements to API docs from [gp-sphinx](https://gp-sphinx.git-pull.com)-based Sphinx packages (#10)

README.md

@@ -16,9 +16,9 @@ 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`, `kill_session` |
-| **Window** | `list_panes`, `split_window`, `rename_window`, `kill_window`, `select_layout`, `resize_window` |
-| **Pane** | `send_keys`, `capture_pane`, `resize_pane`, `kill_pane`, `set_pane_title`, `get_pane_info`, `clear_pane`, `search_panes`, `wait_for_text` |
+| **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` |
+| **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/index.md

@@ -53,13 +53,13 @@ Config blocks for Claude Desktop, Claude Code, Cursor, and others.
 
 Read tmux state without changing anything.
 
-{toolref}`list-sessions` · {toolref}`capture-pane` · {toolref}`get-pane-info` · {toolref}`search-panes` · {toolref}`wait-for-text`
+{toolref}`list-sessions` · {toolref}`capture-pane` · {toolref}`snapshot-pane` · {toolref}`get-pane-info` · {toolref}`search-panes` · {toolref}`wait-for-text` · {toolref}`wait-for-content-change` · {toolref}`display-message`
 
 ### Act (mutating)
 
 Create or modify tmux objects.
 
-{toolref}`create-session` · {toolref}`send-keys` · {toolref}`create-window` · {toolref}`split-window` · {toolref}`resize-pane` · {toolref}`set-option`
+{toolref}`create-session` · {toolref}`send-keys` · {toolref}`paste-text` · {toolref}`create-window` · {toolref}`split-window` · {toolref}`select-pane` · {toolref}`select-window` · {toolref}`move-window` · {toolref}`resize-pane` · {toolref}`pipe-pane` · {toolref}`set-option`
 
 ### Destroy (destructive)
 

docs/tools/index.md

@@ -8,18 +8,36 @@ All tools accept an optional `socket_name` parameter for multi-server support. I
 
 **Reading terminal content?**
 - Know which pane? → {tool}`capture-pane`
+- Need text + cursor + mode in one call? → {tool}`snapshot-pane`
 - Don't know which pane? → {tool}`search-panes`
-- Need to wait for output? → {tool}`wait-for-text`
+- Need to wait for specific output? → {tool}`wait-for-text`
+- Need to wait for *any* change? → {tool}`wait-for-content-change`
 - Only need metadata (PID, path, size)? → {tool}`get-pane-info`
+- Need an arbitrary tmux variable? → {tool}`display-message`
 
 **Running a command?**
 - {tool}`send-keys` — then {tool}`wait-for-text` + {tool}`capture-pane`
+- Pasting multi-line text? → {tool}`paste-text`
 
 **Creating workspace structure?**
 - New session → {tool}`create-session`
 - New window → {tool}`create-window`
 - New pane → {tool}`split-window`
 
+**Navigating?**
+- Switch pane → {tool}`select-pane` (by ID or direction)
+- Switch window → {tool}`select-window` (by ID, index, or direction)
+
+**Rearranging layout?**
+- Swap two panes → {tool}`swap-pane`
+- Move window → {tool}`move-window`
+- Change layout → {tool}`select-layout`
+
+**Scrollback / copy mode?**
+- Enter copy mode → {tool}`enter-copy-mode`
+- Exit copy mode → {tool}`exit-copy-mode`
+- Log output to file → {tool}`pipe-pane`
+
 **Changing settings?**
 - tmux options → {tool}`show-option` / {tool}`set-option`
 - Environment vars → {tool}`show-environment` / {tool}`set-environment`
@@ -91,6 +109,24 @@ Query a tmux option value.
 Show tmux environment variables.
 :::
 
+:::{grid-item-card} snapshot_pane
+:link: snapshot-pane
+:link-type: ref
+Rich capture: content + cursor + mode + scroll.
+:::
+
+:::{grid-item-card} wait_for_content_change
+:link: wait-for-content-change
+:link-type: ref
+Wait for any screen change.
+:::
+
+:::{grid-item-card} display_message
+:link: display-message
+:link-type: ref
+Query arbitrary tmux format strings.
+:::
+
 ::::
 
 ## Act
@@ -178,6 +214,54 @@ Set a tmux option.
 Set a tmux environment variable.
 :::
 
+:::{grid-item-card} select_pane
+:link: select-pane
+:link-type: ref
+Focus a pane by ID or direction.
+:::
+
+:::{grid-item-card} select_window
+:link: select-window
+:link-type: ref
+Focus a window by ID, index, or direction.
+:::
+
+:::{grid-item-card} swap_pane
+:link: swap-pane
+:link-type: ref
+Exchange positions of two panes.
+:::
+
+:::{grid-item-card} move_window
+:link: move-window
+:link-type: ref
+Move window to another index or session.
+:::
+
+:::{grid-item-card} pipe_pane
+:link: pipe-pane
+:link-type: ref
+Stream pane output to a file.
+:::
+
+:::{grid-item-card} enter_copy_mode
+:link: enter-copy-mode
+:link-type: ref
+Enter copy mode for scrollback.
+:::
+
+:::{grid-item-card} exit_copy_mode
+:link: exit-copy-mode
+:link-type: ref
+Exit copy mode.
+:::
+
+:::{grid-item-card} paste_text
+:link: paste-text
+:link-type: ref
+Paste multi-line text via tmux buffer.
+:::
+
 ::::
 
 ## Destroy