ruby-mcp-client 2.1.0 → 3.0.0

data/lib/mcp_client/client.rb

@@ -2,28 +2,66 @@
 
 require 'logger'
 require 'securerandom'
+require_relative 'client/sampling_validation'
+require_relative 'deep_copy'
+require_relative 'client/list_aggregation'
+require_relative 'client/cache_slices'
+require_relative 'client/notification_routing'
+require_relative 'deprecations'
+require_relative 'client/task_support'
+require_relative 'client/task_api'
 
 module MCPClient
   # MCP Client for integrating with the Model Context Protocol
   # This is the main entry point for using MCP tools
   class Client
+    include SamplingValidation
+    include ListAggregation
+    include CacheSlices
+    include NotificationRouting
+    include MCPClient::Client::TaskSupport
+    include MCPClient::Client::TaskApi
+
+    # Ceiling on the schema-violation text that reaches a log line or an
+    # exception (the validator already bounds its error count).
+    MAX_VIOLATION_TEXT = 4000
+
     # Elicitation modes implemented by this client (MCP 2025-11-25).
     # Requests with a mode outside this set are rejected with -32602.
     SUPPORTED_ELICITATION_MODES = %w[form url].freeze
 
-    # @!attribute [r] servers
-    #   @return [Array<MCPClient::ServerBase>] list of servers
-    # @!attribute [r] tool_cache
-    #   @return [Hash<String, MCPClient::Tool>] cache of tools by composite key (server_id:name)
-    # @!attribute [r] prompt_cache
-    #   @return [Hash<String, MCPClient::Prompt>] cache of prompts by composite key (server_id:name)
-    # @!attribute [r] resource_cache
-    #   @return [Hash<String, MCPClient::Resource>] cache of resources by composite key (server_id:uri)
-    # @!attribute [r] logger
-    #   @return [Logger] logger for client operations
-    # @!attribute [r] roots
-    #   @return [Array<MCPClient::Root>] list of MCP roots (MCP 2025-06-18)
-    attr_reader :servers, :tool_cache, :prompt_cache, :resource_cache, :logger, :roots
+    # These readers are declared one per line with an ordinary doc comment
+    # rather than grouped under `@!attribute` directives, because the directive
+    # form loses documentation silently: YARD drops the docstring of the LAST
+    # directive in a block preceding a combined `attr_reader`, re-registering
+    # that name from the statement itself with the leftover (empty) docstring.
+    # The `roots` deprecation below was absent from the generated API
+    # documentation for exactly that reason, while every check that read the
+    # source found it.
+
+    # @return [Array<MCPClient::ServerBase>] list of servers
+    attr_reader :servers
+
+    # @return [Hash<String, MCPClient::Tool>] cache of tools by composite key (server_id:name)
+    attr_reader :tool_cache
+
+    # @return [Hash<String, MCPClient::Prompt>] cache of prompts by composite key (server_id:name)
+    attr_reader :prompt_cache
+
+    # @return [Hash<String, MCPClient::Resource>] cache of resources by composite key (server_id:uri)
+    attr_reader :resource_cache
+
+    # @return [Logger] logger for client operations
+    attr_reader :logger
+
+    # @return [Array<MCPClient::Root>] list of MCP roots (MCP 2025-06-18)
+    # @deprecated Roots is deprecated since MCP 2026-07-28 (SEP-2577); earliest
+    #   removal is the first revision released on or after 2027-07-28. Reading the
+    #   list is not itself a first use of the feature — the notice follows
+    #   configuring a root or serving one — but the list is a deprecated feature's
+    #   state, and a host reading it is holding one. Pass directories or files
+    #   through tool parameters, resource URIs or server configuration instead.
+    attr_reader :roots
 
     # Supported modes for structuredContent validation (MCP 2025-11-25):
     # :warn logs a warning on mismatch, :strict raises a ValidationError.
@@ -38,6 +76,11 @@ module MCPClient
     # Placeholder written in place of a redacted value.
     REDACTED = '[REDACTED]'
 
+    # Where {#register_notification_handlers} leaves word, on the thread that
+    # is routing, that the caches for the notification in hand have already
+    # been dropped by the transport's invalidation hook.
+    CACHE_INVALIDATION_MARK = :mcp_client_cache_invalidation
+
     # Maximum characters of a peer-supplied log message written to the host
     # log. The remote server controls this content, so an unbounded message
     # would let it inflate log storage at will.
@@ -47,8 +90,13 @@ module MCPClient
     # @param mcp_server_configs [Array<Hash>] configurations for MCP servers
     # @param logger [Logger, nil] optional logger, defaults to STDOUT
     # @param elicitation_handler [Proc, nil] optional handler for elicitation requests (MCP 2025-06-18)
-    # @param roots [Array<MCPClient::Root, Hash>, nil] optional list of roots (MCP 2025-06-18)
-    # @param sampling_handler [Proc, nil] optional handler for sampling requests (MCP 2025-11-25)
+    # @param roots [Array<MCPClient::Root, Hash>, nil] optional list of roots (MCP 2025-06-18).
+    #   Deprecated since MCP 2026-07-28 (SEP-2577); earliest removal is the first revision
+    #   released on or after 2027-07-28. Pass directories or files through tool parameters,
+    #   resource URIs or server configuration instead.
+    # @param sampling_handler [Proc, nil] optional handler for sampling requests (MCP 2025-11-25).
+    #   Deprecated since MCP 2026-07-28 (SEP-2577); earliest removal is the first revision
+    #   released on or after 2027-07-28. Integrate directly with the LLM provider API instead.
     # @param sampling_supports_tools [Boolean] whether the sampling handler supports tool use
     #   (MCP 2025-11-25 / SEP-1577); declares the sampling.tools capability and forwards
     #   tools/toolChoice params to the handler instead of rejecting tool-enabled requests
@@ -58,14 +106,23 @@ module MCPClient
     #   structuredContent does not match the tool's declared outputSchema (MCP 2025-11-25:
     #   "Clients SHOULD validate structured results against this schema"): :warn (default)
     #   logs a warning, :strict raises MCPClient::Errors::ValidationError
+    # @param request_meta [Hash, #call, nil] metadata merged into every request's `_meta`
+    #   (a Hash, or a callable returning one, evaluated per request) — e.g. OpenTelemetry
+    #   trace context (`traceparent`, `tracestate`, `baggage`, MCP 2026-07-28) or
+    #   vendor-prefixed keys. Reserved protocol keys cannot be set this way.
+    # @param extensions [Array<String>, Hash{String => Hash}, nil] MCP 2026-07-28 extensions to declare
+    #   in every request's clientCapabilities (identifier, or identifier => settings), e.g.
+    #   `['io.modelcontextprotocol/tasks']` to let servers answer tools/call with a task
     def initialize(mcp_server_configs: [], logger: nil, elicitation_handler: nil, roots: nil, sampling_handler: nil,
-                   sampling_supports_tools: false, client_info: nil, validate_structured_content: :warn)
+                   sampling_supports_tools: false, client_info: nil, validate_structured_content: :warn,
+                   request_meta: nil, extensions: nil)
       unless STRUCTURED_CONTENT_MODES.include?(validate_structured_content)
         raise ArgumentError, "validate_structured_content must be one of #{STRUCTURED_CONTENT_MODES.inspect}, " \
                              "got #{validate_structured_content.inspect}"
       end
 
       @validate_structured_content = validate_structured_content
+      @extensions = normalize_extensions(extensions)
       # Preserve a caller-supplied logger's formatter (only tag progname), and
       # install the default formatter solely on a logger we create ourselves.
       # Overwriting the formatter of an application's logger would silently
@@ -83,6 +140,28 @@ module MCPClient
         MCPClient::ServerFactory.create(config, logger: @logger)
       end
       @tool_cache = {}
+      # Bumped whenever the tool cache is emptied, so a list_tools that was
+      # already in flight can tell that its definitions were superseded while
+      # it ran (MCP 2026-07-28: a HeaderMismatch refresh announces itself as a
+      # tools/list_changed).
+      @tool_cache_generation = 0
+      @cache_mutex = Mutex.new
+      # The effective-parameter fingerprint each server's slice of a list
+      # cache was filled under (MCP 2026-07-28 caching: a result is served
+      # only to a request that would carry the same parameters).
+      @cache_params = Hash.new { |h, k| h[k] = {}.compare_by_identity }
+      # Which servers have filled their slice of a list cache, so a snapshot
+      # is known to be complete however few items it holds: a server that
+      # legitimately lists nothing must be served from the cache too, not
+      # asked again on every call.
+      @cache_filled = {}
+      # One lock for the list caches and their parameter tags: a freshness
+      # check and the copy it approves are one snapshot, and the notification
+      # thread's clears wait for it.
+      @cache_mutex = Mutex.new
+      # Bumped by every write under @cache_mutex, so a freshness verdict
+      # reached outside the lock can be revalidated before a copy is served.
+      @cache_version = 0
       # Active progressToken -> callback registrations (MCP progress utility)
       @progress_callbacks = {}
       @progress_mutex = Mutex.new
@@ -92,28 +171,29 @@ module MCPClient
       @notification_listeners = []
       # Elicitation handler (MCP 2025-06-18)
       @elicitation_handler = elicitation_handler
-      # Sampling handler (MCP 2025-11-25)
+      # Sampling handler (MCP 2025-11-25; deprecated in 2026-07-28, SEP-2577)
       @sampling_handler = sampling_handler
+      MCPClient::Deprecations.warn(:sampling, @logger) if sampling_handler
       # Whether the sampling handler supports tool use (SEP-1577)
       @sampling_supports_tools = sampling_supports_tools
-      # Roots (MCP 2025-06-18)
+      # Roots (MCP 2025-06-18; deprecated in 2026-07-28, SEP-2577)
       @roots = normalize_roots(roots)
+      MCPClient::Deprecations.warn(:roots, @logger) unless @roots.empty?
       # Register default and user-defined notification handlers on each server
       @servers.each do |server|
