Agent: security fixes, allowlist & new tools

Fixes hidden-class redaction for Parse-on-Mongo pointer storage forms and corrects agent_fields/enriched_schema case-mismatch by resolving allowlist entries through the class field_map; adds denylist for internal Parse fields. Introduces agent_join_fields and keys-on-include auto-projection with truncated_include_fields metadata to limit included row materialization. Adds pointer compaction for aggregate results (with compact_pointers: flag), high-level aggregation helpers (group_by, group_by_date, distinct) with dry_run support, and a lightweight discovery built-in (list_tools) plus tool categories and registry/category filtering. Adds agent_canonical_filter DSL and opt-out per-call, expands get_schema to include richer method/enum/allowlist metadata, provides structured AccessDenied details, and adds a MetadataAudit utility. Tests and docs updated to cover the new behaviors and features.

Author: AdrianCurtin

CHANGELOG.md

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    parse-stack (4.2.0)
+    parse-stack (4.2.1)
       activemodel (>= 6.1, < 9)
       activesupport (>= 6.1, < 9)
       faraday (~> 2.0)
@@ -28,9 +28,9 @@ GEM
       securerandom (>= 0.3)
       tzinfo (~> 2.0, >= 2.0.5)
       uri (>= 0.13.1)
-    ansi (1.5.0)
+    ansi (1.6.0)
     base64 (0.3.0)
-    bigdecimal (4.1.0)
+    bigdecimal (4.1.2)
     bson (5.2.0)
     builder (3.3.0)
     coderay (1.1.3)
@@ -43,7 +43,7 @@ GEM
     dotenv (3.2.0)
     drb (2.2.3)
     erb (6.0.4)
-    faraday (2.14.1)
+    faraday (2.14.2)
       faraday-net_http (>= 2.0, < 3.5)
       json
       logger
@@ -60,20 +60,20 @@ GEM
       prism (>= 1.3.0)
       rdoc (>= 4.0.0)
       reline (>= 0.4.2)
-    json (2.19.3)
+    json (2.19.5)
     logger (1.7.0)
     method_source (1.1.0)
-    minitest (6.0.3)
+    minitest (6.0.6)
       drb (~> 2.0)
       prism (~> 1.5)
     minitest-mock (5.27.0)
-    minitest-reporters (1.7.1)
+    minitest-reporters (1.8.0)
       ansi
       builder
-      minitest (>= 5.0)
+      minitest (>= 5.0, < 7)
       ruby-progressbar
     moneta (1.6.0)
-    mongo (2.23.0)
+    mongo (2.24.0)
       base64
       bson (>= 4.14.1, < 6.0.0)
     mustermann (3.1.1)
@@ -87,9 +87,10 @@ GEM
       prettyprint
     prettyprint (0.2.0)
     prism (1.9.0)
-    pry (0.14.2)
+    pry (0.16.0)
       coderay (~> 1.1)
       method_source (~> 1.0)
+      reline (>= 0.6.0)
     psych (5.3.1)
       date
       stringio
@@ -105,15 +106,15 @@ GEM
       rack (>= 3.0.0)
     rack-test (2.2.0)
       rack (>= 1.3)
-    rake (13.3.1)
+    rake (13.4.2)
     rdoc (7.2.0)
       erb
       psych (>= 4.0.0)
       tsort
     redcarpet (3.6.1)
     redis (5.4.1)
       redis-client (>= 0.22.0)
-    redis-client (0.27.0)
+    redis-client (0.29.0)
       connection_pool
     reline (0.6.3)
       io-console (~> 0.5)
@@ -134,7 +135,7 @@ GEM
       concurrent-ruby (~> 1.0)
     uri (1.1.1)
     webrick (1.9.2)
-    yard (0.9.42)
+    yard (0.9.43)
 
 PLATFORMS
   aarch64-linux-gnu

Gemfile.lock

