docs(sacp): add guidance on when to use MatchMessage vs MatchMessageFrom

- Add module-level 'When to use which' section
- Recommend MatchMessageFrom over JrMessageHandler implementations
- Clarify MatchMessage is for unwrapped messages or inside callbacks

Author: nikomatsakis

src/sacp/src/session.rs

@@ -135,6 +135,7 @@ where
 #[non_exhaustive]
 pub enum SessionMessage {
     /// Periodic updates with new content, tool requests, etc.
+    /// Use [`MatchMessage`] to match on the message type.
     SessionMessage(MessageCx),
 
     /// When a prompt completes, the stop reason.

src/sacp/src/util/typed.rs

@@ -3,6 +3,18 @@
 //! When handling [`UntypedMessage`]s, you can use [`MatchMessage`] for simple parsing
 //! or [`MatchMessageFrom`] when you need role-aware endpoint transforms (e.g., unwrapping
 //! proxy envelopes).
+//!
+//! # When to use which
+//!
+//! - **[`MatchMessageFrom`]**: Preferred over implementing [`JrMessageHandler`] directly.
+//!   Use this in connection handlers when you need to match on message types with
+//!   proper endpoint-aware transforms (e.g., unwrapping `SuccessorMessage` envelopes).
+//!
+//! - **[`MatchMessage`]**: Use this when you already have an unwrapped message and
+//!   just need to parse it, such as inside a [`MatchMessageFrom`] callback or when
+//!   processing messages that don't need endpoint transforms.
+//!
+//! [`JrMessageHandler`]: crate::JrMessageHandler
 
 // Types re-exported from crate root
 use jsonrpcmsg::Params;
@@ -16,9 +28,12 @@ use crate::{
 
 /// Role-agnostic helper for pattern-matching on untyped JSON-RPC messages.
 ///
-/// Use this when you just need to parse messages as specific types without
-/// any endpoint-aware transforms. For role-aware matching that handles
-/// proxy envelope unwrapping, use [`MatchMessageFrom`] instead.
+/// Use this when you already have an unwrapped message and just need to parse it,
+/// such as inside a [`MatchMessageFrom`] callback or when processing messages
+/// that don't need endpoint transforms.
+///
+/// For connection handlers where you need proper endpoint-aware transforms,
+/// use [`MatchMessageFrom`] instead.
 ///
 /// # Example
 ///
@@ -249,13 +264,19 @@ impl MatchMessage {
 
 /// Role-aware helper for pattern-matching on untyped JSON-RPC requests.
 ///
+/// **Prefer this over implementing [`JrMessageHandler`] directly.** This provides
+/// a more ergonomic API for matching on message types in connection handlers.
+///
 /// Use this when you need endpoint-aware transforms (e.g., unwrapping proxy envelopes)
-/// before parsing messages. For simple parsing without role awareness, use [`MatchMessage`].
+/// before parsing messages. For simple parsing without role awareness (e.g., inside
+/// a callback), use [`MatchMessage`] instead.
 ///
 /// This wraps [`MatchMessage`] and applies endpoint-specific message transformations
 /// via `remote_style().handle_incoming_message()` before delegating to `MatchMessage`
 /// for the actual parsing.
 ///
+/// [`JrMessageHandler`]: crate::JrMessageHandler
+///
 /// # Example
 ///
 /// ```

src/yopo/src/lib.rs

@@ -8,7 +8,7 @@ use sacp::schema::{
     RequestPermissionOutcome, RequestPermissionRequest, RequestPermissionResponse,
     SessionNotification, TextContent, VERSION as PROTOCOL_VERSION,
 };
-use sacp::util::MatchMessageFrom;
+use sacp::util::{MatchMessage, MatchMessageFrom};
 use sacp::{Component, Handled, MessageCx, UntypedMessage};
 use std::path::PathBuf;
 
@@ -120,7 +120,7 @@ pub async fn prompt_with_callback(
                 let update = session.read_update().await?;
                 match update {
                     sacp::SessionMessage::SessionMessage(message) => {
-                        MatchMessageFrom::new(message, &cx)
+                        MatchMessage::new(message)
                             .if_notification(async |notification: SessionNotification| {
                                 tracing::debug!(
                                     ?notification,