parse-stack-next 5.1.1 → 5.2.1

data/docs/mongodb_direct_guide.md

@@ -757,6 +757,15 @@ non-master scope so this enforcement always runs. See the
 [Atlas Vector Search Guide](./atlas_vector_search_guide.md) for the
 full API surface.
 
+`Parse::Retrieval.retrieve` and the `semantic_search` agent tool (v5.2)
+build directly on `find_similar`, so they inherit this exact Layer 1-5
+mongo-direct enforcement. The earlier RAG plan's "two-stage" REST
+re-query was intentionally NOT adopted — there is no REST vector path,
+and `acl_user:` / `acl_role:` scopes have no REST equivalent, so the
+post-`$vectorSearch` `_rperm` `$match` is the single enforcement
+boundary. The retrieval layer adds a tenant-scope fold into the Atlas
+pre-filter on top of this, never a substitute for it.
+
 ### Timeouts
 
 ```ruby
@@ -947,7 +956,7 @@ three independent flags that every mutation re-checks per call.
   Requires `clusterMonitor` privilege on the reader; returns `{}`
   when not granted so callers degrade gracefully.
 
-### Model DSL: `mongo_index` / `mongo_geo_index` / `mongo_relation_index`
+### Model DSL: `mongo_index` / `unique_index_on` / `mongo_geo_index` / `mongo_relation_index`
 
 Index declarations are class-level metadata on `Parse::Object`
 subclasses. They run validation at registration time so a typo,
@@ -967,6 +976,7 @@ class Car < Parse::Object
 
   mongo_index :make, :model, :year         # compound
   mongo_index :vin, unique: true
+  unique_index_on :registration            # dedup floor; unique { registration: 1 }
   mongo_index :owner                       # pointer auto-rewrites to _p_owner
   mongo_geo_index :location                # 2dsphere on GeoJSON Point
   mongo_index :tags                        # array field
@@ -1007,6 +1017,61 @@ class Author < Parse::Object
 end
 ```
 
+### `unique_index_on` — the `first_or_create!` correctness floor
+
+`unique_index_on(*fields, sparse: false, partial: nil, name: nil)` declares
+a unique index on the exact dedup tuple that `first_or_create!` and
+`create_or_update!` key on. It is thin sugar over
+`mongo_index(*fields, unique: true, …)` — same registration, same validation
+(sensitive-field guard, pointer auto-rewrite, parallel-array / relation /
+`_id` rejection), same `apply_indexes!` writer path — but the name states the
+intent: these fields are the create-or-update identity.
+
+```ruby
+class Subscription < Parse::Object
+  property :email, :string
+  belongs_to :tenant, as: :user
+
+  unique_index_on :email, :tenant   # key: { email: 1, _p_tenant: 1 } unique
+end
+
+Subscription.apply_indexes!          # provisions the index via the writer gate
+```
+
+**Why it matters.** The Redis-backed `synchronize:` lock on `first_or_create!`
+is a *latency optimization*: in the common path it collapses concurrent
+callers so only one issues the create. The unique index is the *correctness
+floor* that survives the lock being bypassed — a Redis outage, a TTL expiring
+between the existence check and the write, a caller passing
+`synchronize: false`, or two app servers whose lock secrets disagree. When a
+race slips past the lock, the loser's insert fails with `DuplicateValue`
+(Parse error 137), which `first_or_create!` rescues and resolves to the
+winning row. Lock plus index make the net invariant — *exactly one row, every
+caller sees the same id* — hold under any race, not just the happy path.
+
+**Defaults are non-sparse, on purpose.** The index key is kept identical to
+the query `first_or_create!` re-runs on recovery (`_scoped_first` on the same
+`query_attrs`), so a 137 always corresponds to a row the recovery query can
+find. A sparse or partial index that fires on a condition the recovery query
+doesn't reproduce would surface a 137 the rescue can't resolve, and the error
+would re-raise. `sparse:` only changes behavior for a document missing *every*
+field in the tuple — a compound sparse index indexes a doc when it has at
+least one key, and `first_or_create!` always writes the full tuple, so sparse
+never weakens the floor. Leave it off unless out-of-band writers create
+tuple-less rows you want excluded.
+
+For "unique within a subset" — unique email per tenant, but rows with no
+tenant may repeat — a partial filter is the right tool, **not** `sparse:`
+(a compound sparse index still collides two rows that share the present
+fields). You own the filter's lifecycle and must keep the recovery query
+consistent with it:
+
+```ruby
+# Unique email per tenant; tenant-less rows are not constrained.
+unique_index_on :email, :tenant,
+                partial: { "_p_tenant" => { "$exists" => true } }
+```
+
 ### Migrator: `indexes_plan` (dry-run) / `apply_indexes!` (mutate)
 
 `Parse::Schema::IndexMigrator` reconciles declared indexes against the