-        # Host-provided Implementation info for the initialize clientInfo
-        server.client_info = client_info if client_info && server.respond_to?(:client_info=)
-        server.on_notification do |method, params|
-          # Default notification processing (e.g., cache invalidation, logging)
-          process_notification(server, method, params)
-          # Invoke user-defined listeners
-          @notification_listeners.each { |cb| cb.call(server, method, params) }
-        end
+        configure_server_identity(server, client_info, request_meta)
+        register_notification_handlers(server)
         # Register feature callbacks only for features the host actually
         # supports: transports derive their declared client capabilities from
         # the callbacks registered before connecting, and MCP forbids using
         # capabilities that were not negotiated.
+        # The transports call the callback with (request_id, params) only, so
+        # the asking server is closed over here: the URL-mode host contract
+        # depends on its protocol era (MCP 2026-07-28 removed elicitationId).
         if @elicitation_handler && server.respond_to?(:on_elicitation_request)
-          server.on_elicitation_request(&method(:handle_elicitation_request))
+          server.on_elicitation_request do |request_id, request_params|
+            handle_elicitation_request(request_id, request_params, server)
+          end
         end
         # The client always implements the roots feature (roots/list and
         # list_changed notifications), independent of the current roots list.
@@ -134,29 +214,14 @@ module MCPClient
     # @raise [MCPClient::Errors::ConnectionError] on authorization failures
     # @raise [MCPClient::Errors::PromptGetError] if no prompts could be retrieved from any server
     def list_prompts(cache: true)
-      return @prompt_cache.values if cache && !@prompt_cache.empty?
-
-      prompts = []
-      connection_errors = []
-
-      servers.each do |server|
-        server.list_prompts.each do |prompt|
-          cache_key = cache_key_for(server, prompt.name)
-          @prompt_cache[cache_key] = prompt
-          prompts << prompt
+      holding_request_meta('prompts/list') do
+        if cache && (snapshot = cached_snapshot(:prompts, @prompt_cache))
+          release_held_request_meta
+          return snapshot
         end
-      rescue MCPClient::Errors::ConnectionError => e
-        # Fast-fail on authorization errors for better user experience
-        # If this is the first server or we haven't collected any prompts yet,
-        # raise the auth error directly to avoid cascading error messages
-        raise e if e.message.include?('Authorization failed') && prompts.empty?
-
-        # Store the error and try other servers
-        connection_errors << e
-        @logger.error("Server error: #{e.message}")
-      end
 
-      prompts
+        collect_prompts_from_servers(cache)
+      end
     end
 
     # Gets a specific prompt by name with the given parameters
@@ -214,44 +279,24 @@ module MCPClient
     # @raise [MCPClient::Errors::ConnectionError] on authorization failures
     # @raise [MCPClient::Errors::ResourceReadError] if no resources could be retrieved from any server
     def list_resources(cache: true, cursor: nil)
-      # If cursor is provided, we can only query one server (the one that provided the cursor)
-      # This is a limitation of aggregating multiple servers
-      if cursor
-        # For now, just use the first server when cursor is provided
-        # In a real implementation, you'd need to track which server the cursor came from
-        return servers.first.list_resources(cursor: cursor) if servers.any?
-
-        return { 'resources' => [], 'nextCursor' => nil }
-      end
-
-      # Use cache if available and no cursor
-      return { 'resources' => @resource_cache.values, 'nextCursor' => nil } if cache && !@resource_cache.empty?
-
-      resources = []
-      connection_errors = []
-
-      servers.each do |server|
-        result = server.list_resources
-        resource_list = result['resources'] || []
+      holding_request_meta('resources/list') do
+        # If cursor is provided, we can only query one server (the one that provided the cursor)
+        # This is a limitation of aggregating multiple servers
+        if cursor
+          # For now, just use the first server when cursor is provided
+          return servers.first.list_resources(cursor: cursor) if servers.any?
+
+          return { 'resources' => [], 'nextCursor' => nil }
+        end
 
-        resource_list.each do |resource|
-          cache_key = cache_key_for(server, resource.uri)
-          @resource_cache[cache_key] = resource
-          resources << resource
+        # Use cache if available and no cursor
+        if cache && (snapshot = cached_snapshot(:resources, @resource_cache))
+          release_held_request_meta
+          return { 'resources' => snapshot, 'nextCursor' => nil }
         end
-      rescue MCPClient::Errors::ConnectionError => e
-        # Fast-fail on authorization errors for better user experience
-        # If this is the first server or we haven't collected any resources yet,
-        # raise the auth error directly to avoid cascading error messages
-        raise e if e.message.include?('Authorization failed') && resources.empty?
-
-        # Store the error and try other servers
-        connection_errors << e
-        @logger.error("Server error: #{e.message}")
-      end
 
-      # Return hash format consistent with server methods
-      { 'resources' => resources, 'nextCursor' => nil }
+        collect_resources_from_servers(cache)
+      end
     end
 
     # Reads a specific resource by URI
@@ -277,36 +322,14 @@ module MCPClient
     # @raise [MCPClient::Errors::ConnectionError] on authorization failures
     # @raise [MCPClient::Errors::ToolCallError] if no tools could be retrieved from any server
     def list_tools(cache: true)
-      return @tool_cache.values if cache && !@tool_cache.empty?
-
-      tools = []
-      connection_errors = []
-
-      servers.each do |server|
-        server.list_tools.each do |tool|
-          cache_key = cache_key_for(server, tool.name)
-          @tool_cache[cache_key] = tool
-          tools << tool
+      holding_request_meta('tools/list') do
+        if cache && (snapshot = cached_snapshot(:tools, @tool_cache))
+          release_held_request_meta
+          return snapshot
         end
-      rescue MCPClient::Errors::ConnectionError => e
-        # Fast-fail on authorization errors for better user experience
-        # If this is the first server or we haven't collected any tools yet,
-        # raise the auth error directly to avoid cascading error messages
-        raise e if e.message.include?('Authorization failed') && tools.empty?
-
-        # Store the error and try other servers
-        connection_errors << e
-        @logger.error("Server error: #{e.message}")
-      end
 
-      # If we didn't get any tools from any server but have servers configured, report failure
-      if tools.empty? && !servers.empty?
-        raise connection_errors.first if connection_errors.any?
-
-        @logger.warn('No tools found from any server.')
+        collect_tools_from_servers(cache)
       end
-
-      tools
     end
 
     # Calls a specific tool by name with the given parameters
@@ -314,6 +337,9 @@ module MCPClient
     # @param parameters [Hash] the parameters to pass to the tool
     # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
     # @return [Object] the result of the tool invocation
+    # @raise [MCPClient::Errors::ValidationError] when the parameters miss a
+    #   required property, or the tool's inputSchema declares a JSON Schema
+    #   dialect this client does not support (MCP 2026-07-28)
     def call_tool(tool_name, parameters, server: nil, progress: nil)
       tool = resolve_tool(tool_name, server: server)
 
@@ -329,20 +355,51 @@ module MCPClient
       # request _meta and route matching notifications/progress to the
       # caller's callback while the request is active.
       parameters, token = setup_progress_tracking(parameters, progress)
+      # The session the call is made in: a task it comes back as belongs to
+      # that session, not to one that replaced it while the answer was read.
+      # The call goes into that very session and no other — a transport that
+      # reconnects inside the request would otherwise run the tool in the
+      # replacement session while the task is stamped with the sampled one,
+      # and the wait would then refuse a task whose (possibly non-idempotent)
+      # tool has already run, inviting a duplicate retry.
+      task_epoch = tasks_extension? ? invocation_session_epoch(server) : nil
+
+      # The call and the re-resolve that follows it share one slot for the
+      # definition the transport's request goes out under, so a call that a
+      # notification listener nests inside this one cannot leave its own
+      # there.
+      with_called_tool_definition(server) do
+        result = begin
+          pinned_to_session(server, task_epoch) { server.call_tool(tool_name, parameters) }
+        rescue MCPClient::Errors::ConnectionError => e
+          # Add server identity information to the error for better context
+          server_id = server.name ? "#{server.class}[#{server.name}]" : server.class.name
+          raise MCPClient::Errors::ToolCallError,
+                "Error calling tool '#{tool_name}': #{e.message} (Server: #{server_id})"
+        ensure
+          # Tokens are only valid for the lifetime of the request: dropping the
+          # registration filters out stale post-completion notifications.
+          unregister_progress_callback(token) if token
+        end
 
-      result = begin
-        server.call_tool(tool_name, parameters)
-      rescue MCPClient::Errors::ConnectionError => e
-        # Add server identity information to the error for better context
-        server_id = server.name ? "#{server.class}[#{server.name}]" : server.class.name
-        raise MCPClient::Errors::ToolCallError, "Error calling tool '#{tool_name}': #{e.message} (Server: #{server_id})"
-      ensure
-        # Tokens are only valid for the lifetime of the request: dropping the
-        # registration filters out stale post-completion notifications.
-        unregister_progress_callback(token) if token
+        # MCP 2026-07-28 HeaderMismatch recovery re-derives a call's
+        # Mcp-Param-* headers from a refreshed tools/list, so the attempt that
+        # was answered may have gone out under a definition this client never
+        # resolved. Validate against that one -- never against the transport's
+        # current list, which a tools/list_changed racing the call may already
+        # have replaced with a definition the server never used. It is read
+        # here, before a task's result is waited for: a refresh that lands
+        # during a wait that may take minutes belongs to another invocation and
+        # says nothing about the definition this one was answered under.
+        called = called_tool_definition(server, tool_name)
+
+        # MCP 2026-07-28 tasks extension: the server may have turned the call
+        # into a task; drive it to its final result so the contract of this
+        # method does not change.
+        result = complete_task_result(tool_name, server, result, task_epoch)
+
+        validate_called_result!(called || tool, result)
       end
-
-      validate_structured_content!(tool, result)
     end
 
     # Convert MCP tools to OpenAI function specifications
@@ -375,14 +432,38 @@ module MCPClient
     # Clean up all server connections
     def cleanup
       servers.each(&:cleanup)
+      # The transports forgot their results; the slices built from them go too.
+      clear_cache
+      clear_task_states
     end
 
