MCP: freeze the tool surface, bound its work, and guard pane input

.github/WRITING.md

@@ -73,15 +73,14 @@ An entry opens with a bold clause naming what changed, then gives the prose that
 makes it decidable:
 
 ```markdown
-- **`tmux_whoami` failed on a socket with no server behind it.** It is the tool
-  the instructions tell a model to call first, and it asked tmux for its
-  version, which needs a running server. It now says there is no server and
-  points at `tmux_list_servers`.
+- **`capture_since` now reports an observe-only tmux effect.** Reading from a
+  cursor leaves tmux state unchanged, so the capability metadata no longer
+  overstates what the call changes.
 ```
 
-Name identifiers literally: `Pane.capture`, `LIBTMUX_WATCH`, `--rerun-tasks`,
-`tmux://panes/{pane}`. Lead with a concrete verb — add, fix, remove, reject,
-`now`, `no longer`.
+Name identifiers literally: `Pane.capture`, `LIBTMUX_TOOLSETS`,
+`--rerun-tasks`, `tmux://capabilities`. Lead with a concrete verb: add, fix,
+remove, reject, `now`, or `no longer`.
 
 State a changed default explicitly, and an incompatibility more explicitly
 still, with the way forward in the same entry.
@@ -354,8 +353,8 @@ has nothing but the string:
   "JDK 21" both appear upstream — this project writes **JDK 21**.
 - A **pane**, **window**, **session**, and **server** are what tmux calls them.
   Do not introduce a synonym for one.
-- Write the identifier, not a description of it: `LIBTMUX_WATCH=true`, not
-  "the watch environment variable"; `--rerun-tasks`, not "the rerun flag";
+- Write the identifier, not a description of it: `LIBTMUX_TOOLSETS=inspect`,
+  not "the toolset environment variable"; `--rerun-tasks`, not "the rerun flag";
   `/tmp/libtmux-java-test/`, not "the test socket directory".
 
 Treat AI slop as review-hostile noise. The goal is information density:

CHANGELOG.md

@@ -14,6 +14,19 @@ production.
 
 ### Added
 
