66_Notes on upcoming releases will be added here_
77<!-- END PLACEHOLDER - ADD NEW CHANGELOG ENTRIES BELOW THIS LINE -->
88
9+ ### Dependencies
10+
11+ **Minimum `fastmcp>=4.0.2`** (was `>=3.4.2,<4.0.0`)
12+
13+ libtmux-mcp tracks the FastMCP 4 line. FastMCP 4 builds on MCP Python SDK
14+ v2, which brings `mcp>=2.0.0`, `mcp-types` and pydantic 2.12 with it, and
15+ replaces httpx with httpx2 across FastMCP's HTTP stack. No tool, resource or
16+ prompt changes shape, and one server serves both the session-based and the
17+ sessionless `2026-07-28` protocol eras, negotiated per connection.
18+
19+ **FastMCP releases are adopted without waiting out the cooldown**
20+
21+ The dependency cooldown held every FastMCP release back, so a refreshed lock
22+ resolved to a patch behind the one being tested against. `fastmcp` and its
23+ `fastmcp-slim` companion are exempt from it.
24+
25+ ### What's new
26+
27+ **`tmux://` templates answer argument completion**
28+
29+ The templates take live tmux identifiers, and MCP publishes a template's URI
30+ but never its parameter domain, so a reader had no way to discover a valid
31+ session name or pane id from the listing. A completion handler offers them
32+ from the live server, filtered by what has been typed and scoped by an
33+ already-supplied `socket_name`. A server that is gone yields no suggestions
34+ rather than an error.
35+
36+ Whether suggestions appear depends on the client. The MCP Inspector's browser
37+ UI and VS Code send `completion/complete`; measured against five agent CLIs,
38+ none do.
39+
40+ ### Fixes
41+
42+ **`tmux://` reads keep accepting tmux names that look like paths**
43+
44+ FastMCP 4 screens templated resource parameters before a handler runs. Its
45+ absolute-path check does not fit tmux identifiers: it rejects the socket paths
46+ `list_servers` reports, and reads any `<letter>:<rest>` session name — which
47+ tmux accepts — as a Windows drive-relative path. Both stay readable, so
48+ `tmux://` and the equivalent tools continue to agree on which sessions and
49+ servers exist.
50+
51+ Traversal and null-byte screening remain on, and are set per template rather
52+ than server-wide. `socket_name` reaches `tmux -L`, which appends it to the
53+ socket directory without normalising, so `../..` really does place the socket
54+ elsewhere; exempting the parameter outright would drop that guard along with
55+ the absolute-path check.
56+
57+ **A `tmux://` read that fails now says so as `-32603`**
58+
59+ FastMCP's `ErrorHandlingMiddleware` matches not-found exceptions by exact
60+ class, so only an unknown resource URI still maps to `-32002`. A missing
61+ session raises `ResourceError`, and a rejected path raises
62+ `ResourceSecurityError` — a `NotFoundError` subclass, and so not an exact
63+ match — and both reach the client as `-32603` "Internal error". The message is
64+ unchanged; only clients matching on the numeric code are affected.
65+
66+ **A wait tool survives a context that carries no session**
67+
68+ `Context.session` raises rather than degrading when there is no request
69+ context, so `ctx.warning` and `ctx.report_progress` took the whole tool call
70+ down in any execution that lacks one. The wait helpers check before
71+ delivering: the call returns its normal result, without notifications, instead
72+ of failing. Notification delivery on an ordinary request is unchanged.
73+
974### Documentation
1075
76+ **The completion topic describes the handlers the server registers**
77+
78+ The page said libtmux-mcp registered no completion handlers and offered
79+ workarounds for the gap. It describes what the `tmux://` templates complete,
80+ and states the caveat where it now belongs: whether suggestions appear depends
81+ on the client. The retired claims are pinned as forbidden text, so the page
82+ cannot drift back to underclaiming a shipped feature.
83+
1184**The toolset migration notes reach the migration page**
1285
1386The 0.1.0a21 notes mapping the retired tiers onto `inspect`, `manage`,
@@ -17,6 +90,38 @@ of `MIGRATION`, and they state that `LIBTMUX_SAFETY` raises while the server
1790module loads — every value, the former default `mutating` included — and that
1891the former default is reached by removing the variable and setting nothing.
1992
93+ ### Development
94+
95+ **A Sphinx warning fails the documentation build**
96+
97+ The docs workflow passes `-W --keep-going`, so a warning stops the build that
98+ publishes the site instead of scrolling past in a green run.
99+
100+ **Path-like session-name tests skip on tmux below 3.7**
101+
102+ tmux before 3.7 rewrites `:` and `.` in a session name to `_`, turning `a:1`
103+ into `a_1`, and exits 0 with no stderr — so a caller cannot tell from the
104+ result. The resource tests that need such a name check what tmux stored and
105+ skip when it differs, naming the rewrite. They ran only against a newer tmux
106+ before, and reported the resulting absent session as a failed read on every
107+ supported tmux in CI.
108+
109+ **The test suite runs without FastMCP's camelCase compatibility shims**
110+
111+ FastMCP 4 answers MCP SDK v1 attribute spellings such as `tool.inputSchema`
112+ through warn-once shims it plans to remove. Neither gate catches a test that
113+ depends on one: the type checker sees `Any`, and the warning fires once per
114+ attribute for the whole run. The suite sets `FASTMCP_MCP_CAMELCASE_COMPAT=false`,
115+ so a surviving camelCase read raises `AttributeError` and fails the test that
116+ made it.
117+
118+ **The compatibility reference is bound to the manifest**
119+
120+ The dependency table restated floors by hand and had drifted: it named libtmux
121+ 0.55 against a manifest requiring 0.62, and omitted `regex` entirely. A test
122+ compares the table against `[project].dependencies` as version ranges, so the
123+ next floor that moves without its documentation fails the suite.
124+
20125## libtmux-mcp 0.1.0a21 (2026-08-30)
21126
22127libtmux-mcp 0.1.0a21 replaces cumulative safety tiers with independently
0 commit comments