Claimed shapes carry vendor fields verbatim; say so honestly

A short-circuiting tools/call interceptor's dict is passed through by
the runner as a trusted well-formed result — nothing strips vendor
top-level fields on the way to the client. The docs, tutorials, and
test fixtures previously claimed the opposite and string-packed
payloads into requestState; the claim models now carry real vendor
fields end to end (the settings-echo test gains a dict-typed field
instead of JSON string-packing). Also: the closed-surface bullet now
says notification bindings shadowed by core vocabulary go quiet rather
than being rejected, the core-subclass rule is scoped to the verb's
result types, and the notification-binding contribution kind gets a
deferred manifest entry naming its session-tier coverage.

Author: maxisbey

docs/advanced/extensions.md

@@ -188,10 +188,10 @@ kinds, each with a default: `settings()`, `claims()`, and `notifications()`.
   is defined.
 * `claims()` returns `ResultClaim`s: a wire tag, the model that parses it, and the
   resolver that finishes it. The model must pin the tag with
-  `result_type: Literal["receipt"]` and must not subclass a core result type — both
-  enforced when the claim is constructed. (The payload rides `requestState` here
-  because an `MCPServer` substituting a claimed shape serializes only the core
-  `tools/call` surface fields; a server on another SDK may send richer shapes.)
+  `result_type: Literal["receipt"]` and must not subclass the verb's core result
+  types — both enforced when the claim is constructed. Vendor fields like
+  `receipt_token` ride the wire as-is: a substituted shape reaches the client
+  verbatim.
 * The resolver receives the parsed model and a `ClaimContext`; `ctx.session` is the
   same public handle as `client.session`, so follow-ups are ordinary session calls.
   It returns the verb's normal `CallToolResult`.
@@ -238,8 +238,9 @@ resources, methods, one `tools/call` interceptor; on the client: settings, resul
 claims, notification bindings. An extension cannot:
 
 * **Reach into the host.** It declares data; it holds no server or client reference.
-* **Replace core behaviour.** Spec methods are rejected at construction, and
-  `initialize` is reserved by the runner outright.
+* **Replace core behaviour.** Spec methods and core result tags are rejected at
+  construction (`initialize` is reserved by the runner outright); a notification
+  binding shadowed by core vocabulary goes quiet with a warning instead.
 * **Register late.** After `MCPServer(...)` or `Client(...)` returns, the extension
   set is what it is.
 

docs_src/extensions/tutorial006.py

@@ -16,7 +16,7 @@ class ReceiptResult(types.Result):
     """The claimed result shape; `result_type` pins the wire tag."""
 
     result_type: Literal["receipt"] = "receipt"
-    request_state: str
+    receipt_token: str
 
 
 class ReceiptIssuer(Extension):
@@ -32,7 +32,7 @@ async def intercept_tool_call(
     ) -> HandlerResult:
         if params.name != "buy":
             return await call_next(ctx)
-        return {"resultType": "receipt", "requestState": "r-117"}
+        return {"resultType": "receipt", "receiptToken": "r-117"}
 
 
 class Receipts(ClientExtension):
@@ -44,7 +44,7 @@ def claims(self) -> Sequence[ResultClaim[Any]]:
         return [ResultClaim(result_type="receipt", model=ReceiptResult, resolve=self._redeem)]
 
     async def _redeem(self, claimed: ReceiptResult, ctx: ClaimContext) -> types.CallToolResult:
-        return await ctx.session.call_tool("redeem", {"token": claimed.request_state})
+        return await ctx.session.call_tool("redeem", {"token": claimed.receipt_token})
 
 
 mcp = MCPServer("shop", extensions=[ReceiptIssuer()])

tests/client/test_client_extensions.py

@@ -3,10 +3,8 @@
 
 Claimed-shape servers here are real `MCPServer`s whose SEP-2133 server extension
 rewrites `tools/call` results via `intercept_tool_call` — the full public-API loop.
-The in-process server can only deliver claimed fields the v2026 tools/call surface
-keeps (`resultType`, `requestState`, `inputRequests`, `_meta`): the server-side
-`serialize_server_result` drops anything else, so claimed payloads here ride
-`requestState`.
+A short-circuiting interceptor's dict reaches the client verbatim (the runner trusts
+it as a well-formed result), so the claimed models carry vendor top-level fields.
 
 `tools/call` is never cached (`Client.call_tool` has no `_cached_fetch` weave and the
 SEP-2549 cacheable verbs do not include it), so the claim path needs no cache tests.