+- **`tools/mcp-swap` configures all eight supported agent clients.** It replaces
+  the retired `scripts/mcp_swap.py`, builds through
+  `./gradlew :tools:mcp-swap:installDist`, and decodes JSON, JSONC, and TOML
+  with strict UTF-8. OpenCode edits preserve JSONC comments and trailing commas,
+  Pi reports its adapter prerequisite, and `antigravity` selects canonical
+  `agy`. Multi-client use and revert preflight and stage one transaction,
+  preserve config symlinks, reverse proven writes on failure, and keep
+  `--dry-run` fully observational. Persistent, versioned recovery records bind
+  each backup to the exact swapped config, path topology, and server route;
+  drift fails closed without deleting recovery.
+- **`NamedServerFixture` safely owns explicitly named test servers.** It binds
+  teardown to the reported process, socket path, and inode, then fails closed if
+  any of that identity changes before cleanup.
 - **`Pane.findWindow` searches by name, title, or content, with
   case-insensitive and regular-expression matching.** Build a `FindSpec` or
   configure one inline. (#6)
@@ -26,6 +39,32 @@ production.
 
 ### Changed
 
+- **`libtmux-mcp` now exposes a fixed 45-tool capability surface.** One native
+  registry drives tool registration, schemas, trust metadata, selection, and
+  the static `tmux://capabilities` resource. Unordered toolsets and named
+  include/exclude lists replace safety tiers; the retired `LIBTMUX_SAFETY`
+  variable and `--safety` option now fail with migration guidance. The retired
+  `LIBTMUX_WATCH` variable and `--watch` option also fail; use bounded wait and
+  capture tools instead of dynamic resource notifications. The server defaults
+  to the dedicated `libtmux-mcp` socket, supports separate socket-name and
+  absolute socket-path selectors, and enables teardown by default only for a
+  newly created minimal daemon.
+- **Copy-mode entry and exit remain library-only.** The MCP surface reads pane
+  text through `capture_pane` history, `snapshot_pane`, `search_panes`, or
+  `capture_since` without taking ownership of an attached client's modal
+  interface. Java callers retain `Pane.copyMode` and `Pane.exitMode`.
+- **The MCP guide maps every earlier public tool, resource URI, prompt workflow,
+  and completion path.** Each retired name now points to its current typed
+  route, composed workflow, or explicit no-replacement boundary.
+- **MCP searches and read batches now have fixed work ceilings.** Search stops
+  after 200 panes, 20,000 lines, 1,000,000 bytes of matching input, or five
+  seconds. Read batches validate each nested call and cap the complete JSON-RPC
+  response, including line framing, at 1,000,000 bytes without dropping an
+  executed row. Request IDs over 512 KiB now fail before dispatch rather than
+  consuming that response budget.
+- **`capture_since` and `call_read_tools_batch` now advertise observe-only tmux
+  effects.** Cursor capture and every batch-eligible inspect operation leave
+  tmux state unchanged.
 - **`Pane.findWindowByName` and `Pane.findWindowByContent` are removed.** Use
   `findWindow` with `inName()` or `inContent()`. (#6)
 - **`Server.waitFor`, `waitForWithSignalCapacity`, `signal`, and `drain` move
@@ -60,6 +99,31 @@ production.
 
 ### Fixed
 
+- **`Pane.sendKeys` preserves option-shaped input.** It ends tmux option parsing
+  before caller keys, so values such as `-X`, `-R`, and `-N` reach pane programs
+  through the core API and MCP single or batch routes.
+- **`Pane.breakOut` preserves literal `#` in requested window names.** The
+  `break-pane -n` path receives the raw name; only the tmux 3.7 rename fallback
+  applies tmux format literalization.
+- **MCP capability rows disclose both output risk dimensions.** Pane text,
+  environment and configured-command values, and names, titles, paths, or
+  current commands now advertise both secret and untrusted-content risk;
+  strictly structural results remain false for both.
+- **MCP pane input now refuses effective recipients in a human-owned mode.**
+  `send_keys` and each `send_keys_batch` operation resolve pane-level
+  `synchronize-panes` overrides before dispatch; `paste_text` remains
+  target-only, dead configured recipients fail closed, and
+  `run_shell_command` checks a singular cohort before setup and again before
+  input because its completion, output, and status are singular.
+- **`run_shell_command` no longer relies on mutable pane-shell framing state.**
+  Completion markers and signalling run in an isolated outer subshell through
+  an absolute selected tmux executable and the server's resolved `-S` socket,
+  so ordinary output-command aliases/functions, pane `PATH`/socket variables,
+  inherited `errexit`, and a readonly nonce name cannot lose completion or
+  close the pane; the frame also leaves no status variable behind. This assumes
+  the parent shell has not replaced the exact client word or
+  `trap`/`eval`/`exit` with functions, and marker commands honor trusted server
+  hooks.
 - **Destructive MCP tools fail closed when caller-pane identity cannot be
   proven.** Uncertain socket, server, or pane identity now requires explicit
   self-confirmation instead of bypassing the guard. (#6)
@@ -128,6 +192,9 @@ production.
 
 ### Removed
 
+- **MCP prompts, completions, watches, dynamic resources, per-call server
+  discovery, and workspace tools are removed.** Use the fixed tool surface and
+  its static `tmux://capabilities` resource.
 - **`ExecutionMode`, `ControlTransport`, `VirtualThreadTransport`,
   `LIBTMUX_MODE`, and their benchmark surface are removed.** `Server` uses
   process execution; use `ControlClient` for event streams and batches or

build-logic/src/main/kotlin/libtmux.java-library.gradle.kts

@@ -1,4 +1,10 @@
 // Shared Java conventions. A module script then declares only what makes it different.
+import java.nio.charset.StandardCharsets
+import java.nio.file.Files
+import java.nio.file.LinkOption
+import java.nio.file.Path
+import java.security.MessageDigest
+import java.util.HexFormat
 import net.ltgt.gradle.errorprone.errorprone
 
 plugins {
@@ -94,8 +100,7 @@ tasks.withType<Test>().configureEach {
     // a real server and can kill it. Two environment values decide where a bare client lands: tmux
     // resolves its default socket under TMUX_TMPDIR when it execs, and $TMUX takes precedence over
     // that for a client started inside a pane — which the Gradle daemon may well have been.
-    val tmuxTmpDir = layout.buildDirectory.dir("tmux-tmpdir").get().asFile
-    environment("TMUX_TMPDIR", tmuxTmpDir.absolutePath)
+    // TMUX_TMPDIR is set per invocation in doFirst below, under the same root as the named sockets.
     environment.remove("TMUX")
     environment.remove("TMUX_PANE")
 
@@ -113,7 +118,34 @@ tasks.withType<Test>().configureEach {
         require(socketRoot.length <= 40) {
             "libtmuxSocketRoot is $socketRoot, too long to leave room for a socket under it"
         }
-        tmuxTmpDir.mkdirs()
+        // The quarantine shares the configured root, so overriding libtmuxSocketRoot moves the
+        // bare-client sockets along with the named ones instead of splitting them across two roots.
+        // Owner identity separates concurrent invocations; 16 hex digits leave AF_UNIX room.
+        val quarantineIdentity = listOf(
+            rootProject.rootDir.canonicalPath,
+            path,
+            ProcessHandle.current().pid().toString(),
+        ).joinToString("\u0000")
+        val quarantineDigest = MessageDigest.getInstance("SHA-256")
+            .digest(quarantineIdentity.toByteArray(StandardCharsets.UTF_8))
+        val quarantineName = HexFormat.of().formatHex(quarantineDigest, 0, 8)
+        val tmuxTmpDir = Path.of(socketRoot, quarantineName)
+
+        if (Files.exists(tmuxTmpDir, LinkOption.NOFOLLOW_LINKS)) {
+            require(Files.isDirectory(tmuxTmpDir, LinkOption.NOFOLLOW_LINKS)) {
+                "tmux quarantine is not a directory: $tmuxTmpDir"
+            }
+            val entries = Files.walk(tmuxTmpDir).use { paths -> paths.toList() }
+            val stale = entries.firstOrNull {
+                it != tmuxTmpDir && !Files.isDirectory(it, LinkOption.NOFOLLOW_LINKS)
+            }
+            require(stale == null) {
+                "tmux quarantine contains a stale entry: $stale"
+            }
+            entries.asReversed().filter { it != tmuxTmpDir }.forEach(Files::delete)
+        }
+        Files.createDirectories(tmuxTmpDir)
+        environment("TMUX_TMPDIR", tmuxTmpDir.toString())
         File(socketRoot).mkdirs()
     }
 

build.gradle.kts

@@ -105,6 +105,6 @@ val kotlinStaysDownstream =
 tasks.register("check") {
     group = "verification"
     description = "Every gate that must hold before publication."
-    dependsOn(subprojects.map { "${it.path}:check" })
+    dependsOn(subprojects.filter { it.buildFile.exists() }.map { "${it.path}:check" })
     dependsOn(platformCoversEveryPublishedModule, kotlinStaysDownstream)
 }

docs/guide/filtering.md

@@ -98,18 +98,19 @@ Java names. The `matches` operand is the exception: its syntax and numeric flags
 are those of `java.util.regex.Pattern`. A non-Java consumer must reproduce those
 semantics or reject that operator.
 
-`libtmux-mcp` is the worked example. Its `tmux_list_panes` tool takes an optional
-`filter`, which is one of these documents:
+An application that stores a pane predicate is the worked example. The wire
+form is one of these documents:
 
 ```json
 {"schema": "libtmux.filter/1", "model": "pane",
  "expr": {"node": "compare", "field": "pane_current_command",
           "op": "starts_with", "value": "nvim"}}
 ```
 
-A model cannot write Java, so this is the only way it can say what it wants
-narrowed. What it gets back costs the same one capture the unfiltered listing
-would have, because the filter runs over what that capture returned.
+Java applications can read that document with the matching `FilterModel` and
+apply it to a captured hierarchy. `libtmux-mcp` deliberately does not accept
+this open expression format: `list_panes` returns bounded typed metadata for a
+client to filter, while `search_panes` searches only rendered terminal text.
 
 ## Filters that arrive as strings