docs: ClientHandler list_changed callbacks don't mention Peer::listen (2026-07-28) #1394

Summary

ClientHandler::on_tool_list_changed, on_prompt_list_changed and on_resource_list_changed (crates/rmcp/src/handler/client.rs) have no rustdoc, and nothing in that file mentions Peer::listen.

On 2026-07-28, list-changed notifications go through subscriptions/listen: servers SHOULD send notifications/tools/list_changed to clients that opened a listen stream with toolsListChanged: true (Tools), and MUST NOT send notification types the client has not requested (Subscriptions). So with a compliant server:

• a client that never calls Peer::listen gets no list-changed notifications, and the callbacks never fire;
• a client that does call it gets them on the Subscription: the serve loop routes notifications whose _meta["io.modelcontextprotocol/subscriptionId"] matches an active subscription to that channel and skips handle_notification (crates/rmcp/src/service.rs ~L1645-1678; the response cache is still invalidated first, ~L1612).

On 2025-11-25, or with servers that still send unscoped notifications, the callbacks fire as before.

Peer::listen already says "Notifications routed to the returned Subscription are not also delivered through ClientHandler callbacks", but the callbacks themselves don't, and the README's resources section (~L489, "Clients handle these via ClientHandler") shows on_resource_list_changed without pointing to the Subscriptions section. Real-world example: goose implements on_tool_list_changed without opening a listen stream (aaif-goose/goose#13055).

Proposal

Docs only: rustdoc on the three callbacks saying they receive only notifications not routed to a Subscription, pointing to Peer::listen with SubscriptionFilterBuilder::{tools,prompts,resources}_list_changed() and the subscriptions_streamhttp client example. Optionally a one-line pointer from the README's resources section to the Subscriptions section. Happy to open the PR if this direction works for you.

AI Disclosure (pursuant to the AI Contribution Policy): I used Claude to help write this issue; all checks, reviews, and code were handled by me personally.