-    # Clear the cached tools so that next list_tools will fetch fresh data
+    # The list kinds this client caches, each with the transport-level cache
+    # behind it.
+    CACHED_LIST_KINDS = %i[tools prompts resources].freeze
+
+    # Clear the cached lists so that the next list_tools, list_prompts or
+    # list_resources fetches fresh data.
     # @return [void]
     def clear_cache
-      @tool_cache.clear
-      @prompt_cache.clear
-      @resource_cache.clear
+      clear_tool_cache
+      @cache_mutex.synchronize do
+        @cache_version += 1
+        @prompt_cache.clear
+        @resource_cache.clear
+        # A slice's tag goes with the slice: a leftover tag must not vouch
+        # for a server whose slice a later, partial refill never rebuilt.
+        @cache_params.clear
+        @cache_filled.clear
+      end
+      # The promise is fresh data, and a transport holding a list the server
+      # bounded with a positive `ttlMs` (MCP 2026-07-28
+      # server/utilities/caching) would answer the next listing from it
+      # without sending anything at all. Dropped outside this client's lock:
+      # each transport takes its own.
+      servers.each do |server|
+        CACHED_LIST_KINDS.each { |kind| refresh_server_cache(server, kind) }
+        forget_schema_checks
+      end
     end
 
     # Register a callback for JSON-RPC notifications from servers
@@ -392,11 +473,44 @@ module MCPClient
       @notification_listeners << block
     end
 
+    # Register the host's control over a multi round-trip request's
+    # out-of-band wait on every server (MCP 2026-07-28 client/elicitation
+    # "URL Mode": manual retry/cancel controls). See
+    # {MCPClient::JsonRpcCommon#on_input_required_wait} for the contract.
+    # @param block [Proc] callback that receives an InputRequiredWait
+    # @return [void]
+    def on_input_required_wait(&block)
+      @input_required_wait_handler = block
+      @servers.each do |server|
+        server.on_input_required_wait(&block) if server.respond_to?(:on_input_required_wait)
+      end
+    end
+
+    # Resume a multi round-trip request from the continuation an
+    # {MCPClient::Errors::InputRequiredError} carries, on the transport that
+    # raised it. The result is the transport's, as {#call_tool} would have
+    # returned it before validation.
+    # @param error [MCPClient::Errors::InputRequiredError] a resumable error
+    # @param timeout [Numeric, nil] per-request timeout for the resumed request
+    # @return [Object] the final (complete) result
+    # @raise [ArgumentError] if the error carries no continuation or names no transport
+    def resume_input_required(error, timeout: nil)
+      transport = error.respond_to?(:transport) ? error.transport : nil
+      raise ArgumentError, 'the error names no transport to resume on' unless transport
+
+      transport.resume_input_required(error, timeout: timeout)
+    end
+
     # Set the roots for this client (MCP 2025-06-18)
     # When roots are changed, a notification is sent to all connected servers
+    # @deprecated Roots are deprecated since MCP 2026-07-28 (SEP-2577);
+    #   earliest removal is the first revision released on or after
+    #   2027-07-28. Pass directories or files through tool parameters,
+    #   resource URIs or server configuration instead.
     # @param new_roots [Array<MCPClient::Root, Hash>] the new roots to set
     # @return [void]
     def roots=(new_roots)
+      MCPClient::Deprecations.warn(:roots, @logger)
       @roots = normalize_roots(new_roots)
       # Notify servers that roots have changed
       notify_roots_changed
@@ -457,8 +571,20 @@ module MCPClient
       raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless server
 
       begin
-        # Use the streaming API if it's available
-        server.call_tool_streaming(tool_name, parameters)
+        task_epoch = tasks_extension? ? invocation_session_epoch(server) : nil
+        # Use the streaming API if it's available, opened in the session the
+        # epoch was sampled for: a chunk that comes back as a task is stamped
+        # with that session, so the call must not have been written into the
+        # one that replaced it (see #call_tool). The stream every built-in
+        # transport hands back is lazy, so the call itself goes out under the
+        # pin the enumeration takes (see #streamed_call_chunks) — this one
+        # covers a transport that sends while building it.
+        stream = pinned_to_session(server, task_epoch) { server.call_tool_streaming(tool_name, parameters) }
+        # Every stream goes through the wrapper, whether or not tasks are in
+        # play: "Clients SHOULD validate structured results against this
+        # schema" is about a result, not about the method that fetched it, and
+        # so is the dialect a result's schema declares.
+        streamed_call_chunks(stream, tool, tool_name, server, epoch: task_epoch)
       rescue MCPClient::Errors::ConnectionError => e
         # Add server identity information to the error for better context
         server_id = server.name ? "#{server.class}[#{server.name}]" : server.class.name
@@ -526,171 +652,57 @@ module MCPClient
       srv.complete(ref: ref, argument: argument, context: context)
     end
 
-    # Call a tool as a task (task-augmented tools/call, MCP 2025-11-25).
-    #
-    # Instead of blocking for the result, the server accepts the request and
-    # immediately returns a task handle; the actual result is retrieved later
-    # via {#get_task_result} once the task reaches a terminal status. The server
-    # must advertise the tasks.requests.tools.call capability, and the tool must
-    # declare execution.taskSupport of 'optional' or 'required'.
-    # @param tool_name [String] the name of the tool to call
-    # @param parameters [Hash] the parameters to pass to the tool
-    # @param ttl [Integer, nil] optional requested task lifetime in milliseconds
-    # @param server [String, Symbol, Integer, MCPClient::ServerBase, nil] optional server to use
-    # @return [MCPClient::Task] the created task (status typically 'working')
-    # @raise [MCPClient::Errors::ToolNotFound] if the tool is not found
-    # @raise [MCPClient::Errors::ValidationError] if required parameters are missing
-    # @raise [MCPClient::Errors::TaskError] if the server or tool does not support tasks, or creation fails
-    def call_tool_as_task(tool_name, parameters, ttl: nil, server: nil)
-      tool = resolve_tool(tool_name, server: server)
-      validate_params!(tool, parameters)
-
-      srv = tool.server
-      raise MCPClient::Errors::ServerNotFound, "No server found for tool '#{tool_name}'" unless srv
-
-      unless server_supports_task_tool_call?(srv)
-        raise MCPClient::Errors::TaskError,
-              'Server does not support task-augmented tools/call (no tasks.requests.tools.call capability)'
-      end
-      unless tool.supports_task?
-        raise MCPClient::Errors::TaskError,
-              "Tool '#{tool_name}' does not support task execution (execution.taskSupport is forbidden/unset)"
-      end
-
-      task_params = {}
-      task_params[:ttl] = ttl if ttl
-      # Keep _meta (string or symbol key) as a top-level request field rather
-      # than a tool argument, so request metadata is preserved and does not fail
-      # tool input-schema validation.
-      meta_key = [:_meta, '_meta'].find { |k| parameters.key?(k) }
-      arguments = meta_key ? parameters.reject { |k, _| k == meta_key } : parameters
-      rpc_params = { name: tool_name, arguments: arguments, task: task_params }
-      rpc_params[:_meta] = parameters[meta_key] if meta_key
-
-      begin
-        result = srv.rpc_request('tools/call', rpc_params)
-        MCPClient::Task.from_create_result(result, server: srv)
-      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
-        raise MCPClient::Errors::TaskError, "Error creating task for tool '#{tool_name}': #{e.message}"
-      end
-    end
-
-    # Get the current state of a task (tasks/get, MCP 2025-11-25)
-    # @param task_id [String, MCPClient::Task] the task to query; passing the
-    #   Task handle returned by #call_tool_as_task routes to its own server
+    # Open a long-lived notification stream on a server (MCP 2026-07-28
+    # subscriptions/listen). The subscription's notifications also flow
+    # through the client's regular notification handling (cache
+    # invalidation, on_notification listeners).
+    # @param notifications [Hash] the SubscriptionFilter: tools_list_changed,
+    #   prompts_list_changed, resources_list_changed (booleans),
+    #   resource_subscriptions, task_ids (arrays of strings)
     # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [MCPClient::Task] the task with current status
-    # @raise [ArgumentError] if the server is ambiguous in a multi-server client
-    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
-    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
-    # @raise [MCPClient::Errors::TaskError] if retrieving the task fails
-    def get_task(task_id, server: nil)
-      srv = select_task_server(task_id, server, 'get_task')
-      task_id = task_identifier(task_id)
-
-      begin
-        result = srv.rpc_request('tasks/get', { taskId: task_id })
-        MCPClient::Task.from_json(result, server: srv)
-      rescue MCPClient::Errors::ServerError => e
-        raise task_error_from(e, task_id, 'getting')
-      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
-        raise MCPClient::Errors::TaskError, "Error getting task '#{task_id}': #{e.message}"
-      end
-    end
-
-    # Retrieve the result of a completed task (tasks/result, MCP 2025-11-25).
-    # Returns exactly what the underlying request would have returned (e.g. a
-    # CallToolResult hash with 'content'/'isError'/'structuredContent'); it is
-    # NOT wrapped in a Task. Blocks on the server until the task is terminal.
-    #
-    # NOTE: structured-content validation (see #validate_structured_content!)
-    # does not cover task-delivered results yet: a task ID alone does not
-    # identify which tool (and therefore which outputSchema) produced the
-    # result, and the client keeps no task-to-tool registry. Callers who need
-    # validation here can run MCPClient::SchemaValidator.validate themselves.
-    # @param task_id [String, MCPClient::Task] the task; passing the Task
-    #   handle returned by #call_tool_as_task routes to its own server
-    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [Object] the underlying task result
-    # @raise [ArgumentError] if the server is ambiguous in a multi-server client
-    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
-    # @raise [MCPClient::Errors::TaskError] if retrieval fails
-    def get_task_result(task_id, server: nil)
-      srv = select_task_server(task_id, server, 'get_task_result')
-      task_id = task_identifier(task_id)
-
-      begin
-        srv.rpc_request('tasks/result', { taskId: task_id })
-      rescue MCPClient::Errors::ServerError => e
-        raise task_error_from(e, task_id, 'getting result for')
-      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
-        raise MCPClient::Errors::TaskError, "Error getting result for task '#{task_id}': #{e.message}"
-      end
-    end
-
-    # List tasks known to a server (tasks/list, paginated, MCP 2025-11-25)
-    # @param cursor [String, nil] optional pagination cursor
-    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [Hash] { tasks: Array<MCPClient::Task>, next_cursor: String, nil }
-    # @raise [MCPClient::Errors::TaskError] if listing fails
-    def list_tasks(cursor: nil, server: nil)
+    # @param ack_timeout [Numeric, false, nil] seconds to wait for the server's
+    #   acknowledgment before giving the listen up and cancelling it; nil takes
+    #   the transport's own read timeout, false waits for ever
+    # @yield [method, params] notifications delivered on the subscription
+    # @return [MCPClient::Subscription]
+    # @raise [MCPClient::Errors::CapabilityError] if the server is not a 2026-07-28 server
+    def listen(notifications:, server: nil, ack_timeout: nil, &listener)
       srv = select_server(server)