data/docs/mongodb_index_optimization_guide.md

@@ -66,6 +66,7 @@ paying for an index nobody uses.
 | Regular B-tree | `mongo_index :field` | Equality, range, sort on a scalar field |
 | Compound | `mongo_index :a, :b, :c` | Multi-field queries with a common prefix |
 | Unique | `mongo_index :field, unique: true` | Enforce uniqueness at the DB layer |
+| Unique dedup floor | `unique_index_on :a, :b` | Name the `first_or_create!` / `create_or_update!` dedup tuple; sugar for `unique: true` (non-sparse) |
 | Sparse | `mongo_index :field, sparse: true` | Field present on only some documents |
 | Partial | `mongo_index :field, partial: { … }` | Index only documents matching a filter |
 | TTL | `mongo_index :field, expire_after: N` | Auto-delete documents N seconds after the timestamp |
@@ -318,7 +319,27 @@ fails.
 
 **Better:** `unique: true, sparse: true` for "unique when present".
 This is exactly what `parse_reference` auto-registers, and it's the
-right pattern for any optional uniqueness constraint.
+right pattern for any optional uniqueness constraint *on a single
+field*.
+
+**Sparse does NOT generalize to compound keys.** A compound sparse
+index excludes a document only when it is missing *every* indexed
+field; a document that has at least one key is still indexed. So for a
+two-field tuple, two rows that share the present field and both omit
+the other still collide under `sparse: true`. For "unique within a
+subset" — e.g. unique `email` per `tenant`, but tenant-less rows may
+repeat — use a **partial filter**, not sparse:
+
+```ruby
+unique_index_on :email, :tenant,
+                partial: { "_p_tenant" => { "$exists" => true } }
+```
+
+For the `first_or_create!` / `create_or_update!` dedup tuple, prefer
+`unique_index_on` (sugar for `unique: true`, **non-sparse** by default
+so the index key matches the query the upsert re-runs on recovery). It
+is the durable correctness floor behind the synchronize-create lock —
+see the MongoDB Direct guide for the full rationale.
 
 ### Geo without proper coordinate order
 

data/docs/usage_guide.md

@@ -133,6 +133,21 @@ song = Song.first_or_create!({ title: "My Song" }, { artist: "Unknown" })
 song = Song.create_or_update!({ title: "My Song" }, { plays: 100 })
 ```
 
+Under concurrency these have a TOCTOU window. Pass `synchronize: true` to
+serialize the find→create→save through a Moneta-backed lock, and declare a
+`unique_index_on` on the dedup tuple as the durable correctness floor — the lock
+optimizes latency, the unique index guarantees a single row even if the lock is
+bypassed:
+
+```ruby
+class Song < Parse::Object
+  property :title, :string
+  unique_index_on :title          # provisioned via Song.apply_indexes!
+end
+
+Song.first_or_create!({ title: "My Song" }, { artist: "Unknown" }, synchronize: true)
+```
+
 ## ACLs (Access Control)
 
 ```ruby

data/lib/parse/agent/constraint_translator.rb

@@ -170,7 +170,11 @@ module Parse
           # These enable bcrypt-hash and session-token oracle attacks via
           # count deltas even when operators are otherwise clean.
           assert_where_key_permitted!(key)
