[paolocostanzo]

Closes #1394.

Adds rustdoc to ClientHandler::on_tool_list_changed, on_prompt_list_changed and on_resource_list_changed.

On a connection that negotiates 2026-07-28, list-changed notifications are sent on a subscriptions/listen stream that requested them, and the serve loop routes notifications whose io.modelcontextprotocol/subscriptionId matches an active subscription to that Subscription instead of handle_notification. Peer::listen already documents this, but the callbacks don't, so a client that only implements them can miss list changes from servers that follow the spec (e.g. aaif-goose/goose#13055).

The new docs point to Peer::listen, SubscriptionFilterBuilder::{tools,prompts,resources}_list_changed and the subscriptions_streamhttp client example, and note that the callbacks still receive notifications without a matching subscription (earlier protocol versions, or servers that send them unscoped) and that the list caches are invalidated on both paths.

Docs only, no behaviour change.

AI Disclosure (pursuant to the AI Contribution Policy): I used Claude to help write the doc comments and this description (hence the Co-Authored-By trailer); all checks and reviews were handled by me personally, and I take responsibility for the change.

[chatgpt-codex-connector]

Codex Review Summary

This comment shows the latest Codex review activity on this pull request.

Review	Status	Commit	Review trigger
📝 Code Review	🔄 Running since 2026-10-28T11:04:36.797336Z	ea0a3cf	PR opened

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review" or "@codex security review".

Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings.

[github-actions]

@gocamille is on triage rotation this week and is the reviewer for this one.

Labels come from the PR labeler. Please review the change.

_{Automated triage. Labels are a first pass and the assigned maintainer has the final say.}