mcp(feat[instructions]): make the card visibility-aware via run_server

Phase 4 of the BASE_INSTRUCTIONS slim-down. The card names specific
tools by hint phrase (``snapshot_pane over capture_pane + get_pane_info``,
``wait_for_text over capture_pane in a retry loop``,
``search_panes over list_panes...``); under
``LIBTMUX_SAFETY=readonly`` some of those tools are hidden by
``mcp.enable(tags=..., only=True)``, so naming them in the card was
misleading.

Composition
-----------
* New ``_HANDLE_HINTS: tuple[tuple[str, str], ...]`` keyed by tool name.
* New ``_format_handles_section(visible_tool_names)`` renders the
  three-bullet handles list, filtering the Tools-handle hints by
  visibility. ``visible_tool_names=None`` keeps every hint
  (backward-compat for tests that build instructions without invoking
  ``mcp.enable``, and for the module-import-time placeholder).
* ``_INSTR_HANDLES`` is now ``_format_handles_section(None)`` — the
  unfiltered baseline used by ``_BASE_INSTRUCTIONS``.

Wiring
------
* ``_build_instructions`` gains a ``visible_tool_names: set[str] | None``
  parameter. When provided it rebuilds the base from ``_INSTR_CARD`` +
  filtered handles; otherwise it uses ``_BASE_INSTRUCTIONS`` directly.
  Env-driven ``is_caller`` block is unchanged.
* ``run_server`` now collects visible tool names via
  ``asyncio.run(mcp.list_tools())`` after ``mcp.enable(tags=..., only=True)``
  has applied the safety-tier filter, then overwrites ``mcp.instructions``
  with the visibility-filtered card. The module-import-time
  ``instructions=`` set on the FastMCP constructor is now an explicitly
  documented placeholder.

Tests
-----
* ``test_card_omits_invisible_tools`` (parametrized) — drops one tool
  from the visible set and asserts its hint phrase disappears, with a
  paired sanity check that the phrase IS present when the tool is
  visible.
* ``test_build_instructions_default_visible_tool_names_emits_full_card``
  — pins the backward-compat behavior so a future contributor doesn't
  silently break the placeholder by changing the default.

End-to-end smoke: simulating ``LIBTMUX_SAFETY=readonly`` (wait_for_text
hidden), the card drops the wait_for_text hint while keeping
snapshot_pane and search_panes. Default placeholder still emits all
three at 215 total words.

Author: tony

src/libtmux_mcp/server.py

@@ -69,22 +69,69 @@
     "and is the documented socket_name exception."
 )
 