-          result[columnize(key)] = translate_value(value, depth: 0, agent: agent)
+          result[columnize(key)] = if key == "$relatedTo"
+                                     translate_related_to_value(value, depth: 0, agent: agent)
+                                   else
+                                     translate_value(value, depth: 0, agent: agent)
+                                   end
         end
       end
 
@@ -213,30 +217,48 @@ module Parse
         # Check if it's a Parse type (Pointer, Date, File, GeoPoint)
         return hash if parse_type?(hash)
 
-        # Check if all keys are operators
-        if hash.keys.all? { |k| k.to_s.start_with?("$") }
-          hash.transform_keys(&:to_s).each_with_object({}) do |(op, val), result|
-            validate_operator!(op)
-            # NEW-TOOLS-7: validate $regex / $options operands before
-            # forwarding to MongoDB.
-            assert_regex_operand_safe!(op, val) if op == "$regex" || op == "$options"
-            result[op] = if CROSS_CLASS_OPERATORS.include?(op)
-                           translate_cross_class_value(op, val, depth: depth + 1, agent: agent)
-                         else
-                           translate_value(val, depth: depth + 1, agent: agent)
-                         end
-          end
-        else
-          # Regular nested object - translate keys to columnized format.
-          # Apply the internal-field key denylist at every nesting level so
-          # a key nested inside $and/$or/$nor cannot bypass the top-level check.
-          hash.transform_keys(&:to_s).each_with_object({}) do |(k, v), result|
+        # Classify each key INDEPENDENTLY rather than branching on whether
+        # *every* key is an operator. A hash that mixes an operator key with a
+        # non-operator (field) sibling — reachable as a `$or`/`$and`/`$nor`
+        # array element — must still validate and dispatch the operator. The
+        # previous all-or-nothing `keys.all?(operator)` gate routed any mixed
+        # hash to the field branch, which skipped `validate_operator!` AND the
+        # cross-class / `$relatedTo` accessibility checks: a blocked operator
+        # (`$where`) or an off-allowlist cross-class / relation reference could
+        # smuggle through alongside a throwaway field key. Per-key dispatch
+        # closes that hole while preserving behavior for pure-operator and
+        # pure-field hashes.
+        hash.transform_keys(&:to_s).each_with_object({}) do |(k, v), result|
+          if k.start_with?("$")
+            result[k] = translate_operator_value(k, v, depth: depth, agent: agent)
+          else
+            # Field-name key: enforce the internal-field denylist at every
+            # nesting level (so a key nested inside `$and`/`$or`/`$nor` cannot
+            # bypass the top-level check), then columnize and recurse.
             assert_where_key_permitted!(k)
             result[columnize(k)] = translate_value(v, depth: depth + 1, agent: agent)
           end
         end
       end
 
+      # Validate and translate a single operator (`$`-prefixed) key/value pair.
+      # Centralized so the operator denylist/whitelist and the cross-class /
+      # `$relatedTo` accessibility checks run for operators in pure-operator
+      # hashes AND for operators mixed with field-key siblings.
+      def translate_operator_value(op, val, depth:, agent: nil)
+        validate_operator!(op)
+        # NEW-TOOLS-7: validate $regex / $options operands before
+        # forwarding to MongoDB.
+        assert_regex_operand_safe!(op, val) if op == "$regex" || op == "$options"
+        if CROSS_CLASS_OPERATORS.include?(op)
+          translate_cross_class_value(op, val, depth: depth + 1, agent: agent)
+        elsif op == "$relatedTo"
+          translate_related_to_value(val, depth: depth + 1, agent: agent)
+        else
+          translate_value(val, depth: depth + 1, agent: agent)
+        end
+      end
+
       # Translate the value of a cross-class operator
       # (+$inQuery+/+$notInQuery+/+$select+/+$dontSelect+). The value
       # carries an embedded +className+ that must be validated against
@@ -299,6 +321,55 @@ module Parse
         translate_value(val, depth: depth, agent: agent)
       end
 