@@ -4256,6 +4256,13 @@ result = agent.execute(:get_all_schemas)
 result = agent.execute(:query_class, class_name: "Song", limit: 10)
 result = agent.execute(:count_objects, class_name: "Song", where: { plays: { "$gte" => 1000 } })
 
+# High-level aggregation helpers (v4.2.1) — no pipeline authoring needed
+result = agent.execute(:group_by, class_name: "Song", field: "genre",
+                       sort: "value_desc", limit: 10)
+result = agent.execute(:group_by_date, class_name: "Song", field: "createdAt",
+                       interval: "day", timezone: "America/New_York")
+result = agent.execute(:distinct, class_name: "Song", field: "artist")
+
 # Ask natural language questions (requires LLM endpoint)
 response = agent.ask("How many songs have more than 1000 plays?")
 puts response[:answer]
@@ -4287,6 +4294,12 @@ class Song < Parse::Object
 
   property :title, :string, _description: "The song title"
   property :plays, :integer, _description: "Total play count"
+  property :is_removed, :boolean
+
+  # Per-class "valid state" predicate applied by default on every read tool
+  # (query_class, count_objects, aggregate). Opt out per-call with
+  # `apply_canonical_filter: false`.
+  agent_canonical_filter "isRemoved" => { "$ne" => true }
 
   # Expose methods with permission levels
   agent_readonly :find_popular, "Find songs with high play counts"

README.md

@@ -8,6 +8,7 @@
 require_relative "agent/errors"
 require_relative "agent/metadata_dsl"
 require_relative "agent/metadata_registry"
+require_relative "agent/metadata_audit"
 require_relative "agent/relation_graph"
 require_relative "agent/tools"
 require_relative "agent/constraint_translator"
@@ -267,6 +268,10 @@ def rack_app(**kwargs, &block)
         explain_query
         call_method
         export_data