-      ensure_task_capability!(srv, 'list')
-
-      params = cursor ? { cursor: cursor } : {}
-
-      begin
-        result = srv.rpc_request('tasks/list', params) || {}
-        tasks = (result['tasks'] || []).map { |t| MCPClient::Task.from_json(t, server: srv) }
-        { tasks: tasks, next_cursor: result['nextCursor'] }
-      rescue MCPClient::Errors::ServerError, MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
-        raise MCPClient::Errors::TaskError, "Error listing tasks: #{e.message}"
-      end
-    end
-
-    # Cancel a task (tasks/cancel, MCP 2025-11-25)
-    # @param task_id [String, MCPClient::Task] the task to cancel; passing the
-    #   Task handle returned by #call_tool_as_task routes to its own server
-    # @param server [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
-    # @return [MCPClient::Task] the task with updated (cancelled) status
-    # @raise [ArgumentError] if the server is ambiguous in a multi-server client
-    # @raise [MCPClient::Errors::ServerNotFound] if no server is available
-    # @raise [MCPClient::Errors::TaskNotFound] if the task does not exist
-    # @raise [MCPClient::Errors::TaskError] if cancellation fails (including cancelling a terminal task)
-    def cancel_task(task_id, server: nil)
-      srv = select_task_server(task_id, server, 'cancel_task')
-      task_id = task_identifier(task_id)
-      ensure_task_capability!(srv, 'cancel')
-
-      begin
-        result = srv.rpc_request('tasks/cancel', { taskId: task_id })
-        MCPClient::Task.from_json(result, server: srv)
-      rescue MCPClient::Errors::ServerError => e
-        # A terminal task cannot be cancelled (-32602); that is an error, not a
-        # missing task, so keep it as a TaskError.
-        if e.message.match?(/terminal/i)
-          raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+      filter = MCPClient::Subscription.normalize_filter(notifications)
+      if filter.key?('taskIds')
+        unless tasks_extension?
+          raise MCPClient::Errors::CapabilityError,
+                'Task notifications (taskIds) require the tasks extension: pass ' \
+                "extensions: ['#{MCPClient::JsonRpcCommon::TASKS_EXTENSION}'] to MCPClient::Client.new"
         end
-
-        raise task_error_from(e, task_id, 'cancelling')
-      rescue MCPClient::Errors::TransportError, MCPClient::Errors::ConnectionError => e
-        raise MCPClient::Errors::TaskError, "Error cancelling task '#{task_id}': #{e.message}"
+        # The server must have negotiated the extension too (it answers a
+        # taskIds filter from a non-declaring client with -32021).
+        ensure_task_capability!(srv, 'listen')
       end
+
+      srv.listen(notifications: notifications, ack_timeout: ack_timeout, &listener)
     end
 
     # Set the logging level on all connected servers (MCP 2025-06-18)
     # To set on a specific server, use: client.find_server('name').log_level = 'debug'
+    # @deprecated Logging is deprecated since MCP 2026-07-28 (SEP-2577);
+    #   earliest removal is the first revision released on or after
+    #   2027-07-28. Have the server log to stderr (stdio) or use
+    #   OpenTelemetry instead.
     # @param level [String] the log level ('debug', 'info', 'notice', 'warning', 'error',
     #   'critical', 'alert', 'emergency')
     # @return [Array<Hash>] results from servers
     # @raise [MCPClient::Errors::ServerError] if server returns an error
     def log_level=(level)
+      MCPClient::Deprecations.warn(:logging, @logger)
       @servers.filter_map do |srv|
         # MCP lifecycle: only use capabilities that were successfully
         # negotiated — skip servers whose NEGOTIATED set lacks logging.
         # Unconnected servers proceed: the transport-level gate re-checks
-        # after its handshake establishes the capability set.
-        unless !capabilities_known?(srv) || srv.capability?('logging')
+        # after its handshake establishes the capability set. A 2026-07-28
+        # server needs no capability at all: the level is a per-request
+        # field of every request's _meta, not a logging/setLevel call.
+        unless !capabilities_known?(srv) || srv.capability?('logging') || modern_server?(srv)
           @logger.debug("Skipping logging/setLevel for #{srv.name || srv.class.name}: " \
                         'logging capability not negotiated')
           next
@@ -702,85 +714,129 @@ module MCPClient
 
     private
 
-    # Whether the server's negotiated capability set is available yet.
-    # @param srv [MCPClient::ServerBase] the server
-    # @return [Boolean]
-    def capabilities_known?(srv)
-      srv.respond_to?(:capabilities) && !srv.capabilities.nil?
-    end
-
-    # Enforce the tasks.<operation> capability gate for a server (MCP
-    # lifecycle: "Only use capabilities that were successfully negotiated").
-    # When the negotiated capability set is not yet known, first trigger the
-    # handshake with a cheap standard request (ping) and then re-apply the
-    # gate against the freshly negotiated set, so a previously uninitialized
-    # server that negotiates no tasks capability never receives the
-    # prohibited request.
-    # @param srv [MCPClient::ServerBase] the selected server
-    # @param operation [String] the tasks sub-capability ('list' or 'cancel')
-    # @return [void]
-    # @raise [MCPClient::Errors::CapabilityError] if the negotiated set lacks the capability
-    def ensure_task_capability!(srv, operation)
-      if !capabilities_known?(srv) && srv.respond_to?(:ping)
-        begin
-          srv.ping
-        rescue MCPClient::Errors::MCPError
-          # Initialization failed; fall through and let the task request
-          # itself surface the failure via the normal error path.
+    # The chunks of a streaming tools/call, still in the session the call was
+    # sampled for.
+    #
+    # Every built-in transport answers call_tool_streaming with a lazy
+    # Enumerator: nothing is sent until the host enumerates it, and the pin
+    # around the construction is long gone by then (pins are per thread, and
+    # the consumer may not even be the thread that opened the stream). The
+    # call is therefore made under a pin taken inside the enumeration itself,
+    # so a session that ended meanwhile stops the call at the wire instead of
+    # running a (possibly non-idempotent) tool in the session that replaced
+    # the sampled one — where the task it answers with would be stamped with
+    # a session it never belonged to, and the wait would refuse the very task
+    # that ran.
+    # @param stream [Enumerator] the transport's lazy stream
+    # @param tool [MCPClient::Tool] the definition the call was validated against
+    # @param epoch [Integer, nil] the session the call belongs to
+    # @return [Enumerator]
+    def streamed_call_chunks(stream, tool, tool_name, server, epoch:)
+      resolve = tasks_extension? && modern_server?(server)
+      Enumerator.new do |yielder|
+        pinned_to_session(server, epoch) do
+          # The call and the re-resolve that follows it share one slot for the
+          # definition the request went out under (see #call_tool). The call
+          # happens inside this enumeration, so the slot is opened here:
+          # without it the transport's record dies with its own call_tool and
+          # the re-resolve would list again, validating the result against a
+          # definition newer than the one the call carried.
+          with_called_tool_definition(server) do
+            called = nil
+            read_called = false
+            stream.each do |chunk|
+              # MCP 2026-07-28 tasks extension: a chunk may be a task; resolve
+              # it to the call's result, validated as #call_tool does — against
+              # the definition a mid-stream refresh (HeaderMismatch recovery)
+              # may have replaced.
+              task = resolve && task_result?(chunk)
+              # A chunk that is neither a task nor a complete CallToolResult is
+              # progress, not an answer: only a result is checked against the
+              # tool's outputSchema.
+              next yielder << chunk unless task || complete_call_result?(chunk)
+
+              # The definition the stream's one request went out under, read
+              # before a task is waited for (see #call_tool) and read once:
+              # every chunk belongs to that same request, and the record
+              # describes it rather than whatever the list holds later.
+              unless read_called
+                called = called_tool_definition(server, tool_name)
+                read_called = true
+              end
+              result = task ? complete_task_result(tool_name, server, chunk, epoch) : chunk
+              yielder << validate_called_result!(called || tool, result)
+            end
+          end
         end
       end
+    end
 
-      return if !capabilities_known?(srv) || srv.capability?('tasks', operation)
+    # Whether a streamed chunk is the call's answer rather than an update on
+    # its way. MCP 2026-07-28 makes `resultType` required and has clients
+    # treat an absent one as "complete" — a rule for *results*, which is
+    # what every pre-2026 server sends. A chunk that carries no `resultType`
+    # and is shaped as no CallToolResult (a progress object, say) is an
+    # update on the way, not an answer to check against an output schema.
+    # @param chunk [Object] one chunk of a streaming tools/call
+    # @return [Boolean]
+    def complete_call_result?(chunk)
+      return false unless chunk.is_a?(Hash) && MCPClient::JsonRpcCommon.result_type(chunk) == 'complete'
 
-      raise MCPClient::Errors::CapabilityError,
-            "Server #{srv.name || srv.class.name} did not declare the tasks.#{operation} capability"
+      # The members a CallToolResult is made of; a chunk carrying none of
+      # them (and no `resultType`) is not a result at all.
+      chunk.key?('resultType') || chunk.key?(:resultType) ||
+        %w[content structuredContent isError].any? { |member| chunk.key?(member) || chunk.key?(member.to_sym) }
     end
 