@@ -48,11 +46,11 @@ def _name_elicitation() -> types.ElicitRequest:
 
 
 class VoucherResult(Result):
-    """The claimed `tools/call` shape, tagged `voucher`; its payload rides `requestState`
-    (the only open payload-bearing field the in-process server's surface dump keeps)."""
+    """The claimed `tools/call` shape, tagged `voucher`, carrying a vendor top-level field
+    (a short-circuiting server interceptor's dict reaches the client verbatim)."""
 
     result_type: Literal["voucher"] = "voucher"
-    request_state: str | None = None
+    voucher_code: str | None = None
 
 
 _Resolver = Callable[[VoucherResult, ClaimContext], Awaitable[CallToolResult]]
@@ -78,7 +76,7 @@ class _VoucherIssuer(Extension):
     async def intercept_tool_call(
         self, params: types.CallToolRequestParams, ctx: ServerRequestContext[Any, Any], call_next: CallNext
     ) -> HandlerResult:
-        return {"resultType": "voucher", "requestState": "v-42"}
+        return {"resultType": "voucher", "voucherCode": "v-42"}
 
 
 class _TwoRoundVoucherIssuer(Extension):
@@ -91,7 +89,7 @@ async def intercept_tool_call(
     ) -> HandlerResult:
         if params.input_responses is None:
             return types.InputRequiredResult(input_requests={"user_name": _name_elicitation()})
-        return {"resultType": "voucher", "requestState": "after-input"}
+        return {"resultType": "voucher", "voucherCode": "after-input"}
 
 
 def _voucher_server(issuer: Extension | None = None) -> MCPServer:
@@ -414,7 +412,7 @@ async def test_claimed_result_resolves_transparently_to_the_resolvers_result() -
 
     async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
         received.append(claimed)
-        product = CallToolResult(content=[TextContent(text=f"honored {claimed.request_state}")])
+        product = CallToolResult(content=[TextContent(text=f"honored {claimed.voucher_code}")])
         produced.append(product)
         return product
 
@@ -423,7 +421,7 @@ async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
             result = await client.call_tool("issue", {})
             assert_type(result, CallToolResult)
 
-    assert [claimed.request_state for claimed in received] == ["v-42"]
+    assert [claimed.voucher_code for claimed in received] == ["v-42"]
     assert result is produced[0]
     assert result.content == [TextContent(text="honored v-42")]
 
@@ -442,7 +440,7 @@ async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
         async with Client(_voucher_server(), extensions=extensions) as client:
             result = await client.call_tool("issue", {})
 
-    assert [claimed.request_state for claimed in received] == ["v-42"]
+    assert [claimed.voucher_code for claimed in received] == ["v-42"]
     assert result.content == [TextContent(text="routed")]
 
 
@@ -586,7 +584,7 @@ async def elicitation_callback(
 
     async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
         received.append(claimed)
-        return CallToolResult(content=[TextContent(text=f"honored {claimed.request_state}")])
+        return CallToolResult(content=[TextContent(text=f"honored {claimed.voucher_code}")])
 
     server = _voucher_server(issuer=_TwoRoundVoucherIssuer())
     with anyio.fail_after(5):
@@ -596,7 +594,7 @@ async def resolve(claimed: VoucherResult, ctx: ClaimContext) -> CallToolResult:
             result = await client.call_tool("issue", {})
 
     assert prompted == ["What is your name?"]
-    assert [claimed.request_state for claimed in received] == ["after-input"]
+    assert [claimed.voucher_code for claimed in received] == ["after-input"]
     assert result.content == [TextContent(text="honored after-input")]
 
 

tests/docs_src/test_extensions.py

@@ -126,7 +126,7 @@ async def test_session_tier_allow_claimed_returns_the_raw_shape() -> None:
     async with Client(tutorial006.mcp, extensions=[tutorial006.Receipts()]) as client:
         result = await client.session.call_tool("buy", {"item": "lamp"}, allow_claimed=True)
     assert isinstance(result, tutorial006.ReceiptResult)
-    assert result.request_state == "r-117"
+    assert result.receipt_token == "r-117"
 
 
 async def test_the_jobs_client_program_runs_as_shown(capsys: pytest.CaptureFixture[str]) -> None:

tests/interaction/_requirements.py

@@ -2428,6 +2428,19 @@ def __post_init__(self) -> None:
         ),
         arm_exclusions=(ArmExclusion(reason="requires-session", transport="streamable-http-stateless"),),
     ),
