parse-stack-next 5.7.6 → 5.8.0

data/lib/parse/agent/tools.rb

@@ -823,8 +823,10 @@ module Parse
               fields: {
                 type: "array",
                 items: { type: "string" },
-                description: "Optional. Restrict search to these fields. When omitted, all indexed fields are " \
-                             "searched. Subject to the class's agent_fields allowlist when one is declared.",
+                description: "Optional. Restrict search to these fields. When omitted, the fields this agent " \
+                             "may read are searched (every indexed field only when the class declares no " \
+                             "agent_fields). A session-scoped search on a class with protected fields must name " \
+                             "fields, and may not name a protected one.",
               },
               limit: {
                 type: "integer",
@@ -1243,6 +1245,18 @@ module Parse
         #   its declared timeout (handled by Agent#execute and the approval
         #   preview, which both rescue it).
         def invoke(agent, name, **kwargs)
+          # Every tool runs with the agent's per-agent `fields:` narrowing in
+          # scope, so each allowlist check (MetadataRegistry.field_allowlist)
+          # resolves to the effective set for THIS agent.
+          # The agent's data-field naming mode (Parse::Agent::FieldNames) is
+          # scoped the same way; it changes presentation only.
+          Parse::Agent::FieldPolicy.with(agent) do
+            Parse::Agent::FieldNames.with(agent) { invoke_unscoped(agent, name, **kwargs) }
+          end
+        end
+
+        # @!visibility private
+        def invoke_unscoped(agent, name, **kwargs)
           sym = name.to_sym
           entry = REGISTRY_MUTEX.synchronize { @registry[sym] }
 
@@ -2031,16 +2045,24 @@ module Parse
       #
       # Raises `Parse::Agent::AccessDenied` on any breach. The `Agent#execute`
       # rescue chain translates that to `error_code: :access_denied`.
+      #
+      # @return [Array<String>, nil] the fields a result row may carry when
+      #   the source document reaches the output (no stage replaced the
+      #   schema), for {project_aggregate_rows}; nil when no projection is
+      #   needed (no `agent_fields`, or every output field was computed by a
+      #   validated stage).
       def enforce_pipeline_access_policy!(class_name, pipeline, agent: nil)
-        return unless pipeline.is_a?(Array)
+        return nil unless pipeline.is_a?(Array)
         source_permitted = compute_source_allowlist_for(class_name)
-        walk_pipeline_with_state!(
+        available, source_addressable = walk_pipeline_with_state!(
           pipeline,
           source_permitted: source_permitted,
           available: [],
           source_addressable: true,
           agent: agent,
         )
+        return nil if source_permitted.nil? || !source_addressable
+        source_permitted | available
       end
 
       module_function :enforce_pipeline_access_policy!
@@ -2058,6 +2080,26 @@ module Parse
 
       module_function :compute_source_allowlist_for
 
+      # @api private
+      # Drop top-level keys outside `permitted` from aggregation rows whose
+      # source document passed through unreplaced. Checking the fields a
+      # pipeline REFERENCES is not enough: `[{ "$limit" => 1 }]` references
+      # nothing and returns every column. A `_p_<field>` storage key is kept
+      # when `<field>` is permitted, and `_id` / `objectId` always are.
+      def project_aggregate_rows(rows, permitted)
+        return rows if permitted.nil?
+        keep = permitted.map(&:to_s) | %w[_id objectId]
+        Array(rows).map do |row|
+          next row unless row.is_a?(Hash)
+          row.select do |key, _|
+            k = key.to_s
+            keep.include?(k) || (k.start_with?("_p_") && keep.include?(k.delete_prefix("_p_")))
+          end
+        end
+      end
+
+      module_function :project_aggregate_rows
+
       # @api private
       # Forward-pass walker. Maintains two pieces of state across stages:
       #   * `available` — fields introduced by upstream stages (Array<String>)
@@ -2088,6 +2130,7 @@ module Parse
             available = (available | introduced)
           end
         end
+        [available, source_addressable]
       end
 
       module_function :walk_pipeline_with_state!
@@ -2364,6 +2407,38 @@ module Parse
             # MetadataRegistry.field_allowlist already merges in
             # ALWAYS_KEEP_FIELDS (objectId / createdAt / updatedAt), so a
             # join can carry the standard envelope without further work.
+            # Join keys are reads too: joining on a hidden field and counting
+            # the matches reveals its values even when the output is
+            # projected away afterward. Source-side keys and `let`/
+            # `startWith` expressions use the source allowlist; foreign-side
+            # keys (and `restrictSearchWithMatch`) use the joined class's.
+            if value.is_a?(Hash)
+              opts = value.transform_keys(&:to_s)
+              foreign_permitted = target_str ? compute_source_allowlist_for(target_str) : nil
+              if permitted_fields
+                %w[localField].each do |key|
+                  next unless opts[key]
+                  root = join_key_root(opts[key])
+                  unless permitted_fields.include?(root)
+                    raise_allowlist_refusal!("join field", opts[key].to_s, root, permitted_fields)
+                  end
+                end
+                opts["let"].each_value { |e| check_expression_for_restricted_fields!(e, permitted_fields) } if opts["let"].is_a?(Hash)
+                check_expression_for_restricted_fields!(opts["startWith"], permitted_fields) if opts.key?("startWith")
+              end
+              if foreign_permitted
+                %w[foreignField connectFromField connectToField].each do |key|
+                  next unless opts[key]
+                  root = join_key_root(opts[key])
+                  unless foreign_permitted.include?(root)
+                    raise_allowlist_refusal!("join field", opts[key].to_s, root, foreign_permitted)
+                  end
+                end
+                if opts["restrictSearchWithMatch"].is_a?(Hash)
+                  check_match_keys_for_restricted_fields!(opts["restrictSearchWithMatch"], foreign_permitted)
+                end
+              end
+            end
             sub = value.is_a?(Hash) ? (value["pipeline"] || value[:pipeline]) : nil
             if sub
               # The lookup sub-pipeline runs against the FOREIGN class's
@@ -2503,6 +2578,20 @@ module Parse
 
       module_function :walk_pipeline_stage!
 
+      # @api private
+      # Root field of a join key in Parse terms. Joins are written against
+      # stored documents, so `_id`, `_created_at`, `_updated_at`, and a
+      # `_p_<pointer>` column name the objectId, timestamps, and pointer.
+      JOIN_STORAGE_NAMES = { "_id" => "objectId", "_created_at" => "createdAt",
+                             "_updated_at" => "updatedAt" }.freeze
+
+      def join_key_root(key)
+        root = key.to_s.split(".").first.to_s
+        JOIN_STORAGE_NAMES.fetch(root) { root.delete_prefix("_p_") }
+      end
+
+      module_function :join_key_root
+
       # @api private
       # Walk a $match hash refusing field keys outside the allowlist.
       # Logical operators ($and/$or/$nor/$not) recurse. $expr expressions
@@ -2541,7 +2630,22 @@ module Parse
       def check_expression_for_restricted_fields!(expr, permitted_fields)
         case expr
         when String
-          if expr.start_with?("$") && !expr.start_with?("$$")
+          if expr.start_with?("$$")
+            # `$$ROOT` and `$$CURRENT` are the whole document: `$$ROOT.secret`
+            # is `$secret`, and a bare `$$ROOT` copies every field. Other
+            # system and user variables (`$$NOW`, `$$this`, `let` names) do
+            # not address the source document.
+            var, path = expr.delete_prefix("$$").split(".", 2)
+            if %w[ROOT CURRENT].include?(var)
+              ref = path.to_s.split(".").first
+              if ref.nil? || ref.empty?
+                raise_allowlist_refusal!("field reference", expr, "$$#{var}", permitted_fields)
+              end
+              unless permitted_fields.include?(ref)
+                raise_allowlist_refusal!("field reference", expr, ref, permitted_fields)
+              end
+            end
+          elsif expr.start_with?("$")
             ref = expr.sub(/\A\$/, "").split(".").first
             return if ref.empty? || ref.start_with?("$")
             unless permitted_fields.include?(ref)
@@ -3185,6 +3289,17 @@ module Parse
                              order: nil, keys: nil, include: nil,
                              apply_canonical_filter: true, format: nil, **_kwargs)
         assert_class_accessible!(class_name, agent: agent, op: :find)
+        # Hidden-field inference: the caller's own where:/order: may only
+        # reference readable fields. Filtering or sorting on a field outside
+        # the effective agent_fields allowlist reveals its value through
+        # which rows match or how they are ordered. Checked on the CALLER's
+        # constraints, before the server-owned tenant / per-agent /
+        # canonical constraints are merged in.
+        assert_where_fields_in_allowlist!(class_name, where)
+        assert_fields_in_allowlist!(class_name, order_field_names(order).map { |f| wire_field_path(class_name, f) })
+        # Send the names that were checked: `email` resolves to the declared
+        # column it was validated as, never to a same-named hidden column.
+        order = wire_order(class_name, order)
         limit = [limit || Agent::DEFAULT_LIMIT, Agent::MAX_LIMIT].min
 
         # Tenant scope enforcement: resolve before any query building so that
@@ -3255,7 +3370,7 @@ module Parse
         # This blocks dangerous operators like $where, $function
         translated_where = nil
         if effective_where && !effective_where.empty?
-          translated_where = ConstraintTranslator.translate(effective_where, agent)
+          translated_where = ConstraintTranslator.translate(effective_where, agent, class_name)
           query[:where] = translated_where.to_json
         end
 
@@ -3343,6 +3458,9 @@ module Parse
       # @return [Hash] count result
       def count_objects(agent, class_name:, where: nil, apply_canonical_filter: true, **_kwargs)
         assert_class_accessible!(class_name, agent: agent, op: :count)
+        # Hidden-field inference: a count over a hidden field's values is an
+        # oracle for that field, same as a filtered query.
+        assert_where_fields_in_allowlist!(class_name, where)
         # Tenant scope enforcement. TRACK-AGENT-7 split: per-agent filter is
         # UNCONDITIONAL, canonical filter is LLM-controllable.
         scope = resolve_tenant_scope!(agent, class_name)
@@ -3354,7 +3472,7 @@ module Parse
 
         translated_where = nil
         if effective_where && !effective_where.empty?
-          translated_where = ConstraintTranslator.translate(effective_where, agent)
+          translated_where = ConstraintTranslator.translate(effective_where, agent, class_name)
           query[:where] = translated_where.to_json
         end
 
@@ -3440,7 +3558,7 @@ module Parse
             else
               { "$and" => [composed_filter, { "objectId" => object_id }] }
             end
-          translated_combined = ConstraintTranslator.translate(combined_where, agent)
+          translated_combined = ConstraintTranslator.translate(combined_where, agent, class_name)
           rows = if agent.respond_to?(:acl_scope_requires_direct?) && agent.acl_scope_requires_direct?
               execute_find_via_direct(
                 agent, class_name,
@@ -3465,7 +3583,7 @@ module Parse
           # The three-layer ACL simulation in Parse::MongoDB.aggregate
           # ensures the row is only returned when the agent's scope
           # permits it.
-          where_id = ConstraintTranslator.translate({ "objectId" => object_id }, agent)
+          where_id = ConstraintTranslator.translate({ "objectId" => object_id }, agent, class_name)
           rows = execute_find_via_direct(
             agent, class_name,
             where: where_id, limit: 1,
@@ -3574,7 +3692,7 @@ module Parse
         base_in_where = { "objectId" => { "$in" => unique_ids } }
         composed = apply_per_agent_filter_to_where(base_in_where, class_name, agent: agent)
         composed = apply_canonical_filter_to_where(composed, class_name, agent: agent) if apply_canonical_filter
-        translated_where = ConstraintTranslator.translate(composed, agent)
+        translated_where = ConstraintTranslator.translate(composed, agent, class_name)
 
         # Build query
         query = {
@@ -3686,7 +3804,7 @@ module Parse
         effective_where = apply_canonical_filter_to_where(effective_where, class_name, agent: agent)
         translated_where = nil
         if effective_where && !effective_where.empty?
-          translated_where = ConstraintTranslator.translate(effective_where, agent)
+          translated_where = ConstraintTranslator.translate(effective_where, agent, class_name)
           query[:where] = translated_where.to_json
         end
 
@@ -3760,7 +3878,7 @@ module Parse
         # class's agent_fields allowlist on projection-style stages
         # ($project, $addFields, $set, $unset, $replaceRoot). Without this
         # the top-level assert_class_accessible! check is bypassable.
-        enforce_pipeline_access_policy!(class_name, pipeline, agent: agent)
+        output_fields = enforce_pipeline_access_policy!(class_name, pipeline, agent: agent)
 
         # Auto-rewrite LLM-style $lookup stages into Parse-on-Mongo column
         # form AFTER access policy has run on the LLM's original (logical)
@@ -3877,6 +3995,7 @@ module Parse
           # placeholder) and not silently surfaced into the pointer_classes
           # envelope map.
           results = redact_hidden_classes!(results, agent: agent)
+          results = project_aggregate_rows(results, output_fields)
 
           # Pointer-column compaction. Default-on: a typical aggregate over
           # a class with a high-cardinality pointer (e.g. author per row)
@@ -3986,6 +4105,7 @@ module Parse
         formatted_value = value_field ? resolve_aggregation_field(class_name, validate_group_field!(value_field, name: :value_field)) : nil
 
         pipeline = build_group_pipeline(
+          class_name: class_name,
           where: where,
           group_field: formatted_group,
           flatten_arrays: flatten_arrays,
@@ -4082,6 +4202,7 @@ module Parse
 
         date_expr = build_date_group_expression(formatted_field, interval_sym, tz)
         pipeline = build_group_pipeline(
+          class_name: class_name,
           where: where,
           group_field: nil,
           group_expression: date_expr,
@@ -4150,6 +4271,7 @@ module Parse
 
         formatted_field = resolve_aggregation_field(class_name, validated_field)
         pipeline = build_group_pipeline(
+          class_name: class_name,
           where: where,
           group_field: formatted_field,
           flatten_arrays: false,
@@ -4311,13 +4433,113 @@ module Parse
       def assert_where_fields_in_allowlist!(class_name, where)
         return unless where.is_a?(Hash) && !where.empty?
         allowlist = MetadataRegistry.field_allowlist(class_name)
-        return if allowlist.nil? || allowlist.empty?
-        permitted = allowlist.map(&:to_s) | MetadataRegistry::ALWAYS_KEEP_FIELDS
-        check_match_keys_for_restricted_fields!(where, permitted)
+        if allowlist && allowlist.any?
+          permitted = allowlist.map(&:to_s) | MetadataRegistry::ALWAYS_KEEP_FIELDS
+          # Compare the names ConstraintTranslator will actually send:
+          # `play_count` and `created_at` are permitted as `playCount` and
+          # `createdAt`, and a `_p_` storage prefix is stripped.
+          check_match_keys_for_restricted_fields!(normalize_where_keys(class_name, where), permitted)
+        end
+        # Embedded subqueries are validated against their OWN target class,
+        # whether or not the outer class declares an allowlist.
+        assert_subquery_fields_in_allowlist!(where)
       end
 
       module_function :assert_where_fields_in_allowlist!
 
+      # @api private
+      # A copy of `where` whose field keys (top level and inside
+      # `$and`/`$or`/`$nor`/`$not`) are rewritten to their wire names, the way
+      # ConstraintTranslator resolves them: the class's `field_map` entry or
+      # an exact declared server name, else lowerCamelCase. A `_p_` storage
+      # prefix is stripped. Operator keys and values are left alone; this is
+      # used only to compare against the allowlist.
+      def normalize_where_keys(class_name, where)
+        case where
+        when Hash
+          where.each_with_object({}) do |(key, value), out|
+            ks = key.to_s
+            if %w[$and $or $nor].include?(ks)
+              out[ks] = Array(value).map { |sub| normalize_where_keys(class_name, sub) }
+            elsif ks == "$not"
+              out[ks] = normalize_where_keys(class_name, value)
+            elsif ks.start_with?("$")
+              out[ks] = value
+            else
+              out[wire_field_path(class_name, ks)] = value
+            end
+          end
+        else
+          where
+        end
+      end
+
+      module_function :normalize_where_keys
+
+      # @api private
+      # Wire form of a (possibly dotted) field path: the root segment is
+      # resolved like a property name, the rest is kept.
+      def wire_field_path(class_name, path)
+        root, rest = path.to_s.sub(/\A_p_/, "").split(".", 2)
+        wire = MetadataRegistry.wire_field_names(class_name, [root]).first || root
+        rest ? "#{wire}.#{rest}" : wire
+      end
+
+      module_function :wire_field_path
+
+      # @api private
+      # Walk a where: Hash for embedded subqueries (`$inQuery`, `$notInQuery`,
+      # `$select`, `$dontSelect`) and validate each one's predicates (and a
+      # `$select` key) against the target class's effective allowlist. An
+      # equivalent subquery must not reach a field a direct query on that
+      # class would be refused, or the subquery becomes an oracle for it.
+      # Class accessibility of the embedded className is enforced separately
+      # by ConstraintTranslator.
+      def assert_subquery_fields_in_allowlist!(node)
+        case node
+        when Hash
+          node.each do |key, value|
+            case key.to_s
+            when "$inQuery", "$notInQuery"
+              next unless value.is_a?(Hash)
+              target = value["className"] || value[:className]
+              inner = value["where"] || value[:where]
+              assert_where_fields_in_allowlist!(target.to_s, inner) if target
+            when "$select", "$dontSelect"
+              next unless value.is_a?(Hash)
+              query = value["query"] || value[:query] || {}
+              target = query["className"] || query[:className]
+              next unless target
+              assert_where_fields_in_allowlist!(target.to_s, query["where"] || query[:where])
+              selected = value["key"] || value[:key]
+              assert_fields_in_allowlist!(target.to_s, [selected]) if selected
+            when "$relatedTo"
+              # The relation column lives on the OWNING object's class, so
+              # `count_objects(_User, $relatedTo: {object: Post#X, key:
+              # "flaggedBy"})` would reveal a relation hidden from Post's
+              # allowlist unless the key is checked against that class.
+              next unless value.is_a?(Hash)
+              # Resolve the owner the way the translator does (a pointer Hash,
+              # a Parse::Pointer, or a "Class$id" string).
+              owner_class = ConstraintTranslator.send(:related_to_owning_class, value)
+              relation_key = value["key"] || value[:key]
+              if relation_key && (owner_class.nil? || owner_class.to_s.empty?)
+                raise Parse::Agent::AccessDenied.new(
+                  nil, "$relatedTo requires a resolvable owning-object class.", kind: :field_denied,
+                )
+              end
+              assert_fields_in_allowlist!(owner_class.to_s, [relation_key]) if relation_key
+            else
+              assert_subquery_fields_in_allowlist!(value)
+            end
+          end
+        when Array
+          node.each { |item| assert_subquery_fields_in_allowlist!(item) }
+        end
+      end
+
+      module_function :assert_subquery_fields_in_allowlist!
+
       # @api private
       # Verify each referenced field is within agent_fields (or the
       # always-keep set) when an allowlist is declared on the class.
@@ -4329,15 +4551,42 @@ module Parse
           root = raw.to_s.sub(/\A_p_/, "").split(".").first
           next if root.nil? || root.empty?
           unless permitted.include?(root)
-            raise Parse::Agent::AccessDenied.new(
-              build_allowlist_refusal("field", raw.to_s, root, permitted),
-            )
+            # raise_allowlist_refusal! carries kind/denied_field/allowed_fields
+            # as structured attributes. Passing the refusal Hash positionally
+            # (as this did before 5.8) landed it in the class-name slot, so the
+            # message was a stringified Hash and `kind` was lost.
+            raise_allowlist_refusal!("field", raw.to_s, root, permitted)
           end
         end
       end
 
       module_function :assert_fields_in_allowlist!
 
+      # @api private
+      # Field names an `order:` value sorts on. Accepts Parse REST form
+      # ("-createdAt,title"), an Array of such entries, or nil.
+      def order_field_names(order)
+        return [] if order.nil?
+        Array(order).flat_map { |entry| entry.to_s.split(",") }
+                    .map { |f| f.strip.sub(/\A[-+]/, "") }
+                    .reject(&:empty?)
+      end
+
+      module_function :order_field_names
+
+      # @api private
+      # `order` rewritten to wire names, keeping each key's `-`/`+` prefix:
+      # `"-play_count,title"` becomes `"-playCount,title"`.
+      def wire_order(class_name, order)
+        return order if order.nil?
+        Array(order).flat_map { |entry| entry.to_s.split(",") }.map(&:strip).reject(&:empty?).map do |key|
+          sign = key[/\A[-+]/].to_s
+          "#{sign == "-" ? "-" : ""}#{wire_field_path(class_name, key.delete_prefix(sign))}"
+        end.join(",")
+      end
+
+      module_function :wire_order
+
       # @api private
       # Resolve a wire-format field name to its MongoDB aggregation form.
       # Pointer fields are auto-prefixed with `_p_` when the local Parse
@@ -4370,10 +4619,10 @@ module Parse
       # nil we emit a bare $group with only _id (distinct).
       def build_group_pipeline(where:, group_field:, flatten_arrays:,
                                accumulator_op:, value_field:, operation:,
-                               group_expression: nil, agent: nil)
+                               group_expression: nil, agent: nil, class_name: nil)
         pipeline = []
         if where.is_a?(Hash) && !where.empty?
-          pipeline << { "$match" => ConstraintTranslator.translate(where, agent) }
+          pipeline << { "$match" => ConstraintTranslator.translate(where, agent, class_name) }
         end
         if flatten_arrays && group_field
           pipeline << { "$unwind" => "$#{group_field}" }
@@ -4772,6 +5021,17 @@ module Parse
 
       # @api private
       def export_via_query(agent, class_name:, where:, keys:, include:, order:, limit:, skip: nil, scope: nil)
+        # Hidden-field inference: the caller's own where:/order: may only
+        # reference readable fields. Filtering or sorting on a field outside
+        # the effective agent_fields allowlist reveals its value through
+        # which rows match or how they are ordered. Checked on the CALLER's
+        # constraints, before the server-owned tenant / per-agent /
+        # canonical constraints are merged in.
+        assert_where_fields_in_allowlist!(class_name, where)
+        assert_fields_in_allowlist!(class_name, order_field_names(order).map { |f| wire_field_path(class_name, f) })
+        # Send the names that were checked: `email` resolves to the declared
+        # column it was validated as, never to a same-named hidden column.
+        order = wire_order(class_name, order)
         # Reuse query_class's gates by routing through it directly.
         # query_class returns a ResultFormatter-wrapped hash; we want the raw rows.
         query = {}
@@ -4817,7 +5077,7 @@ module Parse
         effective_where = apply_canonical_filter_to_where(effective_where, class_name, agent: agent)
         translated_where = nil
         if effective_where && !effective_where.empty?
-          translated_where = ConstraintTranslator.translate(effective_where, agent)
+          translated_where = ConstraintTranslator.translate(effective_where, agent, class_name)
           query[:where] = translated_where.to_json
         end
 
@@ -4844,7 +5104,7 @@ module Parse
       # @api private
       def export_via_aggregate(agent, class_name:, pipeline:, scope: nil)
         PipelineValidator.validate!(pipeline)
-        enforce_pipeline_access_policy!(class_name, pipeline, agent: agent)
+        output_fields = enforce_pipeline_access_policy!(class_name, pipeline, agent: agent)
         assert_joins_tenant_safe!(pipeline, scope)
         # Prepend tenant scope $match before per-agent + canonical filter and auto-limit.
         scoped_pipeline = apply_tenant_scope_to_pipeline(pipeline, scope)
@@ -4883,7 +5143,7 @@ module Parse
           end
         end
 
-        redact_hidden_classes!(rows, agent: agent)
+        project_aggregate_rows(redact_hidden_classes!(rows, agent: agent), output_fields)
       end
 
       module_function :export_via_aggregate
@@ -5075,6 +5335,9 @@ module Parse
       # @return [Hash] query explanation
       def explain_query(agent, class_name:, where: nil, **_kwargs)
         assert_class_accessible!(class_name, agent: agent, op: :find)
+        # Explain stats (nReturned) answer yes/no for any predicate, so a
+        # hidden field must not be addressable here either.
+        assert_where_fields_in_allowlist!(class_name, where)
         # No direct-MongoDB equivalent of Parse Server's REST explain
         # plan exists today, and routing this through master-key REST
         # under an acl_user/acl_role agent would silently bypass the
@@ -5100,7 +5363,7 @@ module Parse
         effective_where = apply_canonical_filter_to_where(effective_where, class_name, agent: agent)
 
         if effective_where && !effective_where.empty?
-          query[:where] = ConstraintTranslator.translate(effective_where, agent).to_json
+          query[:where] = ConstraintTranslator.translate(effective_where, agent, class_name).to_json
         end
 
         response = agent.client.find_objects(class_name, query, **agent.request_opts)
@@ -5475,7 +5738,7 @@ module Parse
       # @return [Hash, nil]
       def run_explain(agent, class_name, where)
         query = { explain: true, limit: 1 }
-        query[:where] = ConstraintTranslator.translate(where, agent).to_json
+        query[:where] = ConstraintTranslator.translate(where, agent, class_name).to_json
         response = agent.client.find_objects(class_name, query, **agent.request_opts)
         return nil unless response.success?
         response.result
@@ -5687,10 +5950,29 @@ module Parse
       # also packs a reference to the assignee `_User`) would otherwise
       # leak fields the conversational `query_class` tool would refuse
       # to return.
+      #
+      # A returned Parse::Object is serialized from `as_json`, which carries
+      # its values under the Parse (wire) field names, including explicit
+      # `field_map` aliases and nested JSON verbatim. Before 5.8 this read
+      # `result.attributes`, which is the model's field TYPE map, so a
+      # method returning an object emitted `{ "title" => :string }` instead
+      # of its data. An AggregationResult (e.g. a method returning
+      # `query.aggregate(...).results`) is emitted as a Hash: snake_case keys
+      # by default, the aggregation's own keys under `field_names: :server`.
+      # Before 5.8 it was emitted as its `inspect` String.
       def serialize_result(result, agent: nil)
         formatted = case result
           when Parse::Object
-            project_object_to_allowlist(result.parse_class, ResultFormatter.format_object(result.parse_class, result.attributes)[:object])
+            project_object_to_allowlist(result.parse_class, ResultFormatter.simplify_object(result.as_json))
+          when Parse::AggregationResult
+            source = Parse::Agent::FieldNames.server? ? result.raw : result.to_h
+            row = source.each_with_object({}) { |(k, v), h| h[k.to_s] = serialize_result(v, agent: agent) }
+            # A row is a computed shape with no owning class, so it cannot be
+            # projected through an allowlist; Parse Server's internal columns
+            # (`_rperm`, `_hashed_password`, `_auth_data_*`, ...) are removed
+            # from it at every depth, as on every other aggregation path.
+            Parse::PipelineSecurity.redact_internal_fields_deep!(row)
+            row
           when Array
             result.map { |item| serialize_result(item, agent: agent) }
           when Hash
@@ -5700,7 +5982,30 @@ module Parse
           else
             result.to_s
           end
-        redact_hidden_classes!(formatted, agent: agent)
+        redact_hidden_classes!(project_embedded_objects(formatted), agent: agent)
+      end
+
+      # @api private
+      # Project every embedded Parse object in a formatted result through
+      # its OWN class's effective allowlist (class `agent_fields` narrowed by
+      # the executing agent's `fields:` policy). A method may return an
+      # object whose included children, or a plain Hash holding object JSON,
+      # carry fields the caller may not read; projecting only the top-level
+      # class would leak them. An embedded object is any Hash carrying a
+      # `className`, saved or not: an unsaved object has no `objectId` but
+      # still holds field values. A bare pointer keeps only its className,
+      # `__type`, and `objectId`, so projecting it is harmless.
+      def project_embedded_objects(value)
+        case value
+        when Hash
+          class_name = value["className"] || value[:className]
+          projected = class_name ? project_object_to_allowlist(class_name.to_s, value) : value
+          projected.each_with_object({}) { |(k, v), acc| acc[k] = project_embedded_objects(v) }
+        when Array
+          value.map { |item| project_embedded_objects(item) }
+        else
+          value
+        end
       end
 
       # @api private
@@ -5799,6 +6104,15 @@ module Parse
         limit = clamp_atlas_limit(limit)
         auth = atlas_auth_options!(agent, tool: :atlas_text_search)
         fields_norm = normalize_atlas_fields_with_allowlist!(class_name, fields)
+        # Hidden-field inference: the caller's filter may only address
+        # readable fields, and with no `fields:` the text search defaults to
+        # the readable fields rather than every field (`wildcard: "*"`), so
+        # neither which rows match nor their rank depends on a hidden field.
+        assert_where_fields_in_allowlist!(class_name, filter) if filter.is_a?(Hash)
+        fields_norm ||= readable_atlas_text_fields(class_name)
+        # An empty field list means `wildcard: "*"` to Atlas Search, which
+        # would let hidden fields decide matches; refuse instead.
+        refuse_empty_readable_text_fields!(class_name, fields_norm)
 
         # TRACK-AGENT-6 / TRACK-AGENT-7 fix: per-agent filter is
         # UNCONDITIONAL; canonical filter is LLM-controllable via
@@ -5911,9 +6225,19 @@ module Parse
           # Parse::AtlasSearch::FacetedSearchNotACLSafe); pass master:
           # true unconditionally here, since the agent-level gate
           # above already enforced master_atlas?.
+          readable = readable_atlas_text_fields(class_name)
+          facet_opts = {}
+          # A non-empty query searches only readable fields (never a
+          # wildcard across hidden ones) when an allowlist applies.
+          if readable && !query.to_s.strip.empty?
+            refuse_empty_readable_text_fields!(class_name, readable)
+            facet_opts[:fields] = readable
+          end
+          # Parse::AtlasSearch is loaded on first use, not with the agent.
+          require_relative "../atlas_search"
           result = Parse::AtlasSearch.faceted_search(
             class_name, query.to_s, facets,
-            limit: limit, master: true,
+            limit: limit, master: true, **facet_opts,
             # Master mode still has to name its application: the binding
             # guard compares the client, not the posture, and an unnamed
             # caller is refused once two applications are in play.
@@ -6063,7 +6387,7 @@ module Parse
       def fetch_call_method_receiver(agent, klass, class_name, object_id)
         scope = resolve_tenant_scope!(agent, class_name)
         result = if agent.respond_to?(:acl_scope_requires_direct?) && agent.acl_scope_requires_direct?
-            where_id = ConstraintTranslator.translate({ "objectId" => object_id }, agent)
+            where_id = ConstraintTranslator.translate({ "objectId" => object_id }, agent, class_name)
             rows = execute_find_via_direct(agent, class_name, where: where_id, limit: 1)
             rows && rows.first
           else
@@ -6196,6 +6520,27 @@ module Parse
       module_function :compose_atlas_filter
 
       # @api private
+      # @api private
+      # The fields an Atlas text search may run over when the caller named
+      # none: the effective allowlist minus the always-keep system fields,
+      # or nil when no allowlist applies (the wildcard is then harmless).
+      def readable_atlas_text_fields(class_name)
+        allowlist = Parse::Agent::MetadataRegistry.field_allowlist(class_name)
+        return nil if allowlist.nil? || allowlist.empty?
+        allowlist.map(&:to_s) - Parse::Agent::MetadataRegistry::ALWAYS_KEEP_FIELDS
+      end
+
+      # @api private
+      def refuse_empty_readable_text_fields!(class_name, fields)
+        return unless fields.is_a?(Array) && fields.empty?
+        raise Parse::Agent::AccessDenied.new(
+          class_name,
+          "No readable fields to text-search on class '#{class_name}' under this agent's field policy.",
+          kind: :field_denied,
+          allowed_fields: Parse::Agent::MetadataRegistry.field_allowlist(class_name)&.map(&:to_s),
+        )
+      end
+
       def assert_atlas_field_allowed!(class_name, field_name, kind:)
         name = field_name.to_s
         allowlist = Parse::Agent::MetadataRegistry.field_allowlist(class_name)
@@ -6251,6 +6596,10 @@ module Parse
       # carry implementation details (toggle names, internal stage
       # ordering) that aren't useful in an LLM tool-call response.
       def invoke_atlas_search(op, class_name, query, opts, **extra)
+        # Parse::AtlasSearch is loaded on first use, not with the agent. Load
+        # it before the body runs so the rescue clauses below can resolve
+        # its error classes.
+        require_relative "../atlas_search"
         case op
         when :search
           Parse::AtlasSearch.search(class_name, query, **opts)