+      # Validate the owning-object class named by a +$relatedTo+ constraint.
+      #
+      # +$relatedTo+ has the shape +{ object: <Pointer>, key: <relation field> }+.
+      # Unlike +$inQuery+ / +$select+ it carries no +className+ / inner +where+,
+      # so it is NOT a {CROSS_CLASS_OPERATORS} entry — but it DOES reach across
+      # to a second class: the owning object whose relation is being read. Left
+      # unvalidated, an agent narrowed to one class (or with a class globally
+      # +agent_hidden+) could still name a relation anchored on an off-allowlist
+      # class via the +object+ pointer. That is the SDK-surface analog of
+      # GHSA-wmwx-jr2p-4j4r, where Parse Server's own +$relatedTo+ bypassed the
+      # owning object's ACL. Run the owning class through the same accessibility
+      # policy as every other cross-class hop, then translate the value normally.
+      #
+      # Fails closed when the owning class cannot be resolved from +object+: an
+      # unresolvable pointer is exactly the shape that would otherwise slip the
+      # check, so refuse the constraint rather than skip it.
+      def translate_related_to_value(val, depth:, agent: nil)
+        owning_class = related_to_owning_class(val)
+        if owning_class.nil? || owning_class.to_s.empty?
+          raise ConstraintSecurityError.new(
+            "SECURITY: $relatedTo requires a resolvable owning-object class; " \
+            "none could be determined from its `object` pointer.",
+            operator: "$relatedTo",
+            reason: :cross_class_denied,
+          )
+        end
+        assert_embedded_class_accessible!("$relatedTo", owning_class, agent: agent)
+        translate_value(val, depth: depth, agent: agent)
+      end
+
+      # Extract the Parse class name of a +$relatedTo+ constraint's owning
+      # object from its +object+ slot, which may be a Parse::Pointer, a Parse
+      # pointer/relation hash (+{__type:, className:, objectId:}+, string or
+      # symbol keys), or a storage-form string (+"ClassName$objectId"+).
+      # Returns nil when no class can be resolved so the caller can fail closed.
+      def related_to_owning_class(val)
+        return nil unless val.is_a?(Hash)
+        obj = val["object"] || val[:object]
+        return obj.parse_class if obj.respond_to?(:parse_class)
+        case obj
+        when Hash
+          o = obj.transform_keys(&:to_s)
+          cn = o["className"]
+          cn.nil? || cn.to_s.empty? ? nil : cn
+        when String
+          obj.include?("$") ? obj.split("$", 2).first : nil
+        end
+      end
+
       # Hook into the agent-side accessibility check when the agent
       # module is loaded; in pure-unit contexts where +Parse::Agent::Tools+
       # has not been loaded, default to a no-op rather than raising —

data/lib/parse/agent/describe.rb

@@ -185,6 +185,7 @@ module Parse
             class_filter: strict_class_filter?,
           },
           correlation_id: @correlation_id,
+          prompt:         { version: Parse::Agent::PROMPT_VERSION },
         }
       end
 

data/lib/parse/agent/errors.rb

@@ -129,5 +129,21 @@ module Parse
     # agent-callable" (a Parse::Error) or "the tier doesn't allow it"
     # (a +:permission_denied+).
     class MethodFiltered < AgentError; end
+
+    # Raised at semantic-search dispatch time when at least one class in
+    # the model registry declares +agent_tenant_scope+ but the class
+    # being searched does not. In a tenant-aware deployment an
+    # un-scoped searchable surface would let an agent retrieve across
+    # tenant boundaries, so the gate is a hard refusal, not a warning.
+    # Enforced at dispatch (when all classes are loaded) rather than at
+    # +agent_searchable+ declaration time so class-load order can't
+    # produce a false negative.
+    class MissingTenantScope < AgentError; end
+
+    # Raised when a tool result contains an operator-registered
+    # prompt-injection canary phrase AND `Parse::Agent.canary_action` is
+    # `:refuse`. A SecurityError subclass so it routes through execute's
+    # security rescue and is never swallowed.
+    class PromptInjectionDetected < SecurityError; end
   end
 end

data/lib/parse/agent/mcp_client.rb

@@ -528,7 +528,16 @@ module Parse
       # @api private
       def wrap_tool_content_for_llm(content)
         s = content.to_s