-    # Process incoming JSON-RPC notifications with default handlers
-    # @param server [MCPClient::ServerBase] the server that emitted the notification
-    # @param method [String] JSON-RPC notification method
-    # @param params [Hash] parameters for the notification
+    # Hand the host's identity and request metadata to a transport.
+    # @param server [MCPClient::ServerBase] the transport
+    # @param client_info [Hash, nil] Implementation info sent as clientInfo
+    # @param request_meta [Hash, #call, nil] metadata merged into every request's _meta
     # @return [void]
-    def process_notification(server, method, params)
-      server_id = server.name ? "#{server.class}[#{server.name}]" : server.class
-      case method
-      when 'notifications/tools/list_changed'
-        logger.warn("[#{server_id}] Tool list has changed, clearing tool cache")
-        @tool_cache.clear
-      when 'notifications/resources/updated'
-        logger.warn("[#{server_id}] Resource #{params['uri']} updated")
-      when 'notifications/prompts/list_changed'
-        logger.warn("[#{server_id}] Prompt list has changed, clearing prompt cache")
-        @prompt_cache.clear
-      when 'notifications/resources/list_changed'
-        logger.warn("[#{server_id}] Resource list has changed, clearing resource cache")
-        @resource_cache.clear
-      when 'notifications/message'
-        # MCP 2025-06-18: Handle logging messages from server
-        handle_log_message(server_id, params)
-      when 'notifications/tasks/status'
-        # MCP 2025-11-25: task status update (params are a flat Task)
-        handle_task_status_notification(server_id, params)
-      when 'notifications/cancelled'
-        # MCP 2025-11-25 cancellation utility: the server cancelled one of its
-        # own in-flight requests (sampling/elicitation). Server-request
-        # dispatch is synchronous per transport, so by the time this arrives
-        # the handler has usually completed; receivers MAY ignore
-        # cancellations they cannot honor — log for observability.
-        logger.debug("[#{server_id}] Server cancelled request #{params&.dig('requestId')}: " \
-                     "#{params&.dig('reason') || 'no reason given'}")
-      when 'notifications/progress'
-        handle_progress_notification(server_id, params)
+    def configure_server_identity(server, client_info, request_meta)
+      # Host-provided Implementation info for clientInfo (initialize on
+      # legacy servers, per-request _meta on modern ones)
+      server.client_info = client_info if client_info && server.respond_to?(:client_info=)
+      server.request_meta = request_meta if request_meta && server.respond_to?(:request_meta=)
+      return if @extensions.empty? || !server.respond_to?(:declare_extension)
+
+      @extensions.each { |identifier, settings| server.declare_extension(identifier, settings) }
+    end
+
+    # @param extensions [Array, Hash, nil] the extensions option
+    # @return [Hash{String => Hash}] identifier => settings
+    def normalize_extensions(extensions)
+      case extensions
+      when nil then {}
+      when Hash then extensions.to_h { |identifier, settings| [identifier.to_s, settings || {}] }
+      when Array then extensions.to_h { |identifier| [identifier.to_s, {}] }
       else
-        # Log unknown notification types for debugging purposes
-        logger.debug("[#{server_id}] Received unknown notification: #{method} - #{params}")
+        raise ArgumentError, 'extensions must be an Array of identifiers or a Hash of identifier => settings, ' \
+                             "got #{extensions.class}"
       end
     end
 
-    # Handle logging message notification from server (MCP 2025-06-18)
-    # @param server_id [String] server identifier for log prefix
-    # @param params [Hash] log message params (level, logger, data)
-    # @return [void]
+    # @param srv [MCPClient::ServerBase]
+    # @return [Boolean] whether the server negotiated an MCP 2026-07-28 revision
+    def modern_server?(srv)
+      srv.respond_to?(:modern?) && srv.modern?
+    end
+
+    # Whether the server's negotiated capability set is available yet.
+    # @param srv [MCPClient::ServerBase] the server
+    # @return [Boolean]
+    def capabilities_known?(srv)
+      srv.respond_to?(:capabilities) && !srv.capabilities.nil?
+    end
+
+    # @param mark [Array, nil] what the invalidation hook left behind
+    # @param server [MCPClient::ServerBase] the transport routing now
+    # @param method [String] the notification being routed
+    # @return [Boolean] whether the mark is this notification's
+    def mark_covers?(mark, server, method)
+      mark.is_a?(Array) && mark[0].equal?(server) && mark[1] == method
+    end
+
     # Route a notifications/progress message to the callback registered for
     # its progressToken; unknown or stale tokens are debug-logged and dropped
     # (MCP: "Senders and receivers SHOULD track active progress tokens").
@@ -841,7 +897,12 @@ module MCPClient
       @progress_mutex.synchronize { @progress_callbacks.delete(token) }
     end
 
+    # Handle logging message notification from server (MCP 2025-06-18)
+    # @param server_id [String] server identifier for log prefix
+    # @param params [Hash] log message params (level, logger, data)
+    # @return [void]
     def handle_log_message(server_id, params)
+      MCPClient::Deprecations.warn(:logging, @logger)
       level = params['level'] || 'info'
       logger_name = params['logger']
       data = params['data']
@@ -875,7 +936,7 @@ module MCPClient
     # @param text [String] the peer-supplied text
     # @return [String] sanitized, length-bounded text
     def sanitize_peer_log_text(text)
-      escaped = text.gsub(/[-]/) { |c| format('\\x%02X', c.ord) }
+      escaped = text.gsub(/[\x00-\x1F\x7F]/) { |c| format('\\x%02X', c.ord) }
       return escaped if escaped.length <= MAX_PEER_LOG_MESSAGE_LENGTH
 
       "#{escaped[0, MAX_PEER_LOG_MESSAGE_LENGTH]}... (truncated from #{escaped.length} chars)"
@@ -897,40 +958,6 @@ module MCPClient
       end
     end
 
-    # Resolve which server a task operation targets.
-    #
-    # Task IDs are only unique within the server that issued them, so silently
-    # defaulting to the first configured server can poll, read or cancel an
-    # unrelated task on the wrong server. Resolution order:
-    #   1. an explicit server: argument wins;
-    #   2. a Task handle carries the server that issued it;
-    #   3. a bare ID with exactly one configured server is unambiguous;
-    #   4. anything else is ambiguous and fails closed.
-    # @param task [String, MCPClient::Task] the task or its ID
-    # @param server_arg [Integer, String, Symbol, MCPClient::ServerBase, nil] explicit selector
-    # @param operation [String] calling method name, for the error message
-    # @return [MCPClient::ServerBase]
-    # @raise [ArgumentError] when the target server cannot be determined
-    def select_task_server(task, server_arg, operation)
-      # nil, not falsiness: `server: false` is an invalid selector that
-      # select_server rejects with ArgumentError, and treating it as "omitted"
-      # would silently route a read or a cancel somewhere instead of failing.
-      return select_server(server_arg) unless server_arg.nil?
-      return task.server if task.is_a?(MCPClient::Task) && task.server
-      return select_server(nil) if @servers.size <= 1
-
-      raise ArgumentError,
-            "#{operation} is ambiguous with multiple servers configured: task IDs are only unique per server. " \
-            'Pass the Task returned by call_tool_as_task, or name the server explicitly ' \
-            "(e.g. #{operation}(id, server: 'name'))."
-    end
-
-    # @param task [String, MCPClient::Task] a task or its ID
-    # @return [String] the task ID
-    def task_identifier(task)
-      task.is_a?(MCPClient::Task) ? task.task_id : task
-    end
-
     # Select a server based on index, name, type, or instance
     # @param server_arg [Integer, String, Symbol, MCPClient::ServerBase, nil] server selector
     # @return [MCPClient::ServerBase]
@@ -963,26 +990,42 @@ module MCPClient
       end
     end
 
-    # Validate parameters against tool JSON schema (checks required properties)
+    # Validate parameters against tool JSON schema (checks required
+    # properties, through the root's `$ref` chain and `allOf` members). A
+    # schema declaring a dialect this client does not implement is refused
+    # outright, so the call is never sent under a schema nothing could read.
     # @param tool [MCPClient::Tool] tool definition with schema
     # @param parameters [Hash] parameters to validate
-    # @raise [MCPClient::Errors::ValidationError] when required params are missing
+    # @raise [MCPClient::Errors::ValidationError] when required params are
+    #   missing, or the schema's dialect is not supported
     def validate_params!(tool, parameters)
       schema = tool.schema
+      state = input_schema_state(tool)
+      reject_unsupported_dialect!(tool, state, 'input')
+      # An output schema nothing here could read is refused before the call
+      # too: the dialect error is due whatever the tool would answer, and a
+      # (possibly destructive) tool is not run for a result that cannot be
+      # checked.
+      reject_unsupported_dialect!(tool, output_schema_state(tool), 'output')
+      # An input schema the validator cannot interpret asserts nothing: the
+      # call goes out and the server judges its arguments.
+      return if state[:unusable]
       return unless schema.is_a?(Hash)
 
-      required = schema['required'] || schema[:required]
-      return unless required.is_a?(Array)
-
-      properties = schema['properties'] || schema[:properties] || {}
+      # What the schema requires through every applicator that applies
+      # unconditionally: the root, its `$ref` chain, its `allOf` members (the
+      # tools spec: clients SHOULD follow `$ref` resolution when validating
+      # tool inputs). A conditional branch is the server's to judge.
+      required, properties = MCPClient::SchemaValidator.input_requirements(schema)
+      return if required.empty?
 
-      missing = required.map(&:to_s) - parameters.keys.map(&:to_s)
+      missing = required - parameters.keys.map(&:to_s)
 
       # Exclude required params that have a default value in the schema,
       # since the server will apply the default.
       missing = missing.reject do |param|
-        prop = properties[param] || properties[param.to_sym]
-        prop.is_a?(Hash) && (prop.key?('default') || prop.key?(:default))
+        prop = properties[param]
+        prop.is_a?(Hash) && prop.key?('default')
       end
 
       return unless missing.any?
@@ -990,12 +1033,19 @@ module MCPClient
       raise MCPClient::Errors::ValidationError, "Missing required parameters: #{missing.join(', ')}"
     end
 