+        group_by
+        group_by_date
+        distinct
+        list_tools
       ].freeze,
       write: %i[
         create_object
@@ -1179,7 +1184,8 @@ def execute(tool_name, **kwargs)
           payload[:success]     = false
           payload[:error_class] = e.class.name
           payload[:error_code]  = :access_denied
-          response = error_response(e.message, error_code: :access_denied)
+          details = e.respond_to?(:to_details) ? e.to_details : {}
+          response = error_response(e.message, error_code: :access_denied, details: details.any? ? details : nil)
 
           # Validation errors (e.g. from registered tool handlers or get_objects)
         rescue Parse::Agent::ValidationError => e
@@ -1280,9 +1286,11 @@ def execute(tool_name, **kwargs)
     # Get tool definitions in MCP/OpenAI function calling format
     #
     # @param format [Symbol] the output format (:mcp or :openai)
+    # @param category [String, Symbol, nil] optional category filter applied
+    #   on top of the permission-based allowlist. nil = no filter.
     # @return [Array<Hash>] array of tool definitions
-    def tool_definitions(format: :openai)
-      Parse::Agent::Tools.definitions(allowed_tools, format: format)
+    def tool_definitions(format: :openai, category: nil)
+      Parse::Agent::Tools.definitions(allowed_tools, format: format, category: category)
     end
 
     # Request options hash for Parse API calls
@@ -2128,7 +2136,7 @@ def append_log(entry)
       @operation_log.shift if @operation_log.size > @max_log_size
     end
 
-    def error_response(message, error_code: nil, retry_after: nil)
+    def error_response(message, error_code: nil, retry_after: nil, details: nil)
       entry = {
         error: message,
         error_code: error_code,
@@ -2138,8 +2146,9 @@ def error_response(message, error_code: nil, retry_after: nil)
       append_log(entry)
 
       response = { success: false, error: message }
-      response[:error_code] = error_code if error_code
+      response[:error_code]  = error_code if error_code
       response[:retry_after] = retry_after if retry_after
+      response[:details]     = details if details.is_a?(Hash) && details.any?
       response
     end
 

docs/mcp_guide.md

@@ -38,18 +38,55 @@ def initialize(tool_name, timeout)
     # `:access_denied` error_response without leaking the class name to
     # the wire beyond the sanitized message the caller used.
     class AccessDenied < AgentError
-      attr_reader :class_name
+      attr_reader :class_name, :kind, :denied_field, :allowed_fields, :suggested_rewrite
 
       # @param class_name [String, nil] the Parse class being refused. May be
       #   nil when the denial is not class-scoped (e.g., an env-gate refusal
       #   triggered by a `call_method` invocation of a :write method).
       # @param message [String, nil] optional override for the message. When
       #   not provided, a default "Class 'X' is not accessible to this agent"
       #   message is used.
-      def initialize(class_name = nil, message = nil)
-        @class_name = class_name.to_s
+      # @param kind [Symbol, nil] a finer-grained denial subcode. Lets MCP
+      #   consumers branch on the specific refusal reason without parsing
+      #   prose. Known values:
+      #     :hidden_class            — target class is `agent_hidden`
+      #     :field_denied            — projection/sort/match/expr field is
+      #                                outside the class's `agent_fields`
+      #                                allowlist
+      #     :storage_form_field_ref  — same as :field_denied but the
+      #                                offending name is the Parse-on-Mongo
+      #                                storage column (`_p_*`); the rewrite
+      #                                hint points at the bare pointer name
+      # @param denied_field [String, nil] the offending column / field name
+      #   when the refusal is field-scoped. Nil for class-scoped denials.
+      # @param allowed_fields [Array<String>, nil] the class's effective
+      #   `agent_fields` allowlist (capped for wire compactness). Nil when
+      #   the refusal is not field-scoped.
+      # @param suggested_rewrite [String, nil] a one-shot rewrite suggestion
+      #   the caller can apply to fix the request. Currently emitted for
+      #   storage-form references (e.g., "use `$author` instead of `$_p_author`").
+      def initialize(class_name = nil, message = nil,
+                     kind: nil, denied_field: nil, allowed_fields: nil,
+                     suggested_rewrite: nil)
+        @class_name        = class_name.to_s
+        @kind              = kind
+        @denied_field      = denied_field
+        @allowed_fields    = allowed_fields&.map(&:to_s)
+        @suggested_rewrite = suggested_rewrite
         super(message || "Class '#{@class_name}' is not accessible to this agent")
       end
+
+      # Structured details for the error_response payload. Returns a Hash
+      # with only the populated keys so the wire envelope doesn't carry
+      # unused nil fields.
+      def to_details
+        {
+          kind:              kind,
+          denied_field:      denied_field,
+          allowed_fields:    allowed_fields,
+          suggested_rewrite: suggested_rewrite,
+        }.compact
+      end
     end
 
     # Authentication failure for MCP transport adapters. Custom auth blocks

lib/parse/agent.rb

@@ -329,10 +329,20 @@ def self.handle_initialize(params)
 
       # Handle `tools/list`.
       #
+      # Accepts an optional non-standard `category` param (Parse Stack
+      # extension). Vanilla MCP clients omit it and receive the full
+      # allowed-tools list unchanged. Clients that know about the
+      # extension can pass a category string ("schema", "query",
+      # "aggregate", "mutation", "export", or any custom value) to
+      # filter the response server-side. Tool descriptors always carry
+      # `_meta.category` for client-side filtering as well.
+      #
+      # @param params [Hash] JSON-RPC params (optional `category`).
       # @param agent [Parse::Agent] used to retrieve allowed tool definitions.
       # @return [Hash] `{ "tools" => [...] }`
-      def self.handle_tools_list(_params, agent)
-        { "tools" => agent.tool_definitions(format: :mcp) }
+      def self.handle_tools_list(params, agent)
+        category = params.is_a?(Hash) ? params["category"] : nil
+        { "tools" => agent.tool_definitions(format: :mcp, category: category) }
       end
       private_class_method :handle_tools_list