+        # Idempotency first: our own already-wrapped output (marker at the
+        # head) passes through untouched, so re-wrapping across turns does
+        # not grow or mangle the marker.
         return s if s.start_with?(UNTRUSTED_TOOL_RESULT_MARKER)
+        # Fresh content: neutralize any embedded wrapper/marker strings
+        # (e.g. a stored `</schema_description>` or a forged marker) BEFORE
+        # prepending the real marker, so a stored value can't impersonate or
+        # close the wrapper. The prefix we add afterward is therefore never
+        # seen as embedded by the scrub.
+        s = Parse::Agent::PromptHardening.scrub_marker_injection(s)
         "#{UNTRUSTED_TOOL_RESULT_MARKER}\n#{s}"
       end
 

data/lib/parse/agent/mcp_dispatcher.rb

@@ -132,7 +132,16 @@ module Parse
       #   are translated into a JSON-RPC `isError` content envelope by
       #   {#handle_tools_call}. Cleared from the agent in an ensure block
       #   before this method returns.
-      def self.call(body:, agent:, logger: nil, progress_callback: nil, cancellation_token: nil)
+      # @param subscription_manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      #   the per-transport resource-subscription coordinator. When present and
+      #   {Parse::Agent::MCPSubscriptions::Manager#supported? supported}, the
+      #   `initialize` handshake advertises the `resources.subscribe` capability
+      #   and `resources/subscribe` / `resources/unsubscribe` are routed to it.
+      #   nil (the default, and the only option on non-streaming transports like
+      #   the WEBrick MCPServer) leaves the capability unadvertised and those
+      #   methods returning a "not supported" error.
+      def self.call(body:, agent:, logger: nil, progress_callback: nil, cancellation_token: nil,
+                    subscription_manager: nil, approval_gate: nil)
         # Snapshot any prior callback/token already on the agent (e.g. a
         # token a parent dispatcher installed before a tool handler
         # invoked us recursively, or values pre-set by the application).
@@ -143,6 +152,7 @@ module Parse
         # token.
         prev_progress_callback   = agent.progress_callback   if agent.respond_to?(:progress_callback)
         prev_cancellation_token  = agent.cancellation_token  if agent.respond_to?(:cancellation_token)
+        prev_approval_gate       = agent.approval_gate        if agent.respond_to?(:approval_gate)
 
         # Install the progress callback and cancellation token on the
         # agent for the duration of the dispatch. Cleared in the ensure
@@ -156,6 +166,10 @@ module Parse
         # is documented to return a fresh agent per request.
         agent.progress_callback   = progress_callback   if progress_callback   && agent.respond_to?(:progress_callback=)
         agent.cancellation_token  = cancellation_token  if cancellation_token  && agent.respond_to?(:cancellation_token=)
+        # Install the per-session approval gate (MCP elicitation) so
+        # agent.execute can request human approval for destructive tools.
+        # Restored in the ensure block like the other per-request state.
+        agent.approval_gate       = approval_gate        if approval_gate       && agent.respond_to?(:approval_gate=)
 
         # Guard: body must be a Hash with a "method" key.
         unless body.is_a?(Hash) && body.key?("method")
@@ -175,7 +189,7 @@ module Parse
           return { status: 200, body: jsonrpc_error(id, -32600, "Invalid Request: notifications must not carry an id") }
         end
 
-        result_hash = dispatch(method, params, agent, id, logger)
+        result_hash = dispatch(method, params, agent, id, logger, subscription_manager)
         { status: result_hash[:status], body: result_hash[:body] }
 
       rescue Parse::Agent::Unauthorized => e
@@ -197,6 +211,9 @@ module Parse
         if agent.respond_to?(:cancellation_token=)
           agent.cancellation_token = prev_cancellation_token
         end
+        if agent.respond_to?(:approval_gate=)
+          agent.approval_gate = prev_approval_gate
+        end
       end
 
       # Emit an internal-error diagnostic. The class+message are operator-only;
@@ -219,10 +236,10 @@ module Parse
       # envelope, and return { status:, body: }.
       #
       # @api private