+    # @param result [Hash] a tool result
+    # @return [Symbol, String, nil] the key its structuredContent sits under
+    def structured_content_key(result)
+      [:structuredContent, 'structuredContent'].find { |k| result.key?(k) }
+    end
+
     # Validate a tools/call result's structuredContent against the tool's
     # declared outputSchema (MCP 2025-11-25 server/tools spec: "Clients SHOULD
     # validate structured results against this schema"; a tool declaring an
     # outputSchema must return structuredContent in successful results). Error
-    # results (isError: true) are exempt: the conformance requirements apply to
-    # successful results only. Validation covers the common JSON Schema
+    # results (isError: true) and unfinished ones (resultType
+    # "input_required") are exempt: the conformance requirements apply to
+    # successful, finished results only. Validation covers the common JSON Schema
     # keywords; the full 2020-12 vocabulary is out of scope (see
     # MCPClient::SchemaValidator), and when the schema uses keywords outside
     # that subset a partial-coverage warning is logged in both modes so :strict
@@ -1009,42 +1059,222 @@ module MCPClient
     #   is missing from a successful result or does not match the schema
     def validate_structured_content!(tool, result)
       return result unless tool.structured_output? && result.is_a?(Hash)
-      return result if result['isError'] || result[:isError]
-
-      warn_partial_schema_coverage(tool)
 
-      structured = result.key?('structuredContent') ? result['structuredContent'] : result[:structuredContent]
-      if structured.nil?
+      # A dialect this client cannot read is an error for every result, an
+      # error result included (the MUST is not limited to successful ones).
+      reject_unsupported_dialect!(tool, output_schema_state(tool), 'output')
+      # An error result may carry no structuredContent at all; one that does
+      # is bound by the output schema like any other (the tools specification
+      # exempts nothing about error results), so what is there is checked.
+      return result if (result['isError'] || result[:isError]) && !structured_content_key(result)
+      # An unfinished result (MCP 2026-07-28 resultType "input_required") is
+      # not a successful one either: it carries the continuation instead of
+      # the tool's output. Checking it for structuredContent would fail the
+      # call on a conformance rule that does not apply yet, and would throw
+      # the continuation away with it.
+      return result unless MCPClient::JsonRpcCommon.result_type(result) == 'complete'
+
+      unsupported = warn_partial_schema_coverage(tool)
+      reject_partial_schema_coverage!(tool, unsupported)
+
+      # MCP 2026-07-28: structuredContent "can be any JSON value (object,
+      # array, string, number, boolean, or null)", so presence is decided by
+      # the key, not by the value. MCP 2025-11-25 types it as an object, so on
+      # a session negotiated to that revision anything else — a null, an
+      # array, a string, a number, a boolean — is what it was there: no
+      # structured content at all. The widening is a 2026-07-28 rule and does
+      # not reach back over a legacy session.
+      key = structured_content_key(result)
+      key = nil if key && !result[key].is_a?(Hash) && legacy_server?(tool.server)
+      # Dropping the non-object leaves an error result what it was: one
+      # carrying no structured content, which it is allowed to be. Reporting
+      # it as a successful result missing its output would refuse — in
+      # :strict, raise on — a result the tools specification permits.
+      return result if key.nil? && (result['isError'] || result[:isError])
+
+      unless key
         handle_structured_content_violation(
-          "Tool '#{tool.name}' declares an output schema but its successful result carries no structuredContent " \
-          '(required by the MCP 2025-11-25 tools spec)'
+          "Tool '#{sanitize_peer_log_text(tool.name.to_s)}' declares an output schema but its successful result " \
+          'carries no structuredContent (required by the MCP tools spec)'
         )
         return result
       end
 
-      errors = MCPClient::SchemaValidator.validate(structured, tool.output_schema)
+      # An unusable output schema (unsupported dialect, external $ref, out of
+      # bounds) is a violation too, never a permissive pass.
+      errors = MCPClient::SchemaValidator.validate(result[key], tool.output_schema)
       unless errors.empty?
+        # Schema and data text is peer-controlled: it is sanitized and
+        # bounded before it reaches a log line or an exception.
         handle_structured_content_violation(
-          "Structured content for tool '#{tool.name}' does not match its output schema: #{errors.join('; ')}"
+          "Structured content for tool '#{sanitize_peer_log_text(tool.name.to_s)}' does not match its output " \
+          "schema: #{sanitize_peer_log_text(errors.join('; '))[0, MAX_VIOLATION_TEXT]}"
         )
       end
       result
     end
 
+    # What the preflight made of a tool's inputSchema, checked once per tool
+    # definition. A schema the validator cannot use is warned about (MCP
+    # 2026-07-28: an unsupported dialect, a network `$ref` that is never
+    # dereferenced, or a schema beyond the resource bounds); for everything
+    # but an unsupported dialect the call still goes out — the server owns
+    # argument validation — and the host learns that local parameter checks
+    # are incomplete.
+    # @param tool [MCPClient::Tool]
+    # @return [Hash] :unusable and the :dialect that is not supported, if any
+    def input_schema_state(tool)
+      return {} if tool.schema.nil?
+
+      # Keyed by the definition's identity as well, so a refreshed tool
+      # definition (list_changed, cache expiry, HeaderMismatch recovery) is
+      # re-checked while the copies the client cache hands out are not. The
+      # identity, not the schema's hash: hashing a peer-supplied document
+      # walks it whole (or overflows the stack) before the bounded check
+      # could reject it.
+      @input_schema_warnings ||= {}
+      key = [tool.server&.object_id, tool.name]
+      known = @input_schema_warnings[key]
+      return known if known && known[:identity].equal?(tool_definition_identity(tool))
+
+      preflight = {}
+      problems = MCPClient::SchemaValidator.check_schema(tool.schema, preflight)
+      state = { identity: tool_definition_identity(tool), unusable: !problems.empty?,
+                dialect: preflight[:unsupported_dialect] }
+      @input_schema_warnings[key] = state
+      warn_unusable_input_schema(tool, problems)
+      state
+    end
+
+    # @param problems [Array<String>] why the input schema is unusable
+    # @return [void]
+    def warn_unusable_input_schema(tool, problems)
+      return if problems.empty?
+
+      @logger.warn("Tool '#{sanitize_peer_log_text(tool.name.to_s)}' input schema is not usable for validation: " \
+                   "#{sanitize_peer_log_text(problems.join('; '))}")
+    end
+
+    # MCP 2026-07-28 basic "Implementation Requirements": a client "MUST
+    # handle unsupported dialects gracefully by returning an appropriate
+    # error indicating the dialect is not supported". A dialect this client
+    # does not implement is not a schema it may quietly skip — it cannot
+    # know what the arguments must look like, and the caller must be able to
+    # see that — so the call is refused before it is sent. SEP-2106 assigns
+    # no JSON-RPC code to this, so it is a library error, not a wire one.
+    # The requirement is not conditional on the structured-content mode: a
+    # dialect the client cannot read is not a result it may choose to only
+    # log, on an input schema or on an output one.
+    # @param state [Hash] the memoized preflight state
+    # @param kind [String] which schema the dialect was declared on
+    # @return [void]
+    # @raise [MCPClient::Errors::ValidationError] when the dialect is unsupported
+    def reject_unsupported_dialect!(tool, state, kind)
+      dialect = state[:dialect]
+      return unless dialect
+
+      raise MCPClient::Errors::ValidationError,
+            "Tool '#{sanitize_peer_log_text(tool.name.to_s)}' #{kind} schema declares the JSON Schema dialect " \
+            "#{sanitize_peer_log_text(dialect.inspect)[0, MAX_VIOLATION_TEXT]}: that dialect is not supported " \
+            "(supported: #{MCPClient::SchemaValidator::SUPPORTED_DIALECTS.join(', ')})"
+    end
+
+    # What the preflight made of a tool's outputSchema, checked once per
+    # definition (keyed like {#input_schema_state}). Only the dialect is kept:
+    # every other reason the schema is unusable is reported through
+    # {#handle_structured_content_violation}, which the host's mode decides.
+    # @param tool [MCPClient::Tool]
+    # @return [Hash] the :dialect that is not supported, if any
+    def output_schema_state(tool)
+      return {} if tool.output_schema.nil?
+
+      @output_schema_dialects ||= {}
+      key = [tool.server&.object_id, tool.name]
+      known = @output_schema_dialects[key]
+      return known if known && known[:identity].equal?(tool_definition_identity(tool))
+
+      preflight = {}
+      MCPClient::SchemaValidator.check_schema(tool.output_schema, preflight)
+      @output_schema_dialects[key] = { identity: tool_definition_identity(tool),
+                                       dialect: preflight[:unsupported_dialect] }
+    end
+
+    # Validate the result of a call against the definition the request that
+    # was answered actually went out under. A transport's HeaderMismatch
+    # recovery re-derives a call's Mcp-Param-* headers from a refreshed
+    # tools/list, so the attempt that came back may carry an input schema
+    # this client never resolved — and {#validate_params!} refused the
+    # dialect of the definition the call was prepared from, not of the one it
+    # was sent under.
+    # @param tool [MCPClient::Tool] the answering definition
+    # @param result [Object] the raw tools/call result
+    # @return [Object] the result, unchanged
+    # @raise [MCPClient::Errors::ValidationError]
+    def validate_called_result!(tool, result)
+      reject_unsupported_dialect!(tool, input_schema_state(tool), 'input')
+      validate_structured_content!(tool, result)
+    end
+
+    # @param srv [MCPClient::ServerBase] the transport
+    # @return [Boolean] whether the session was negotiated to a revision
+    #   before 2026-07-28 (a transport that cannot say is not assumed legacy)
+    def legacy_server?(srv)
+      !srv.nil? && srv.respond_to?(:modern?) && srv.modern? == false
+    end
+
+    # The token naming a tool definition ({MCPClient::Tool#schema_identity});
+    # a tool-like object without one is identified by itself.
+    # @param tool [MCPClient::Tool, Object]
+    # @return [Object]
+    def tool_definition_identity(tool)
+      tool.respond_to?(:schema_identity) ? tool.schema_identity : tool
+    end
+
     # Warn (in both :warn and :strict modes) when a tool's output schema uses
     # JSON Schema keywords the built-in validator cannot evaluate, so partial
