parse-stack-next 5.7.6 → 5.8.1

data/docs/mcp_guide.md

@@ -396,6 +396,177 @@ Common uses for the direct dispatcher:
 
 ---
 
+## Deployment Patterns
+
+`MCPRackApp.new(agent_factory: ...)` accepts any factory. For the two common
+production shapes, two factories package the identity rules so a deployment
+cannot drift from one access mode into the other by accident:
+
+| Factory | Use it for | Identity | Data access |
+|---|---|---|---|
+| `MCPRackApp.user_scoped` | Personal assistants, application users | A Parse session token on every request; missing or invalid is 401 | The user's own ACL/CLP, enforced by Parse Server on REST and by the SDK on mongo-direct paths. No master-key fallback |
+| `MCPRackApp.master_analytics` | Analytics, reporting, trusted operational tools | A verified operator from a required `principal_resolver`; unresolved is 401 | Master authority, narrowed by the agent's `tools:`, `classes:`, `filters:`, and field policy. Read-only by default |
+
+Both factories take `agent_options:` (extra `Parse::Agent.new` options such
+as `tools:`, `methods:`, `classes:`, `filters:`) and pass the remaining
+keywords to `MCPRackApp.new` (`transport:`, `logger:`, `allowed_origins:`,
+...). Options that set identity or authority are refused in
+`agent_options:` with `ArgumentError` at construction: `session_token`,
+`acl_user`, `acl_role`, `impersonate_user`, `impersonation_user`,
+`impersonate_mint`, `impersonation_mint`, `impersonate_label`,
+`impersonation_label`, `tenant_id`, `client`, `permissions`, `permission`, and
+`parent`. `user_scoped` also refuses `master_atlas` and `allow_mutations`,
+since a signed-in user's agent never receives authority beyond its session.
+The factory owns the Rack options `agent_factory:`, `principal_resolver:`,
+`listening_stream_revalidator:`, and `listening_stream_revalidate_interval:`,
+so passing any of them is refused as well. A deliberate single-operator
+master-key endpoint is still built with `MCPRackApp.new` directly.
+
+### Personal assistant (user-scoped)
+
+```ruby
+# config/routes.rb (Rails), or `run` it from config.ru
+MCP_APP = Parse::Agent::MCPRackApp.user_scoped(
+  transport: :streamable_http,
+  permissions: :write,                       # writes still go only through agent_methods
+  tenant_from: ->(env, user_id) { Workspace.id_for_user(user_id) },  # pinned server-side
+  agent_options: { classes: %w[Post Comment], methods: %w[archive] },
+)
+mount MCP_APP, at: "/mcp"
+```
+
+```ruby
+# The only write this assistant can make, declared by the application.
+class Post < Parse::Object
+  property :archived, :boolean
+  property :archive_reason, :string
+
+  agent_method :archive, permission: :write, supports_dry_run: true, permitted_keys: [:reason]
+  def archive(reason:, agent: nil, dry_run: false, **)
+    return { would: "archive #{id}", reason: reason } if dry_run
+    self.archived = true
+    self.archive_reason = reason
+    save
+  end
+end
+
+# Require a human approval (MCP elicitation) before any :write call runs.
+Parse::Agent.require_approval_for = [:write]
+```
+
+The client sends the user's session token as `Authorization: Bearer
+<token>` (or `X-Parse-Session-Token`; pass `session_token_from: ->(env) {
+... }` for anything else). Every request builds a fresh
+`Parse::Agent.new(session_token: token, ...)`, so the agent acts as that user
+and tool arguments cannot change who it is or which tenant it is bound to.
+`tenant_from` returning nil refuses the request rather than running unscoped.
+
+On logout the token stops validating, so the next request gets 401 and any
+open listening stream closes within the revalidation interval. To reconnect,
+the client logs in again and starts a new MCP session (`initialize`) with the
+new token. A session id is bound to the principal that initialized it, so
+the new token cannot take over the old session, and the old session's
+subscriptions are torn down when its stream closes (or reaped as orphans,
+below).
+
+### Read-only analytics endpoint (master key)
+
+```ruby
+ANALYTICS = Parse::Agent::MCPRackApp.master_analytics(
+  # Required. Resolve the VERIFIED operator behind the request. Returning
+  # nil or "" refuses the request with 401.
+  principal_resolver: ->(_agent, env) { env["warden"]&.user&.email },
+  transport: :streamable_http,
+  agent_options: {
+    classes: %w[Post Subscription PostMetric],
+    tools: %w[query_class count_objects group_by group_by_date distinct aggregate get_schema],
+  },
+)
+
+# Audit: every tool call emits parse.agent.tool_call.
+ActiveSupport::Notifications.subscribe("parse.agent.tool_call") do |*, payload|
+  AuditLog.record(tool: payload[:tool], correlation_id: payload[:correlation_id])
+end
+```
+
+`principal_resolver:` is a required keyword: `master_analytics` raises
+`ArgumentError` at construction when it is missing or does not respond to
+`#call`. Without one every master-key agent has the same
+fingerprint, so two operators sharing the endpoint could attach to, approve,
+or cancel each other's sessions. The operator identity governs session
+ownership and audit; master authority governs what data the agent can reach,
+and the configured tools and classes govern what it may actually do. It
+defaults to `permissions: :readonly`.
+
+The master-key check runs per request, not at construction. The factory
+resolves its client on each request (the `client:` you passed, else
+`Parse.client` at that moment), and any request whose client has no master key
+is answered with 401. Construction succeeds even when the master key is not
+configured yet.
+
+### Session ownership
+
+Under both factories, an `Mcp-Session-Id` is bound to the principal that
+initialized it (the session token for `user_scoped`, the resolved operator for
+`master_analytics`). Another caller who knows or chooses the same id cannot:
+
+- re-initialize it (403),
+- attach its listening stream (403),
+- cancel its in-flight requests (`notifications/cancelled` is a silent 202 no-op),
+- answer its approval prompts (the elicitation reply is a silent 202 no-op),
+- change its log level.
+
+A session with an attached listening stream or a pending approval keeps its
+owner binding for as long as it is live. When the owner registry is full of
+live sessions, a new `initialize` or listening stream is refused with `503`
+rather than displacing one (see Capacity and eviction under the listening
+stream's owner binding, below).
+
+### Revocation intervals
+
+How quickly a logged-out, expired, or revoked session (or a role change)
+stops having effect, for a `user_scoped` deployment:
+
+| Path | `session_validation: :per_request` (default) | `session_validation: :cached` |
+|---|---|---|
+| New MCP request (any tool) | Next request: the token is re-checked against Parse Server (`GET /users/me`, response cache bypassed) | Identity-cache TTL (`identity_cache_ttl`, default 3600s), or immediately when the `Parse::Cache::Invalidation` `after_logout` / `_User` hooks evict the token |
+| REST tools within an accepted request | Immediate: Parse Server validates the token on every call | Immediate |
+| Mongo-direct reads (identity) | Next request: a failed check also evicts the token from `client.authorization` | Same as the row above |
+| Mongo-direct reads (role change) | Role-cache TTL (`role_cache_ttl`, default 30s), or immediately when the `_Role` invalidation hook fires | Same |
+| Open listening stream / subscriptions | Within `session_revalidate_interval` (default 60s): the stream is re-checked and closed, tearing down its LiveQuery subscriptions | Same (stream re-checks always ask Parse Server) |
+
+`:per_request` costs one `/users/me` call per MCP request; `:cached` saves it
+at the price of the identity-TTL window when invalidation hooks are not
+installed. The TTLs are configured with
+`Parse::Authorization.configure(identity_cache_ttl:, role_cache_ttl:)`.
+
+### Orphaned subscriptions
+
+A session that subscribes to resources but never opens its listening stream
+(or subscribes again after the stream closed) holds LiveQuery subscriptions
+with nowhere to deliver them. Normal teardown (unsubscribe, stream close,
+`DELETE`) does not cover that case, so the subscription manager reaps such
+sessions after a grace period: `orphan_ttl:` on
+`Parse::Agent::MCPSubscriptions::Manager` (default 300 seconds, `nil` to
+disable). Reaping runs whenever a session subscribes or attaches a stream,
+and can be triggered with `manager.reap_orphans!`. A session that attaches
+its stream within the grace period keeps its subscriptions.
+
+### Operational notes for deployment factories
+
+* **Validation load.** `user_scoped` with the default
+  `session_validation: :per_request` asks Parse Server (`GET /users/me`) on
+  every request, including requests carrying a random bearer string. Put a
+  `pre_auth_rate_limiter:` in front of a public endpoint, or use
+  `session_validation: :cached` and rely on the identity cache's TTL and
+  invalidation hooks.
+* **Outages fail closed.** A Parse Server error while validating a session is
+  treated as an invalid session: the request gets 401 and a listening stream
+  is closed at its next revalidation. Clients reconnect once Parse Server is
+  back.
+
+---
+
 ## Connecting Claude Desktop (stdio bridge)
 
 Parse Stack speaks MCP over **HTTP** (the standalone server and the
@@ -659,10 +830,36 @@ The principal fingerprint is derived, in order, from: an operator-supplied
 per-`MCPRackApp` instance and **single-process** — it does not span Puma workers
 or survive a restart. In a clustered deployment the `initialize` POST and the
 `GET` stream may land on different workers, so the initialize-binding degrades
-to TOFU there. The registry is LRU-bounded (default 10,000 sessions) so a stream
-of `initialize`-without-`DELETE` sessions cannot grow it without limit; evicting
-an active owner just downgrades that id to TOFU on its next attach. Blank
-session ids or blank fingerprints fail closed.
+to TOFU there. Blank session ids or blank fingerprints fail closed.
+
+**Capacity and eviction.** The registry is LRU-bounded (default 10,000
+sessions) so a stream of `initialize`-without-`DELETE` sessions cannot grow it
+without limit. Only idle bindings are evicted. A live session (one with an
+attached listening stream or a pending approval prompt) is pinned and keeps its
+owner binding under any amount of LRU pressure, so a flood of new sessions
+cannot strip a victim's owner and then answer its approvals or cancel its
+requests. An evicted idle id is unbound, and the next principal to attach a
+stream to it claims it TOFU. When every binding is live and the registry is
+full, new bindings are refused rather than displacing a live one: `initialize`
+and the listening-stream `GET` answer `503` (`-32000`, "Session capacity
+exhausted"). Clients retry once sessions close or are terminated with
+`DELETE`.
+
+**Per-principal bound.** Each principal may hold at most 100 session
+bindings. Past that, its own least recently used idle binding is evicted (or
+the new one refused with `503` when all of its bindings are live), so one
+caller flooding `initialize` cannot push other principals' sessions out of
+the registry. `initialize` and `resources/subscribe` are charged against the
+principal's rate limiter and answer `429` when it is exhausted; with
+`user_scoped` and `master_analytics` that limiter is shared across the
+principal's requests.
+
+**Requests on another principal's session.** Any POST whose `Mcp-Session-Id`
+is bound to a different principal is refused with `403`.
+`resources/subscribe` additionally requires a session the caller established,
+through `initialize` or by attaching its listening stream, because each
+subscription holds a LiveQuery socket and a slot in the global session limit.
+A stateless client that never initializes can still call tools.
 
 ---
 
@@ -683,6 +880,15 @@ The approval gate is a pluggable `agent.approval_gate` consulted inside
 unit-testable with a fake approver. `Parse::Agent::MCPElicitationGate` is the
 spec-native implementation; `Parse::Agent::NullGate` (the default) approves.
 
+A sub-agent built with `parent:` and no gate of its own uses its parent's gate,
+read at call time, so the gate the dispatcher installs on the parent for a
+`tools/call` also covers any sub-agent a tool builds during that call. Before
+5.8.1 a sub-agent fell back to `NullGate` and skipped approval. Assigning a
+gate on the sub-agent itself overrides this, and assigning `nil` removes the
+override so the sub-agent uses its parent's gate again. The dispatcher
+snapshots and restores the agent's own gate (`approval_gate_override`), so
+driving a sub-agent through `tools/call` never pins its parent's gate onto it.
+
 Round-trip over the streaming transport:
 
 1. A `tools/call` for a gated tier pauses before execution. The server builds an
@@ -847,6 +1053,51 @@ session's logs. `DELETE` on the session forgets it.
 
 ---
 
+## Server Field Names (`field_names: :server`)
+
+`Parse::Agent.new(field_names: :server)` asks for data fields in the exact
+names Parse returns or the model declares through its `field_map`
+(`createdAt`, `totalPlays`, an alias such as `ExternalID`), with no
+snake_case conversion anywhere a tool would otherwise apply one. Omit it (or
+pass `:default`) to keep each tool's existing output; any other value raises
+`ArgumentError`. Sub-agents inherit the mode unless they set their own.
+
+```ruby
+analytics = Parse::Agent.new(field_names: :server, permissions: :readonly)
+```
+
+| Output | Default | `field_names: :server` |
+|---|---|---|
+| `query_class` / `get_object` rows, Atlas and `semantic_search` source records, exports (CSV headers) | Parse field names | Parse field names (unchanged) |
+| A Parse object returned by an `agent_method` (`call_method`) | Parse field names and values | Parse field names and values |
+| An `AggregationResult` returned by an `agent_method` | snake_case keys | keys exactly as the aggregation returned them |
+
+Most tool output already carried server names, so the visible difference is
+in values an `agent_method` returns. Two `call_method` serialization fixes
+ship alongside: a returned Parse object is now emitted with its values (it
+previously emitted the model's field-type map, e.g. `"title" => "string"`),
+and a returned `AggregationResult` is emitted as a Hash (it was previously its
+`inspect` String).
+
+The option changes **data-field keys only**:
+
+* MCP protocol keys and SDK envelope keys (`chunks`, `documents`,
+  `object_id`, `next_call`, ...) keep their contracts.
+* Date, Pointer, and File formatting, vector visibility, and metadata
+  redaction are unchanged.
+* "Server names" means the application-facing Parse names, never raw MongoDB
+  storage columns such as `_p_author`, `_rperm`, or `_session_token`.
+* Explicit export column aliases still win over automatic naming.
+
+Naming is presentation only. ACL/CLP, `protectedFields`, the class
+`agent_fields` ceiling, and per-agent `fields:` policies resolve against the
+canonical field names before anything is formatted, so a user-scoped agent
+and a master-key agent with the same policy return the same fields in either
+mode. Like `fields:`, the mode is scoped to each tool call, so agents with
+different modes can run concurrently in one process.
+
+---
+
 ## Built-in Agent Hardening & Telemetry
 
 5.2 adds several agent-side controls, all configured on `Parse::Agent`:
@@ -1095,6 +1346,12 @@ MCPRackApp (per-request factory)
 
 The same problem exists in miniature whenever a tool handler constructs a sub-agent inside its block — a fresh `Parse::Agent.new` produces a fresh limiter, so an attacker who can induce delegation amplifies the per-process budget linearly with delegation depth × branching. The v4.2 `parent:` kwarg closes that case automatically (see [Per-Agent Tool Filtering & Sub-Agent Delegation](#per-agent-tool-filtering--sub-agent-delegation-v42)); the shared external limiter pattern below covers the cross-request case at the MCPRackApp boundary.
 
+### Deployment factories already share a limiter per principal
+
+`MCPRackApp.user_scoped` and `MCPRackApp.master_analytics` do not have this problem. Each keeps one in-process `RateLimiter` per principal (the validated user id for `user_scoped`, the resolved operator for `master_analytics`) and hands it to every agent it builds for that principal, so `rate_limit:` and `rate_window:` in `agent_options:` accumulate across requests. The registry is LRU-bounded (default 10,000 principals); an evicted principal starts a fresh window. Passing your own `rate_limiter:` in `agent_options:` bypasses the registry and uses that limiter as-is, which is the way to share one budget across processes.
+
+The workarounds below apply to a custom `agent_factory:` lambda (including `Parse::Agent.rack_app do |env| ... end`), which builds a fresh agent per request and gets no shared limiter unless you inject one.
+
 ### The solution
 
 Inject a shared, externally-stateful limiter:
@@ -1398,7 +1655,7 @@ agent = Parse::Agent.new(methods: [:archive, "Project.set_client_description"])
 agent = Parse::Agent.new(methods: { except: ["Account.delete_account"] })
 ```
 
-Entries are bare method names (`:archive` — matches the method on any class) or qualified names (`"Project.archive"` — matches only on that class). Both forms coexist in the same Set; matching is an OR.
+Entries are bare method names (`:archive`, which matches the method on any class) or qualified names (`"Project.archive"`, which matches only on that class). Both forms coexist in the same Set; matching is an OR. The class part is compared by its Parse class name, so `"User.reset"` and `"_User.reset"` name the same method (likewise `Role`, `Session`, and `Installation`), whichever spelling the entry or the `call_method` caller uses. An entry may also name the model by its Ruby constant (`"Artist.purge"` for `class Artist < Parse::Object; parse_class "Musician"; end`), which is compared by its Parse class name too. A qualified entry whose class resolves to no loaded model warns at construction and is matched by its class part as written. Before 5.8.1 an entry was matched against the raw string the caller passed, so `methods: { except: ["_User.reset"] }` could be bypassed by calling it on `"User"`.
 
 The filter **narrows declared methods** — it cannot expose a method that was not declared via the `agent_method` DSL, and it cannot bypass tier checks (`agent_can_call?`) or env-gates (`PARSE_AGENT_ALLOW_WRITE_TOOLS`, `PARSE_AGENT_ALLOW_SCHEMA_OPS`). A filtered-out invocation returns `error_code: :tool_filtered`.
 
@@ -1416,7 +1673,9 @@ class Project < Parse::Object
     # _wperm so the update only sees rows the agent's scope is allowed
     # to modify, defense-in-depth alongside Parse Server's own ACL.
     Audit.all(**agent.acl_scope_kwargs).each { |a| a.cancel! } if agent&.acl_scope
-    update!(archived_at: Time.now, archive_reason: reason)
+    self.archived = true              # property :archived, :boolean
+    self.archive_reason = reason      # property :archive_reason, :string
+    save
     { archived: true, objectId: id }
   end
 end
@@ -1464,7 +1723,7 @@ Parse::Agent.new(classes: { only: [Pots] }, strict_class_filter: true)  # per-in
 
 `except:` is never validated — an operator may proactively block a class not yet loaded.
 
-**Sub-agent inheritance: intersect, never widen.** Unlike `tools:` (where a sub-agent's filter overrides the parent's outright), `classes:` is **intersected** with the parent's effective set so a sub-agent can NEVER widen the parent's data reach. A child `only:` that has no overlap with the parent's `only:` raises `ArgumentError` at construction. A child that omits `classes:` inherits the parent's filter verbatim. `except:` sets are unioned (a sub-agent cannot un-deny a class the parent denied). The asymmetry with `tools:` is intentional — class reach is data scope, closer to `permissions:` than to the UX-scoping `tools:` filter.
+**Sub-agent inheritance: intersect, never widen.** Like `tools:` and `methods:`, `classes:` is **intersected** with the parent's effective set so a sub-agent can NEVER widen the parent's data reach. A child `only:` that has no overlap with the parent's `only:` raises `ArgumentError` at construction. A child that omits `classes:` inherits the parent's filter verbatim. `except:` sets are unioned (a sub-agent cannot un-deny a class the parent denied).
 
 **Schema-catalog filtering.** `get_all_schemas` omits classes outside the per-agent allowlist from the catalog response so the LLM doesn't waste a tool call discovering classes it would be refused on.
 
@@ -1543,6 +1802,7 @@ Parse::Agent::Tools.register(
 | `session_token` | Yes (security-critical) | Without it, a session-token parent silently produces a master-key sub-agent — the constructor default is `nil`, which means master-key mode. This was the v4.2 advisor-flagged blocker; do not undo. |
 | `acl_user` (v4.4.0) | Yes (security-critical) | When the parent was constructed with `acl_user:` and the child supplies none of `session_token:` / `acl_user:` / `acl_role:`, the parent's identity inherits verbatim. Inheritance is conditional on the child supplying NO identity at all — explicit overrides on the child resolve normally and then face the subset check below. |
 | `acl_role` (v4.4.0) | Yes (security-critical) | Same rule as `acl_user`. A child that omits identity inherits the parent's role scope; one that supplies its own identity falls through to the subset check. |
+| `master_atlas` | Yes (security-critical) | `nil` inherits the parent's setting and `false` drops it. `true` is accepted only when the parent has it: since 5.8.1 a sub-agent of a parent without `master_atlas` raises `ArgumentError`, because master-key faceting would return every row's buckets and results under the parent's scoped identity. |
 | `tenant_id` | Yes (security-critical) | Without it, a tenant-bound parent produces an unbound sub-agent that escapes `agent_tenant_scope` rules. |
 | `recursion_depth` | Always (decremented) | The parent's budget is authoritative — the explicit `recursion_depth:` kwarg is ignored on inherited construction. |
 
@@ -1552,12 +1812,74 @@ Parse::Agent::Tools.register(
 |-------|---------|
 | `permissions` | The default of `:readonly` means `Parse::Agent.new(parent: write_agent)` produces a `:readonly` sub-agent. A sub-agent is at most as privileged as the parent by tier; this is enforced by a clamp check at construction, not by inheritance. An explicit override is accepted only if `≤ parent.permissions` — `Parse::Agent.new(parent: readonly_parent, permissions: :admin)` raises `ArgumentError`. Pass `permissions: parent.permissions` to maintain parity intentionally. |
 | `client` | The constructor default `:default` resolves to the same client in standard single-app deployments. Explicit passes through. |
-| `tools:` / `methods:` filters | The whole point of constructing a sub-agent is usually to give it a NARROWER surface. Explicit passes through. |
+
+**`tools:` and `methods:` narrow only (5.8.1).** A sub-agent's `tools:` and `methods:` filters can only remove from what its parent allows. A child `tools: { only: }` is intersected with the parent's allowlist and `except:` sets are unioned; a child that omits `tools:` inherits the parent's filter. For `methods:`, the parent's filters stay in force alongside the child's, so a call must pass every one (entries may be bare or `Class.method`, which plain set intersection would match wrongly). A child `only:` list with nothing its parent allows (after the parent's allowlist and `except:` lists apply) raises `ArgumentError` at construction; an explicitly empty `only: []` is the strictest narrowing and is accepted. Before 5.8.1 a child's filter replaced the parent's, so a sub-agent could enable a tool or agent method within its tier that the parent was not given.
 
 **The clamp invariant:** `sub.permissions ≤ parent.permissions` always holds. The default `:readonly` is always safe regardless of parent tier; only explicit overrides hit the clamp check, and overrides that exceed the parent's tier raise at construction. This is the structural guarantee that a `delegate_to_subagent` chain cannot escape the parent's tier through sub-agent construction — the only path to a more-privileged agent is at the MCP factory, where the explicit elevation is auditable.
 
 **ACL-scope subset invariant (v4.4.0):** when the parent carries a resolved ACL scope (session_token / acl_user / acl_role), an explicit child override must resolve to a `permission_strings` set that is a SUBSET of the parent's. A tool handler that tries `Parse::Agent.new(parent: user_scoped, acl_role: "admin")` raises `ArgumentError` at construction because the child's claim set would include `"role:admin"`, which the parent's claim set does not. The same applies to a different `acl_user:` (different user_id), or to a child that resolves to master-key while the parent was scoped. This closes the analogous footgun for the acl_user / acl_role identity axis — the precedent of session_token swap is misleading because session tokens are externally verified by Parse Server, while `acl_user:` and `acl_role:` are unverified constructor assertions. A master-key parent (`@acl_scope.nil?`) allows any child scope because the parent already has unrestricted reach.
 
+### `fields:` per-agent field narrowing (5.8)
+
+A class's `agent_fields` is the most any agent may read. `fields:` narrows
+that ceiling for one agent, so two MCP deployments in the same process can
+expose different subsets of the same model: a user-facing assistant sees
+less than an analytics endpoint. Effective access is the intersection of the
+caller's Parse ACL/CLP, the class `agent_fields`, the agent's `fields:`
+policy, its tenant scope, and its tool and method filters.
+
+```ruby
+class Customer < Parse::Object
+  property :display_name, :string
+  property :timezone, :string
+  property :plan, :string
+  property :billing_email, :string
+  agent_fields :display_name, :timezone, :plan, :billing_email  # ceiling for every agent
+end
+
+assistant = Parse::Agent.new(session_token: token,
+                             fields: { Customer => %i[display_name timezone] })
+analytics = Parse::Agent.new(permissions: :readonly,
+                             fields: { Customer => %i[display_name plan] })
+```
+
+* **Narrow only.** A field outside `agent_fields` stays hidden even if a
+  policy lists it. A class without `agent_fields` is narrowed to exactly the
+  listed fields (plus `objectId`, `createdAt`, `updatedAt`).
+* **`default:`** narrows every class the policy does not name.
+* **Sub-agents intersect.** `Parse::Agent.new(parent: assistant, fields: ...)`
+  sees only fields both policies permit; omitting `fields:` inherits the
+  parent's policy.
+* **Everywhere the class allowlist applied.** Query projection, `keys:`,
+  include projections, aggregation pipelines, Atlas Search fields,
+  `get_schema` and `completion/complete` field names, exports,
+  `agent.describe`, and `semantic_search` chunk text, reranker input, and
+  filter fields all use the effective set.
+* **No inference through filters.** `query_class`, `count_objects`, and
+  `export_data` refuse a `where:` or `order:` on a field outside the
+  effective set with `:field_denied` (filtering or sorting on a hidden field
+  reveals it through which rows match). `group_by`, `distinct`, and
+  aggregation already refused. This also applies to the class ceiling with
+  no `fields:` policy.
+* **Writes stay on declared methods.** `fields:` governs what the agent
+  reads; writes still go through `agent_method`s and the per-agent
+  `methods:` filter.
+
+The policy is applied for the duration of each tool call (fiber-local), so
+agents serving concurrent requests never see each other's policy.
+
+**Known limits.**
+
+* `call_method` projects returned objects (anything carrying `className` and
+  `objectId`) through their class policy, but rows a method returns from its
+  own aggregation (`$group` output, `$lookup` documents) are the method
+  author's responsibility: the SDK cannot tell which class such a row came
+  from.
+* `get_schema` lists index keys and class-level permission entries that may
+  name fields outside the agent's policy (names only, never values).
+
+---
+
 ### Developer introspection — `agent.describe` / `describe_for` / `would_permit?` (v4.4.0)
 
 Three helpers on every agent for answering "why is this agent refusing this call?" and "what can this agent actually see?" without parsing audit payloads or tracing through tool implementations. NOT exposed to the LLM — operator-side observability only.
@@ -2474,6 +2796,7 @@ Every tool call dispatched through `Agent#execute` fires the `"parse.agent.tool_
 | `:tools_except` | Array<Symbol> | v4.3.0+ — when the agent was constructed with `tools: { except: [...] }`. |
 | `:methods_only` | Array<String> | v4.3.0+ — when the agent was constructed with `methods: { only: [...] }`. Bare names and `"Class.method"` qualified names mix. |
 | `:methods_except` | Array<String> | v4.3.0+ — when the agent was constructed with `methods: { except: [...] }`. |
+| `:methods_layers` | Array<Hash> | 5.8.1+, sub-agents that inherit at least one `methods:` filter (including a single parent layer when the sub-agent has none of its own). Every `methods:` filter in force, parent layers first and the agent's own last, each `{only:, except:}` with sorted name strings (nil when absent). `:methods_only` / `:methods_except` describe only the agent's own layer. `describe[:methods][:layers]` carries the same list. |
 | `:filters` | Hash<String,Array<String>> | v4.4.0+ — when the agent was constructed with `filters: {...}`. Maps each filtered class name (or `"default"`) to the list of FIELD NAMES the filter constrains. Filter VALUES are intentionally NOT echoed — `filters: { Account => { user_id: "abc123" } }` would otherwise emit the user-identifying value on every audit-log line. Subscribers that need the actual constraint can call `agent.filter_for(class_name)` directly. |
 | `:denial_kind` | Symbol | v4.3.0+, AccessDenied failure path only — one of `:hidden_class` (global `agent_hidden`), `:class_filter` (per-agent `classes:` narrowing), `:field_denied` (outside `agent_fields`), or `:storage_form_field_ref` (referenced `_p_*` pointer-storage column). Lets SOC tooling distinguish operator narrowing from policy-level denials without parsing the message prose. |
 
@@ -2483,7 +2806,7 @@ Every tool call dispatched through `Agent#execute` fires the `"parse.agent.tool_
 
   **Server-assigned on `initialize`:** when the client omits the header on the `initialize` request, `MCPRackApp` generates a UUID, binds it to `agent.correlation_id`, and returns it in the `Mcp-Session-Id` response header. Clients echo that id on subsequent requests. A client-supplied `Mcp-Session-Id` on `initialize` is echoed back unchanged; a factory-bound `correlation_id` always wins over both. Only the `initialize` response carries the header — non-init responses don't, so the id is never leaked on every reply. The SDK does not maintain a server-side session store: the id is best-effort correlation only (audit threading + cancellation routing), and a subsequent request carrying an "unknown" id is NOT refused.
 
-  **Session termination via `DELETE /`:** a `DELETE` carrying `Mcp-Session-Id` cancels every in-flight request registered under that correlation id and returns `204 No Content`. The header value is sanitized with the same regex as the request setter; missing or invalid values return `400`. The DELETE handler runs before the agent factory, so teardown traffic cannot force per-request agent construction.
+  **Session termination via `DELETE /`:** a `DELETE` carrying `Mcp-Session-Id` cancels every in-flight request registered under that correlation id and returns `204 No Content`. The header value is sanitized with the same regex as the request setter; missing or invalid values return `400`. Since 5.8, termination is gated like every other session operation: it passes the Origin policy, authenticates through the agent factory (`401` when the factory refuses), and is refused with `403` when the session is bound to a different principal. An unclaimed session can be terminated by any authenticated caller.
 
 - **Factory path (for application-bound sessions):** application code that already has an internal session identifier can override the client-supplied header by setting it inside the agent factory:
 

data/docs/mongodb_direct_guide.md

@@ -469,6 +469,33 @@ The `Parse::MongoDB.to_mongodb_date(value)` helper coerces `Date`,
 `DateTime`, `Time`, ISO 8601 strings, and Unix timestamps to a UTC `Time`
 suitable for matching.
 
+### MongoDB 9.0 null semantics
+
+MongoDB 9.0 changed how `null` comparisons treat a dotted path that runs
+through an array. When the path resolves to no non-null value (the field is
+an empty array, an array of scalars, or contains a nested array), it now
+compares equal to `null`. For `{ meta: [] }` or `{ meta: [1] }`,
+`{ "meta.owner": null }` now matches and `{ "meta.owner": { $ne: null } }` no
+longer does. `$exists` is unchanged, and `$lookup` equality follows the new
+rule. This applies to REST queries (Parse Server passes them to MongoDB) and
+mongo-direct queries alike.
+
+The SDK never adds a `null` comparison on a dotted path by itself; ACL
+scoping only checks the top-level `_rperm`. It compiles one only when you
+name a dotted field. Which constraints are affected:
+
+| Constraint on a dotted field | Compiles to | Changed in 9.0 |
+|---|---|---|
+| `:"meta.owner" => nil` | `{ "meta.owner": null }` | Yes |
+| `:"meta.owner".not => nil`, `.null => false` | `{ $ne: null }` | Yes |
+| `:"meta.owner".in => [nil, ...]` | `{ $in: [null, ...] }` | Yes |
+| `:"meta.items".empty_or_nil`, `.not_empty` | pipeline with `$eq` / `$ne: null` | Yes |
+| `:"meta.owner".null => true`, `.exists => false` | `{ $exists: false }` | No |
+
+If a dotted path in your queries can traverse an array, review those
+queries before upgrading, or use `.exists` when you mean "the field is
+present".
+
 ---
 
 ## Pointer joins and `parse_reference`

data/docs/usage_guide.md

@@ -118,6 +118,44 @@ Song.query.aggregate([
 ])
 ```
 
+### Field names in aggregation results
+
+Custom aggregation rows (`$group`, `$project`, ...) come back as
+`Parse::AggregationResult`. By default `#to_h` converts field names to
+snake_case symbols. Pass `field_names: :server` to `#results` to keep the
+names exactly as the aggregation returned them (5.8):
+
+```ruby
+agg = Song.query.aggregate([
+  { "$group" => { "_id" => "$genre", "totalPlays" => { "$sum" => "$plays" } } },
+])
+
+row = agg.results.first
+row.to_h          # => { _id: "Rock", total_plays: 500 }   (default)
+
+row = agg.results(field_names: :server).first
+row.to_h          # => { "_id" => "Rock", "totalPlays" => 500 }
+row["totalPlays"] # => 500
+row.total_plays   # => 500 (a snake_case name still resolves when it matches one key)
+```
+
+In `:server` mode keys are Strings, nested values are untouched, and keys
+whose snake_case forms collide all survive. A name that is itself a key always
+wins: with both `"totalPlays"` and `"total_plays"` stored, `row.total_plays`
+reads `"total_plays"`. A snake_case name that is not itself a key but matches
+more than one key (`"totalPlays"` and `"TotalPlays"` both stored) is
+ambiguous: the method form (`row.total_plays`) raises `ArgumentError` naming
+the candidates instead of guessing, and `row["total_plays"]` returns nil. Read
+such a field by its exact key. Parse::Object rows are unaffected; `#as_json` already
+returns their server field names. This is a presentation option only, and it
+is separate from:
+
+* `#raw`, which returns the unwrapped Hash exactly as received;
+* `Parse::Query.field_formatter`, which controls how field names in OUTGOING
+  queries are compiled, not response keys;
+* the REST aggregate `raw_field_names:` / `raw_values:` flags, which change
+  what Parse Server itself returns (and are never enabled by `field_names:`).
+
 ## Transactions
 
 ```ruby