-      def self.dispatch(method, params, agent, id, logger = nil)
+      def self.dispatch(method, params, agent, id, logger = nil, subscription_manager = nil)
         result = case method
           when "initialize"
-            handle_initialize(params)
+            handle_initialize(params, subscription_manager)
           when "tools/list"
             handle_tools_list(params, agent)
           when "tools/call"
@@ -233,6 +250,10 @@ module Parse
             handle_resources_templates_list(params, agent)
           when "resources/read"
             handle_resources_read(params, agent)
+          when "resources/subscribe"
+            handle_resources_subscribe(params, agent, subscription_manager)
+          when "resources/unsubscribe"
+            handle_resources_unsubscribe(params, agent, subscription_manager)
           when "prompts/list"
             handle_prompts_list(params)
           when "prompts/get"
@@ -278,6 +299,12 @@ module Parse
 
       rescue Parse::Agent::Unauthorized => e
         { status: 401, body: jsonrpc_error(id, -32001, "Unauthorized") }
+      rescue Parse::Agent::AccessDenied
+        # Class-authorization denial (agent_hidden / classes: allowlist), e.g.
+        # from the resources/subscribe gate. Map to -32602 with a generic
+        # message — do NOT echo the class name, so a denied subscribe can't be
+        # used to probe which hidden classes exist.
+        { status: 200, body: jsonrpc_error(id, -32602, "Invalid params") }
       rescue Parse::Agent::SecurityError
         { status: 200, body: jsonrpc_error(id, -32602, "Invalid params") }
       rescue Parse::Agent::ValidationError => e
@@ -307,8 +334,11 @@ module Parse
       # returning the server's preferred version locks those clients
       # out.
       #
+      # @param subscription_manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      #   when supported, flips the advertised `resources.subscribe` capability
+      #   to true. See {#capabilities_for}.
       # @return [Hash] protocol version, capabilities, and server info.
-      def self.handle_initialize(params)
+      def self.handle_initialize(params, subscription_manager = nil)
         requested = params.is_a?(Hash) ? params["protocolVersion"] : nil
         negotiated =
           if requested.is_a?(String) && SUPPORTED_PROTOCOL_VERSIONS.include?(requested)