-    # coverage is never silent.
+    # coverage is never silent. The schema is scanned once per definition
+    # (keyed like {#warn_unusable_input_schema}), not on every result.
     # @param tool [MCPClient::Tool] the tool whose output schema is being used
-    # @return [void]
+    # @return [Array<String>] the unsupported keywords the schema uses
     def warn_partial_schema_coverage(tool)
+      @output_schema_coverage ||= {}
+      key = [tool.server&.object_id, tool.name]
+      known = @output_schema_coverage[key]
+      return known[:unsupported] if known && known[:identity].equal?(tool_definition_identity(tool))
+
       unsupported = MCPClient::SchemaValidator.unsupported_keywords(tool.output_schema)
-      return if unsupported.empty?
+      @output_schema_coverage[key] = { identity: tool_definition_identity(tool), unsupported: unsupported }
+      return unsupported if unsupported.empty?
 
       @logger.warn(
-        "Structured content check for tool '#{tool.name}': validation is partial: schema uses unsupported " \
+        "Structured content check for tool '#{sanitize_peer_log_text(tool.name.to_s)}': validation is partial: " \
+        'schema uses unsupported ' \
         "keywords: #{unsupported.join(', ')} (full JSON Schema 2020-12 evaluation is not implemented, so " \
         'conforming-looking data may still violate the schema)'
       )
+      unsupported
+    end
+
+    # :strict is a gate. A schema using an assertion this validator does not
+    # evaluate (a dynamic reference only the evaluation path could bind) cannot
+    # be shown to accept the result, and a result not shown to conform is
+    # refused there — a warning beside a returned value was a silent pass in
+    # everything but the log. A keyword that only annotates (`format`,
+    # `contentSchema`) decides nothing and does not refuse.
+    # @param tool [MCPClient::Tool] the tool whose output schema is being used
+    # @param unsupported [Array<String>] what {#warn_partial_schema_coverage} found
+    # @return [void]
+    # @raise [MCPClient::Errors::ValidationError] in :strict mode
+    def reject_partial_schema_coverage!(tool, unsupported)
+      return unless @validate_structured_content == :strict
+
+      assertions = unsupported - MCPClient::SchemaValidator::ANNOTATION_KEYWORDS
+      return if assertions.empty?
+
+      raise MCPClient::Errors::ValidationError,
+            "Structured content for tool '#{sanitize_peer_log_text(tool.name.to_s)}' cannot be checked against " \
+            'its output schema: the schema uses keywords this validator does not evaluate ' \
+            "(#{assertions.join(', ')}), so the result is not shown to conform"
     end
 
     # Log a structured-content conformance violation and, in :strict mode,
@@ -1095,60 +1325,55 @@ module MCPClient
       matching_tools.first
     end
 
-    # Reject a plain (synchronous) call for a tool whose execution.taskSupport is
-    # 'required'. A compliant server would reject a non-task-augmented tools/call
-    # for such a tool, so fail fast and point the caller at call_tool_as_task.
-    # @param tool [MCPClient::Tool] the resolved tool
-    # @param tool_name [String] the tool name (for the message)
-    # @raise [MCPClient::Errors::ToolCallError] if the tool requires task execution
-    def reject_task_required!(tool, tool_name)
-      # Tasks Tool-Level Negotiation rule 1: without tasks.requests.tools.call
-      # in the server capabilities, taskSupport is disregarded entirely and
-      # the tool is invoked as a plain call.
-      return unless tool.task_required? && server_supports_task_tool_call?(tool.server)
-
-      raise MCPClient::Errors::ToolCallError,
-            "Tool '#{tool_name}' requires task-augmented execution; call it with call_tool_as_task instead"
-    end
-
-    # Whether a server advertised support for task-augmented tools/call, i.e.
-    # capabilities.tasks.requests.tools.call.
-    # @param srv [MCPClient::ServerBase] the server
-    # @return [Boolean]
-    def server_supports_task_tool_call?(srv)
-      caps = srv.respond_to?(:capabilities) ? srv.capabilities : nil
-      return false unless caps.is_a?(Hash)
-
-      tasks = caps['tasks'] || caps[:tasks]
-      requests = tasks && (tasks['requests'] || tasks[:requests])
-      tools = requests && (requests['tools'] || requests[:tools])
-      call = tools && (tools['call'] || tools[:call])
-      !call.nil?
-    end
-
-    # Map a ServerError from a task operation to TaskNotFound or TaskError.
-    # @param error [MCPClient::Errors::ServerError] the server error
-    # @param task_id [String] the task id
-    # @param action [String] a verb phrase for the error message (e.g. 'getting')
-    # @return [MCPClient::Errors::TaskNotFound, MCPClient::Errors::TaskError]
-    def task_error_from(error, task_id, action)
-      if error.message.match?(/not found|unknown task|expired/i)
-        return MCPClient::Errors::TaskNotFound.new("Task '#{task_id}' not found")
+    # Empty the tool cache and move its generation on, so a list_tools that
+    # is already fetching does not put the emptied definitions back.
+    # @return [void]
+    def clear_tool_cache
+      @cache_mutex.synchronize do
+        @cache_version += 1
+        @tool_cache.clear
+        @cache_params.delete(:tools)
+        @tool_cache_generation += 1
       end
-
-      MCPClient::Errors::TaskError.new("Error #{action} task '#{task_id}': #{error.message}")
     end
 
-    # Handle a notifications/tasks/status notification (MCP 2025-11-25).
-    # The params are a flat Task.
-    # @param server_id [String] server identifier for the log prefix
-    # @param params [Hash] the flat task params
+    # The definition the transport's own tools/call request went out under,
+    # taken from the transport so it is spent on this one re-resolve.
+    #
+    # It is read back rather than re-listed because a list is only ever the
+    # transport's *current* answer: a tools/list_changed that raced the call
+    # has already replaced it, and the server answered under the definition
+    # the request carried.
+    # @param server [MCPClient::ServerBase] the transport the call went to
+    # @param tool_name [String] the tool being re-resolved
+    # @return [MCPClient::Tool, nil] the definition the answering attempt went
+    #   out under, or nil when the transport recorded none (or recorded that
+    #   its list did not carry the tool), in which case the definition the
+    #   caller resolved before the call stands
+    def called_tool_definition(server, tool_name)
+      return nil unless server.respond_to?(:take_called_tool_definition, true)
+
+      server.send(:take_called_tool_definition, tool_name.to_s)&.first
+    end
+
+    # Forget the once-per-definition schema checks of the tool definitions a
+    # cache slice no longer holds. Their keys name a tool definition, so a
+    # server that keeps renaming its tools would otherwise grow both memos
+    # without bound; a definition still served is checked again on its next
+    # use, which its identity token decides anyway.
+    # @param server [MCPClient::ServerBase, nil] the server whose entries go,
+    #   or nil for every server
     # @return [void]
-    def handle_task_status_notification(server_id, params)
-      task = MCPClient::Task.from_json(params)
-      logger.info("[#{server_id}] Task #{task.task_id} status: #{task.status}")
-    rescue StandardError => e
-      logger.debug("[#{server_id}] Failed to parse task status notification: #{e.message}")
+    def forget_schema_checks(server = nil)
+      [@input_schema_warnings, @output_schema_coverage, @output_schema_dialects].each do |memo|
+        next unless memo
+
+        if server
+          memo.delete_if { |(server_id, _name), _| server_id == server.object_id }
+        else
+          memo.clear
+        end
+      end
     end
 
     # Generate a cache key for server-specific items
@@ -1220,15 +1445,18 @@ module MCPClient
     # Supports both form mode (structured data) and URL mode (out-of-band interaction).
     # @param _request_id [String, Integer] the JSON-RPC request ID (unused at client layer)
     # @param params [Hash] the elicitation parameters
+    # @param server [MCPClient::ServerBase, nil] the server that asked, so the
+    #   URL-mode host contract can follow its protocol era; nil (an era that
+    #   was never established) keeps the 2025-11-25 contract
     # @return [Hash] the elicitation response
-    def handle_elicitation_request(_request_id, params)
+    def handle_elicitation_request(_request_id, params, server = nil)
       mode = params['mode'] || 'form'
       # MCP 2025-11-25: requests with a mode not declared in client
       # capabilities MUST be rejected with -32602 (Invalid params). This check
       # precedes everything else — an undeclared mode is -32602 even when no
       # handler is configured.
       unless SUPPORTED_ELICITATION_MODES.include?(mode)
-        @logger.warn("Rejecting elicitation request with unsupported mode '#{mode}'")
+        @logger.warn("Rejecting elicitation request with unsupported mode '#{sanitize_peer_log_text(mode.to_s)}'")
         return jsonrpc_error_result(-32_602, "Elicitation mode '#{mode}' is not supported")
       end
 
@@ -1243,7 +1471,7 @@ module MCPClient
 
       begin
         result = if mode == 'url'
-                   handle_url_elicitation(params, message)
+                   handle_url_elicitation(params, message, server)
                  else
                    handle_form_elicitation(params, message)
                  end
@@ -1280,7 +1508,9 @@ module MCPClient
       # Validate schema if present
       if schema
         schema_errors = ElicitationValidator.validate_schema(schema)
-        @logger.warn("Elicitation schema validation warnings: #{schema_errors.join('; ')}") unless schema_errors.empty?
+        unless schema_errors.empty?
+          @logger.warn("Elicitation schema validation warnings: #{sanitize_peer_log_text(schema_errors.join('; '))}")
+        end
       end
 
       # Call the user-defined handler
@@ -1299,10 +1529,10 @@ module MCPClient
     # Handle URL mode elicitation (MCP 2025-11-25)
     # @param params [Hash] the elicitation parameters
     # @param message [String] the human-readable message
+    # @param server [MCPClient::ServerBase, nil] the server that asked
     # @return [Object] handler result