+    "extensions:client:notification-binding-delivery": Requirement(
+        source=f"{SPEC_2026_BASE_URL}/basic#resulttype",
+        behavior=(
+            "A vendor server notification bound by a ClientExtension's NotificationBinding is validated "
+            "against the binding's params type and delivered to its handler in arrival order."
+        ),
+        added_in="2026-07-28",
+        deferred=(
+            "Covered at session tier by tests/client/test_session_notification_bindings.py: no public "
+            "server-side surface emits vendor-method notifications (ServerNotification is a closed union), "
+            "and HTTP-modern arrival additionally needs the subscriptions/listen client runtime."
+        ),
+    ),
     # ═══════════════════════════════════════════════════════════════════════════
     # Transports (in-suite coverage)
     # ═══════════════════════════════════════════════════════════════════════════

tests/interaction/mcpserver/test_extensions.py

@@ -2,12 +2,11 @@
 
 The servers here are MCPServers whose server extension substitutes a claimed `tools/call`
 shape via `intercept_tool_call`; the client declares the owning `ClientExtension` and its
-claim resolver finishes the call. The in-process server's 2026 result surface keeps only
-`resultType` / `requestState` / `inputRequests` / `_meta` on a claimed result, so claimed
-payloads here ride `requestState`.
+claim resolver finishes the call. A short-circuiting interceptor's dict is passed through
+verbatim (the runner trusts it as a well-formed result), so claimed shapes carry their
+vendor fields end to end — the models below prove that with top-level vendor fields.
 """
 
-import json
 from collections.abc import Awaitable, Callable, Sequence
 from typing import Any, Literal
 
@@ -32,10 +31,11 @@
 
 
 class ReceiptResult(Result):
-    """The claimed `tools/call` shape, tagged `receipt`; its payload rides `requestState`."""
+    """The claimed `tools/call` shape, tagged `receipt`, carrying vendor top-level fields."""
 
     result_type: Literal["receipt"] = "receipt"
-    request_state: str
+    receipt_token: str
+    settings_echo: dict[str, Any] | None = None
 
 
 _Resolver = Callable[[ReceiptResult, ClaimContext], Awaitable[CallToolResult]]
@@ -67,7 +67,7 @@ async def intercept_tool_call(
     ) -> HandlerResult:
         if params.name != "buy":
             return await call_next(ctx)
-        return {"resultType": "receipt", "requestState": "r-117"}
+        return {"resultType": "receipt", "receiptToken": "r-117"}
 
 
 def _receipt_shop(issuer: Extension) -> MCPServer:
@@ -97,12 +97,12 @@ async def test_claimed_result_is_finished_by_the_owning_extensions_resolver(conn
 
     async def redeem_receipt(claimed: ReceiptResult, ctx: ClaimContext) -> CallToolResult:
         received.append(claimed)
-        return await ctx.session.call_tool("redeem", {"token": claimed.request_state})
+        return await ctx.session.call_tool("redeem", {"token": claimed.receipt_token})
 
     async with connect(_receipt_shop(_ReceiptIssuer()), extensions=[Receipts(redeem_receipt)]) as client:
         result = await client.call_tool("buy", {"item": "lamp"})
 
-    assert [claimed.request_state for claimed in received] == ["r-117"]
+    assert [claimed.receipt_token for claimed in received] == ["r-117"]
     assert result == snapshot(
         CallToolResult(content=[TextContent(text="goods for r-117")], structured_content={"result": "goods for r-117"})
     )
@@ -132,7 +132,7 @@ async def intercept_tool_call(
         assert client_params is not None  # require_client_extension just read it
         extensions = client_params.capabilities.extensions
         assert extensions is not None
-        return {"resultType": "receipt", "requestState": json.dumps(extensions[_RECEIPTS], sort_keys=True)}
+        return {"resultType": "receipt", "receiptToken": "echo", "settingsEcho": extensions[_RECEIPTS]}
 
 
 @requirement("extensions:client:capability-ad:gates-server-behaviour")
@@ -157,7 +157,7 @@ async def keep(claimed: ReceiptResult, ctx: ClaimContext) -> CallToolResult:
     async with connect(server, extensions=[Receipts(keep, settings={"tier": "gold"})]) as client:
         result = await client.call_tool("buy", {"item": "lamp"})
     assert result.content == [TextContent(text="done")]
-    assert [json.loads(claimed.request_state) for claimed in received] == [{"tier": "gold"}]
+    assert [claimed.settings_echo for claimed in received] == [{"tier": "gold"}]
 
     async with connect(server) as client:
         with pytest.raises(MCPError) as exc_info: