mcp(fix[pane_tools]): document capture_pane truncation marker for agents

When ``capture_pane`` truncates, the returned string is prefixed with a
literal ``[... truncated K lines ...]`` first line so the caller can
detect the cap. This is documented in the function docstring at
``pane_tools/io.py:174-178``, but FastMCP only surfaces the
``description=`` override registered at ``pane_tools/__init__.py:83-95``,
not the docstring — and the override only said "tail-preserving
truncation at max_lines, default 500". Agents reading the description
had no signal that the first line of a truncated response is a marker
rather than terminal content, and could mishandle the output.

Extends the override to name the marker and tell the agent it's a
literal prefix line to skip when parsing. Also surfaces the
``max_lines=None`` opt-out.

Test: adds a row to ``test_tool_description_includes`` asserting
``capture_pane``'s description contains ``"truncated"``. The contract
suite already pinned ``snapshot_pane`` / ``wait_for_text`` /
``search_panes`` cross-references; this extends the same drift
guard to the truncation behavior.

Author: tony

src/libtmux_mcp/tools/pane_tools/__init__.py

@@ -85,13 +85,17 @@ def register(mcp: FastMCP) -> None:
         annotations=ANNOTATIONS_RO,
         tags={TAG_READONLY},
         description=(
-            "Capture the visible contents of a tmux pane (tail-preserving "
-            "truncation at max_lines, default 500). For pane content + "
-            "cursor + mode + scroll state in one call, use snapshot_pane. "
-            "For 'send_keys then wait for output' flows, use wait_for_text "
-            "or wait_for_content_change instead of a capture_pane retry "
-            "loop — server-side blocking is dramatically cheaper in agent "
-            "turns. To find text across many panes, use search_panes."
+            "Capture the visible contents of a tmux pane. Output is "
+            "tail-preserving truncated at max_lines (default 500); when "
+            "truncation occurs, the first line of the returned string is a "
+            "literal '[... truncated K lines ...]' marker — skip it when "
+            "parsing terminal content. Pass max_lines=None to disable "
+            "truncation. For pane content + cursor + mode + scroll state in "
+            "one call, use snapshot_pane. For 'send_keys then wait for "
+            "output' flows, use wait_for_text or wait_for_content_change "
+            "instead of a capture_pane retry loop — server-side blocking "
+            "is dramatically cheaper in agent turns. To find text across "
+            "many panes, use search_panes."
         ),
     )(capture_pane)
     mcp.tool(

tests/test_server.py

@@ -402,6 +402,11 @@ def test_registered_tools_accept_socket_name() -> None:
         ("capture_pane", "snapshot_pane"),
         ("capture_pane", "wait_for_text"),
         ("capture_pane", "search_panes"),
+        # Truncation marker — agents need to know the first line of a
+        # truncated capture is a literal '[... truncated K lines ...]'
+        # header, not terminal content. Without this in the description,
+        # an agent might treat the marker as the most recent output.
+        ("capture_pane", "truncated"),
         ("show_hooks", "tmux config file"),
         ("load_buffer", "list_buffers"),
         ("load_buffer", "clipboard history"),