@@ -318,7 +348,7 @@ module Parse
           end
         {
           "protocolVersion" => negotiated,
-          "capabilities"    => CAPABILITIES,
+          "capabilities"    => capabilities_for(subscription_manager),
           "serverInfo"      => {
             "name"    => "parse-stack-mcp",
             "version" => Parse::Stack::VERSION,
@@ -327,6 +357,27 @@ module Parse
       end
       private_class_method :handle_initialize
 
+      # Compute the advertised capability object for this transport.
+      #
+      # `resources.subscribe` is advertised as `true` ONLY when a subscription
+      # manager is wired AND reports itself supported (LiveQuery enabled +
+      # available, on a streaming transport that can hold a listening channel).
+      # Advertising a capability is a contract: we never claim `subscribe: true`
+      # unless the server can actually deliver `notifications/resources/updated`.
+      # On the WEBrick MCPServer (no streaming) and on the Rack app when
+      # subscriptions are disabled, this falls back to the base CAPABILITIES
+      # with `subscribe: false`.
+      #
+      # @param manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      # @return [Hash]
+      def self.capabilities_for(manager)
+        return CAPABILITIES unless manager.respond_to?(:supported?) && manager.supported?
+        CAPABILITIES.merge(
+          "resources" => CAPABILITIES["resources"].merge("subscribe" => true),
+        )
+      end
+      private_class_method :capabilities_for
+
       # Handle `tools/list`.
       #
       # Accepts an optional non-standard `category` param (Parse Stack
@@ -438,12 +489,24 @@ module Parse
             envelope
           end
         else
-          {
+          # Forward the structured error metadata the agent already computed
+          # (error_code, retry_after, details such as suggested_rewrite /
+          # allowed_fields) so a client can branch deterministically and
+          # honor retry_after — instead of re-parsing the prose message. Goes
+          # in `_meta` (spec-allowed arbitrary metadata) under a `parse.`
+          # prefix; the human-readable text content is unchanged.
+          envelope = {
             "content" => [
               { "type" => "text", "text" => result[:error].to_s },
             ],
             "isError" => true,
           }
+          meta = {}
+          meta["parse.error_code"]  = result[:error_code].to_s if result[:error_code]
+          meta["parse.retry_after"] = result[:retry_after]     if result[:retry_after]
+          meta["parse.details"]     = result[:details]         if result[:details].is_a?(Hash) && result[:details].any?
+          envelope["_meta"] = meta unless meta.empty?
+          envelope
         end
       end
       private_class_method :handle_tools_call
@@ -938,6 +1001,75 @@ module Parse
       end
       private_class_method :handle_resources_read
 
+      # Handle `resources/subscribe` (MCP 2025-06-18).
+      #
+      # Registers a LiveQuery-backed subscription for `params["uri"]` keyed by
+      # the agent's session identity (`correlation_id`, sourced from the
+      # `Mcp-Session-Id` header by the transport). Subsequent data changes are
+      # debounced and delivered as `notifications/resources/updated` over the
+      # session's GET listening stream.
+      #
+      # Per the MCP spec a successful subscribe returns an empty result. Errors
+      # propagate as JSON-RPC errors:
+      #   - manager absent / unsupported  → -32601 (capability not offered)
+      #   - malformed or non-subscribable URI → -32602 (ValidationError)
+      #   - agent scope with no LiveQuery equivalent → -32602 (SecurityError)
+      #
+      # @param manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      # @return [Hash] empty result, or an `:error` hash when unsupported.
+      def self.handle_resources_subscribe(params, agent, manager)
+        return subscriptions_unsupported_error unless manager.respond_to?(:supported?) && manager.supported?
+        ok = manager.subscribe(
+          session_id: agent_session_id(agent),
+          uri:        params["uri"].to_s,
+          agent:      agent,
+        )
+        return {} if ok
+        # subscribe returned false: the session's listening stream was torn down
+        # (detach_listener) while the network subscribe was in flight, so no
+        # subscription exists and no notifications/resources/updated will arrive.
+        # Surface an error rather than a false empty-success ack (per the MCP
+        # contract an empty result == subscribed) so the client reopens its GET
+        # stream and retries instead of waiting forever for updates.
+        { error: { "code" => -32602,
+                   "message" => "resources/subscribe: the session no longer has an open " \
+                                "listening stream; reopen the GET stream and retry" } }
+      end
+      private_class_method :handle_resources_subscribe
+
+      # Handle `resources/unsubscribe` (MCP 2025-06-18). Idempotent — stops the
+      # LiveQuery subscription for the URI if one exists, returns an empty
+      # result regardless.
+      #
+      # @param manager [Parse::Agent::MCPSubscriptions::Manager, nil]
+      # @return [Hash] empty result, or an `:error` hash when unsupported.
+      def self.handle_resources_unsubscribe(params, agent, manager)
+        return subscriptions_unsupported_error unless manager.respond_to?(:supported?) && manager.supported?
+        manager.unsubscribe(
+          session_id: agent_session_id(agent),
+          uri:        params["uri"].to_s,
+        )
+        {}
+      end
+      private_class_method :handle_resources_unsubscribe
+
+      # The session identity used to key resource subscriptions. The transport
+      # populates `agent.correlation_id` from `Mcp-Session-Id`.
+      # @return [String, nil]
+      def self.agent_session_id(agent)
+        agent.respond_to?(:correlation_id) ? agent.correlation_id : nil
+      end
+      private_class_method :agent_session_id
+
+      # Error hash returned when a subscribe/unsubscribe arrives but this
+      # transport does not offer the capability. -32601 (method not found) is
+      # the correct code per JSON-RPC for an unoffered method.
+      # @return [Hash]
+      def self.subscriptions_unsupported_error
+        { error: { "code" => -32601, "message" => "Resource subscriptions are not supported by this server" } }
+      end
+      private_class_method :subscriptions_unsupported_error
+
       # Handle `prompts/list`.
       #
       # Delegates to `Parse::Agent::Prompts.list`, which returns an Array of