Fold result claims and notification bindings into ClientSession

Claims arrive keyed by their owning extension identifier; at adopt() the
active set is computed for the negotiated version and the tools/call
result adapter is rebuilt as a discriminated union (zero active claims
keeps the module-level adapter, byte-identical parsing). The capability
ad is built per version through the same association, so an extension
whose claims are all inactive is not advertised — the ad and the claims
dissolve together, on the initialize, discover-probe, and modern-stamp
paths alike. call_tool gains allow_claimed: a claimed shape raises
UnexpectedClaimedResult carrying the parsed value unless allowed.
Notification bindings deliver through per-binding bounded FIFOs with one
serialized consumer task each; enqueue never awaits, and overflow drops
the oldest event with a warning. CORE_RESULT_TYPES derives from the
ResultType literal in mcp-types, one source of truth for both the claim
constructor and the session.

Author: maxisbey

src/mcp-types/mcp_types/__init__.py

@@ -8,6 +8,7 @@
 from mcp_types._types import (
     CLIENT_CAPABILITIES_META_KEY,
     CLIENT_INFO_META_KEY,
+    CORE_RESULT_TYPES,
     DEFAULT_NEGOTIATED_VERSION,
     LOG_LEVEL_META_KEY,
     PROTOCOL_VERSION_META_KEY,
@@ -231,6 +232,7 @@
     "CLIENT_CAPABILITIES_META_KEY",
     "LOG_LEVEL_META_KEY",
     # Type aliases and variables
+    "CORE_RESULT_TYPES",
     "ContentBlock",
     "ElicitRequestedSchema",
     "ElicitRequestParams",

src/mcp-types/mcp_types/_types.py

@@ -8,7 +8,7 @@
 
 from __future__ import annotations
 
-from typing import Annotated, Any, ClassVar, Final, Generic, Literal, TypeAlias, TypeVar
+from typing import Annotated, Any, ClassVar, Final, Generic, Literal, TypeAlias, TypeVar, get_args
 
 from pydantic import (
     BaseModel,
@@ -150,14 +150,19 @@ class Notification(MCPModel, Generic[NotificationParamsT, MethodT]):
     params: NotificationParamsT
 
 
-ResultType = Literal["complete", "input_required"] | str
+_CoreResultType = Literal["complete", "input_required"]
+
+ResultType = _CoreResultType | str
 """Tags a `Result` so the client knows how to parse it (2026-07-28).
 
 "complete" means the result is final; "input_required" means it is an
 `InputRequiredResult`. The union is open (the tasks extension reserves "task").
 Absent `resultType` is equivalent to "complete".
 """
 
+CORE_RESULT_TYPES: Final[frozenset[str]] = frozenset(get_args(_CoreResultType))
+"""The `resultType` tags owned by the core protocol vocabulary; extension claims may not re-key them."""
+
 
 class Result(MCPModel):
     """Base class for JSON-RPC results.

src/mcp/client/__init__.py

@@ -17,6 +17,7 @@
     ClientExtension,
     NotificationBinding,
     ResultClaim,
+    UnexpectedClaimedResult,
     advertise,
 )
 from mcp.client.session import ClientSession
@@ -37,5 +38,6 @@
     "ResponseCacheStore",
     "ResultClaim",
     "Transport",
+    "UnexpectedClaimedResult",
     "advertise",
 ]

src/mcp/client/extension.py

@@ -14,7 +14,7 @@
 from dataclasses import dataclass
 from typing import TYPE_CHECKING, Any, Generic, Literal, TypeVar, get_args
 
-from mcp_types import CallToolResult, InputRequiredResult, Result
+from mcp_types import CORE_RESULT_TYPES, CallToolResult, InputRequiredResult, Result
 from mcp_types.version import MODERN_PROTOCOL_VERSIONS
 from pydantic import BaseModel
 
@@ -28,6 +28,7 @@
     "ClientExtension",
     "NotificationBinding",
     "ResultClaim",
+    "UnexpectedClaimedResult",
     "advertise",
 ]
 
@@ -81,7 +82,7 @@ class ResultClaim(Generic[ClaimedT]):
     protocol_versions: frozenset[str] | None = None
 
     def __post_init__(self) -> None:
-        if self.result_type in ("complete", "input_required"):
+        if self.result_type in CORE_RESULT_TYPES:
             raise ValueError(f"resultType {self.result_type!r} is core protocol vocabulary")
         if issubclass(self.model, CallToolResult | InputRequiredResult):
             raise ValueError("claim models must not subclass core result types")
@@ -98,9 +99,30 @@ def __post_init__(self) -> None:
             )
 
 
+class UnexpectedClaimedResult(RuntimeError):
+    """A claimed (extension) result shape arrived on a `call_tool` that did not opt in.
+
+    Raised by `ClientSession.call_tool` when a claimed shape parses and
+    `allow_claimed` is False. By the time this raises the server may have
+    durably created state (e.g. a task) — the parsed value is carried as
+    `result` so the caller can reach its id to clean up, not just read a
+    message. To handle claimed shapes, pass the owning extension to
+    `Client(extensions=[...])` (the transparent path) or call with
+    `allow_claimed=True` and handle the shape yourself.
+    """
+
+    def __init__(self, result: Result) -> None:
+        super().__init__(
+            f"Server returned a claimed result ({type(result).__name__}); pass the owning extension to "
+            "Client(extensions=[...]) for transparent resolution, or call with allow_claimed=True "
+            "and handle the shape. The carried result may reference server-side state needing cleanup."
+        )
+        self.result = result
+
+
 @dataclass(frozen=True, kw_only=True)
 class NotificationBinding(Generic[NotifyParamsT]):
-    """Deliver server notifications for `method` to `handler` (today: silently dropped).
+    """Deliver server notifications for `method` to `handler` (unbound methods stay silently dropped).
 
     Observation-only: the handler receives validated params, returns None, and
     cannot short-circuit anything. Delivery is per-binding serialized through a