-_INSTR_HANDLES = (
-    "Three handles cover everything the agent needs:\n"
-    "- Tools — call list_tools; per-tool descriptions tell you which to "
-    "prefer (e.g. snapshot_pane over capture_pane + get_pane_info, "
-    "wait_for_text over capture_pane in a retry loop, search_panes over "
-    'list_panes when the user says "panes that contain X").\n'
-    "- Resources (tmux://) — browseable hierarchy plus reference cards "
-    "(format strings).\n"
-    "- Prompts — packaged workflows: run_and_wait, diagnose_failing_pane, "
-    "build_dev_workspace, interrupt_gracefully."
+#: Tool-prefer hints in the Tools handle, keyed by the tool that
+#: motivates them. ``_format_handles_section`` filters these by
+#: ``visible_tool_names`` so the card never names a tool the agent
+#: cannot call (e.g. ``send_keys``-only hints under
+#: ``LIBTMUX_SAFETY=readonly``).
+_HANDLE_HINTS: tuple[tuple[str, str], ...] = (
+    ("snapshot_pane", "snapshot_pane over capture_pane + get_pane_info"),
+    ("wait_for_text", "wait_for_text over capture_pane in a retry loop"),
+    (
+        "search_panes",
+        'search_panes over list_panes when the user says "panes that contain X"',
+    ),
 )
 
+
+def _format_handles_section(visible_tool_names: set[str] | None) -> str:
+    """Render the three-handles bullet list, optionally visibility-filtered.
+
+    When ``visible_tool_names`` is ``None`` every hint is included
+    (backward-compat for tests that build instructions without first
+    invoking ``mcp.enable``). Otherwise hints whose tool is not in the
+    visible set are dropped — naming a tool the agent cannot call would
+    be misleading.
+    """
+    if visible_tool_names is None:
+        hints = [hint for _, hint in _HANDLE_HINTS]
+    else:
+        hints = [hint for tool, hint in _HANDLE_HINTS if tool in visible_tool_names]
+
+    tools_line = (
+        "- Tools — call list_tools; per-tool descriptions tell you which to prefer"
+    )
+    if hints:
+        tools_line += " (e.g. " + ", ".join(hints) + ")."
+    else:
+        tools_line += "."
+
+    return "\n".join(
+        (
+            "Three handles cover everything the agent needs:",
+            tools_line,
+            (
+                "- Resources (tmux://) — browseable hierarchy plus reference "
+                "cards (format strings)."
+            ),
+            (
+                "- Prompts — packaged workflows: run_and_wait, "
+                "diagnose_failing_pane, build_dev_workspace, "
+                "interrupt_gracefully."
+            ),
+        )
+    )
+
+
+_INSTR_HANDLES = _format_handles_section(visible_tool_names=None)
+
 _BASE_INSTRUCTIONS = "\n\n".join((_INSTR_CARD, _INSTR_HANDLES))
 
 
-def _build_instructions(safety_level: str = TAG_MUTATING) -> str:
+def _build_instructions(
+    safety_level: str = TAG_MUTATING,
+    visible_tool_names: set[str] | None = None,
+) -> str:
     """Build server instructions with agent context and safety level.
 
     When the MCP server process runs inside a tmux pane, ``TMUX_PANE`` and
@@ -95,13 +142,25 @@ def _build_instructions(safety_level: str = TAG_MUTATING) -> str:
     ----------
     safety_level : str
         Active safety tier (readonly, mutating, or destructive).
+    visible_tool_names : set of str, optional
+        When provided, the handles section drops hints for tools not in
+        the set so the card never names a tool the agent cannot call.
+        ``run_server`` populates this from ``mcp.list_tools()`` after
+        ``mcp.enable(tags=..., only=True)`` has applied the safety-tier
+        filter. Defaults to ``None`` (backward-compat: all hints emitted),
+        which is what the module-import-time placeholder uses before
+        ``run_server`` runs.
 
     Returns
     -------
     str
         Server instructions string, optionally with agent tmux context.
     """
-    parts: list[str] = [_BASE_INSTRUCTIONS]
+    if visible_tool_names is None:
+        base = _BASE_INSTRUCTIONS
+    else:
+        base = "\n\n".join((_INSTR_CARD, _format_handles_section(visible_tool_names)))
+    parts: list[str] = [base]
 
     # Safety tier context
     parts.append(
@@ -273,6 +332,8 @@ def _register_all() -> None:
 
 def run_server() -> None:
     """Run the MCP server."""
+    import asyncio
+
     _register_all()
 
     # Use FastMCP's native visibility system as primary gate,
@@ -284,4 +345,17 @@ def run_server() -> None:
         allowed_tags.add(TAG_DESTRUCTIVE)
     mcp.enable(tags=allowed_tags, only=True)
 
+    # Rebuild instructions now that ``mcp.enable`` has hidden tools
+    # outside the active safety tier. The card mentions specific tools
+    # by name (snapshot_pane, wait_for_text, search_panes); naming a
+    # tool the agent cannot call would be misleading. The
+    # module-import-time ``instructions=`` set on the FastMCP
+    # constructor was a placeholder built without a visibility filter —
+    # this overwrite is the authoritative version.
+    visible_tool_names = {tool.name for tool in asyncio.run(mcp.list_tools())}
+    mcp.instructions = _build_instructions(
+        safety_level=_safety_level,
+        visible_tool_names=visible_tool_names,
+    )
+
     mcp.run()

tests/test_server.py

@@ -218,6 +218,67 @@ def test_card_length_budget() -> None:
     )
 
 
+# Phrases the handles section emits when the corresponding tool is in
+# ``visible_tool_names``. Phase 4: ``_build_instructions`` filters the
+# Tools handle by visibility so the card never names a tool the agent
+# cannot call. Keep this aligned with ``_HANDLE_HINTS`` in server.py.
+_VISIBILITY_FILTER_CASES: list[tuple[str, str]] = [
+    ("snapshot_pane", "snapshot_pane over capture_pane"),
+    ("wait_for_text", "wait_for_text over capture_pane"),
+    ("search_panes", "search_panes over list_panes"),
+]
+
+
+@pytest.mark.parametrize(
+    ("omitted_tool", "phrase_that_should_drop"),
+    _VISIBILITY_FILTER_CASES,
+    ids=[t for t, _ in _VISIBILITY_FILTER_CASES],
+)
+def test_card_omits_invisible_tools(
+    omitted_tool: str,
+    phrase_that_should_drop: str,
+) -> None:
+    """The handles section drops hints for tools outside ``visible_tool_names``.
+
+    Each row asserts that removing one tool from the visible set drops
+    its tool-prefer hint from the card. Sanity check: the same phrase IS
+    present when the tool IS visible — guards against the test passing
+    accidentally because the phrase was never there.
+    """
+    full_visibility = {tool for tool, _ in _VISIBILITY_FILTER_CASES}
+    visible = full_visibility - {omitted_tool}
+
+    filtered = _build_instructions(TAG_MUTATING, visible_tool_names=visible)
+    assert phrase_that_should_drop not in filtered, (
+        f"phrase {phrase_that_should_drop!r} stayed when {omitted_tool} "
+        f"was filtered out — visibility filter is broken"
+    )
+
+    full = _build_instructions(TAG_MUTATING, visible_tool_names=full_visibility)
+    assert phrase_that_should_drop in full, (
+        f"phrase {phrase_that_should_drop!r} missing even when "
+        f"{omitted_tool} is visible — sanity check failed"
+    )
+
+
+def test_build_instructions_default_visible_tool_names_emits_full_card() -> None:
+    """``visible_tool_names=None`` is the backward-compat default.
+
+    The module-import-time ``instructions=`` placeholder builds without
+    invoking ``mcp.enable``, so it has no visibility set to consult. In
+    that case ``_build_instructions`` must emit every handle hint as if
+    the agent could call any tool — the alternative would be silently
+    dropping hints during the (brief) window before ``run_server``
+    overwrites the placeholder.
+    """
+    full = _build_instructions(TAG_MUTATING)
+    for _, phrase in _VISIBILITY_FILTER_CASES:
+        assert phrase in full, (
+            f"phrase {phrase!r} missing from default _build_instructions; "
+            f"visible_tool_names=None should emit the full hint set"
+        )
+
+
 def test_registered_tools_accept_socket_name() -> None:
     """All registered tools (except list_servers) accept ``socket_name``.