-    def handle_url_elicitation(params, message)
-      url = params['url']
-      elicitation_id = params['elicitationId']
+    def handle_url_elicitation(params, message, server = nil)
+      url_params = url_elicitation_metadata(params, server)
 
       # Call handler with URL-mode specific params
       case @elicitation_handler.arity
@@ -1311,19 +1541,56 @@ module MCPClient
       when 1
         @elicitation_handler.call(message)
       when 2, -1
-        @elicitation_handler.call(message, { 'mode' => 'url', 'url' => url, 'elicitationId' => elicitation_id })
+        @elicitation_handler.call(message, url_params)
       else
-        @elicitation_handler.call(message, { 'mode' => 'url', 'url' => url, 'elicitationId' => elicitation_id },
-                                  params['metadata'])
+        @elicitation_handler.call(message, url_params, params['metadata'])
       end
     end
 
+    # The URL-mode metadata handed to the host. MCP 2026-07-28 (changelog,
+    # minor change 11) removed the `elicitationId` field along with
+    # `notifications/elicitation/complete`: under the multi round-trip
+    # requests pattern the client learns the outcome by retrying the original
+    # request, and a server that must correlate an elicitation across retries
+    # carries its own identifier in `requestState`. So a modern server's
+    # contract has no such key at all — not even a nil one — and a
+    # non-conforming modern server that sends the field anyway cannot smuggle
+    # a correlation id to the host through it. For a server on an earlier
+    # revision the field is part of the protocol and the contract is
+    # unchanged, key present (nil when the server sent none) and all; a nil
+    # server (an era that was never established) is treated the same way.
+    # @param params [Hash] the elicitation parameters
+    # @param server [MCPClient::ServerBase, nil] the server that asked
+    # @return [Hash] the metadata hash for the host's handler
+    def url_elicitation_metadata(params, server)
+      metadata = { 'mode' => 'url', 'url' => params['url'] }
+      return metadata.merge('elicitationId' => params['elicitationId']) unless modern_server?(server)
+
+      if params.key?('elicitationId')
+        # Dropping the field is the protocol decision; saying so is a
+        # courtesy. A logger that raises costs the notice, never the
+        # elicitation — the value is a server-chosen correlation id, so the
+        # message names the field and never quotes it.
+        begin
+          @logger.warn('Ignoring elicitationId on a URL-mode elicitation request: MCP 2026-07-28 removed the field ' \
+                       '(the outcome is learned by retrying the original request; correlate via requestState)')
+        rescue StandardError
+          nil
+        end
+      end
+      metadata
+    end
+
     # Format and validate the elicitation response
     # @param result [Object] handler result
     # @param params [Hash] original request params (for schema validation)
     # @return [Hash] formatted response
     def format_elicitation_response(result, params)
-      response = normalize_elicitation_result(result)
+      response = if (params['mode'] || 'form') == 'url'
+                   normalize_url_elicitation_result(result)
+                 else
+                   normalize_elicitation_result(result)
+                 end
 
       # Per the ElicitResult schema, content is only present when the action
       # is accept and the mode was form; it is omitted for decline/cancel and
@@ -1348,6 +1615,29 @@ module MCPClient
       response
     end
 
+    # A URL-mode elicitation reports the user's consent to open the URL, so
+    # only an explicit answer counts: `true` or an ElicitResult with an
+    # `action` of accept/decline/cancel. Anything else — a bare value, a form
+    # style content hash, nil — is not consent and is answered with cancel.
+    # @param result [Object] handler result
+    # @return [Hash] normalized ElicitResult without content
+    def normalize_url_elicitation_result(result)
+      return { 'action' => 'accept' } if result == true
+
+      action = result.is_a?(Hash) ? (result['action'] || result[:action]) : nil
+      if %w[accept decline cancel].include?(action.to_s)
+        # ElicitResult carries `_meta` in every mode; only `content` is
+        # form-mode-specific, and format_elicitation_response strips it.
+        meta = result['_meta'] || result[:_meta]
+        return { 'action' => action.to_s, '_meta' => meta }.compact
+      end
+
+      unless result.nil? || result == false
+        @logger.warn('URL-mode elicitation handler gave no explicit action; answering cancel (consent is explicit)')
+      end
+      { 'action' => 'cancel' }
+    end
+
     # Normalize a handler's return value into a string-keyed ElicitResult
     # shape, so mixed or symbol keys cannot bypass content handling.
     # @param result [Object] handler result
@@ -1384,14 +1674,21 @@ module MCPClient
       ElicitationValidator.validate_content(response['content'], schema)
     end
 
-    # Ensure the action value conforms to MCP spec (accept, decline, cancel)
-    # Falls back to accept for unknown action values.
+    # Ensure the action value conforms to MCP spec (accept, decline, cancel).
+    # An action outside that set is not consent the user gave, so it is
+    # answered as cancel — the verdict URL mode reaches for the same handler
+    # result — rather than rewritten into an accept. (A handler that returns
+    # bare content and no action at all is the documented convenience shape
+    # and never reaches here; see #normalize_elicitation_result.)
+    # @param result [Hash] the normalized ElicitResult
+    # @return [Hash] the result, with an unrecognized action answered as cancel
     def normalised_action_response(result)
       action = result['action']
       return result if %w[accept decline cancel].include?(action)
 
-      @logger.warn("Unknown elicitation action '#{action}', defaulting to accept")
-      result.merge('action' => 'accept')
+      @logger.warn("Unknown elicitation action '#{sanitize_peer_log_text(action.to_s)}'; answering cancel " \
+                   '(consent is explicit)')
+      result.merge('action' => 'cancel')
     end
 
     # Normalize roots array - convert Hashes to Root objects (MCP 2025-06-18)
@@ -1420,15 +1717,35 @@ module MCPClient
       { 'roots' => @roots.map(&:to_h) }
     end
 
+    # Whether a server may be told the roots list changed. MCP forbids using a
+    # capability that was not declared during initialization, so the
+    # notification goes only to sessions whose declared client capabilities
+    # include roots: a transport that registers the handlers for the modern
+    # multi round-trip pattern but has no server-request channel to serve
+    # them on (plain HTTP on a legacy session) declares none, however it
+    # answers respond_to?.
+    # @param server [Object] an MCP server transport
+    # @return [Boolean]
+    def roots_list_changed_recipient?(server)
+      return false unless server.respond_to?(:on_roots_list_request)
+      # notifications/roots/list_changed was removed in MCP 2026-07-28: a
+      # modern server reads roots through the multi round-trip pattern when it
+      # needs them, and has no channel to be told they changed.
+      # Judged by the ESTABLISHED era: while a probe is in flight the version
+      # is only a proposal, and a server that then falls back to the handshake
+      # can still ask for roots — so the transport, which settles the era
+      # before it writes anything, makes the call.
+      return false if server.respond_to?(:protocol_era) && server.protocol_era == :modern
+      return true unless server.respond_to?(:client_capabilities)
+
+      server.client_capabilities.key?('roots')
+    end
+
     # Send notification to all servers that roots have changed (MCP 2025-06-18)
     # @return [void]
     def notify_roots_changed
       @servers.each do |server|
-        # Only notify sessions where the roots capability could be declared:
-        # MCP forbids using capabilities that were not negotiated, and
-        # transports without a server-request channel (plain HTTP) never
-        # declare roots.
-        next unless server.respond_to?(:on_roots_list_request)
+        next unless roots_list_changed_recipient?(server)
 
         begin
           server.rpc_notify('notifications/roots/list_changed', {})
@@ -1439,52 +1756,13 @@ module MCPClient
       end
     end
 
-    # Handle sampling/createMessage request from server (MCP 2025-11-25)
-    # @param _request_id [String, Integer] the JSON-RPC request ID (unused, kept for callback signature)
-    # @param params [Hash] the sampling parameters
-    # @return [Hash] the sampling response (role, content, model, stopReason)
-    def handle_sampling_request(_request_id, params)
-      # Without a handler the sampling capability was never declared, so the
-      # request targets an unsupported method: answer -32601 (Method not
-      # found) rather than -1, which sampling.mdx § Error Handling reserves
-      # for "User rejected sampling request".
-      unless @sampling_handler
-        @logger.warn('Received sampling request but no sampling handler is configured')
-        return jsonrpc_error_result(-32_601, 'Sampling not supported: no sampling handler configured')
-      end
-
-      # SEP-1577 (schema.ts CreateMessageRequestParams.tools/.toolChoice):
-      # "The client MUST return an error if this field is provided but
-      # ClientCapabilities.sampling.tools is not declared." -32602 is the
-      # Invalid params code used by sampling.mdx § Error Handling.
-      if (params.key?('tools') || params.key?('toolChoice')) && !@sampling_supports_tools
-        @logger.warn('Rejecting tool-enabled sampling request: sampling.tools capability not declared')
-        return jsonrpc_error_result(-32_602,
-                                    'Invalid params: tools/toolChoice provided but the sampling.tools ' \
-                                    'capability was not declared')
-      end
-
-      messages = params['messages'] || []
-      model_preferences = normalize_model_preferences(params['modelPreferences'])
-      system_prompt = params['systemPrompt']
-      max_tokens = params['maxTokens']
-
-      begin
-        # Call the user-defined handler with parameters based on arity
-        result = call_sampling_handler(messages, model_preferences, system_prompt, max_tokens, params)
+    # @param block [Object] a content block
+    # @return [String, nil] its type, nil unless it is an object with a String type
+    def sampling_block_type(block)
+      return nil unless block.is_a?(Hash)
 
-        # Validate and format response
-        validate_sampling_response(result)
-      rescue StandardError => e
-        @logger.error("Sampling handler error: #{e.message}")
-        @logger.debug(e.backtrace.join("\n"))
-        # A handler exception is an internal client failure (-32603), not a
-        # user rejection: sampling.mdx § Error Handling reserves -1 for
-        # "User rejected sampling request". The exception message itself is
-        # host-internal (file paths, connection strings, library internals)
-        # and stays in the local log rather than crossing to the server.
-        jsonrpc_error_result(-32_603, 'Sampling error')
-      end
+      type = block['type'] || block[:type]
+      type.is_a?(String) ? type : nil
     end
 
     # Call sampling handler with appropriate arity