activeadmin_mcp 0.0.4 → 0.1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5eb6b95afa3bf6d96a2ae33ced52621014f535f11542dcbee38b88638580e6a9
-  data.tar.gz: c87121826ee5e29805cfa9f3fd8faf1f5042698ec94d46c5fbd7bbc90f08b3f3
+  metadata.gz: aac4aa9e2af5d377f711090b2e8adad79915844e26842733f5c8af6b02f37d7b
+  data.tar.gz: c418625d7b5bff3c9e555d0d248e098c08a8ac1a224644e900fa14fa3a95dfa7
 SHA512:
-  metadata.gz: 6b7a903b975a980a23246e944b2e321fab7019ac218c06a51f6645a5e0d7577951cb4bdce9c4319e7184d9b5f031b96320ee874666b8d28c1814850cb59533b9
-  data.tar.gz: 3a069d2f4d7a69038f3f96153e67911472f43fabb64aa4fc7a3ccdb421684cd6cabd126d208fbe9671dc1fa7c7ecc7f2789d68638f4e84cfdcb78e45d90ddb7b
+  metadata.gz: aea999468c061e6d532b0edb1e3241393a78dc34c1f94c0b07c2108431ab4370b4c89d45940a6691dce0ce5bfbc6903f92bc087457fc4d557fd70a97dacc9278
+  data.tar.gz: 588af72e3801e3c2c728d0407e217c7ebf54277d07a8dbdbd518fdbfe7e9cb335601cc3afe90cbcbbe76af40ef55b6bddde982ce11632107aca957875e34e464

data/README.md

@@ -20,7 +20,11 @@ The server is a Rails engine mounted inside your application (by default at
   are the ones you have already configured.
 - **Queries use Ransack.** The `query` tool passes its arguments straight to
   [Ransack](https://activerecord-hackery.github.io/ransack/), the same search
-  library ActiveAdmin uses for filtering.
+  library ActiveAdmin uses for filtering. The tool calls `ransack` on the
+  model directly rather than going through an ActiveAdmin filter form, so on
+  Ransack 4 the model must allowlist the attributes it wants queryable via
+  `ransackable_attributes`; without that allowlist, `query` against that
+  resource will raise instead of returning an empty result.
 - **Reads go through ActiveAdmin too.** `list_resources` and `query` run through
   the same authorization adapter (CanCanCan, Pundit, etc.) as the authenticated
   MCP user: resources the user cannot read are hidden from the listing and
@@ -28,18 +32,21 @@ The server is a Rails engine mounted inside your application (by default at
   `scope_collection`, so the MCP user only ever sees the records they could see
   in the admin UI. With ActiveAdmin's default adapter every check passes, so
   applications without an authorization adapter are unaffected.
-- **Writes go through ActiveAdmin.** The `update` tool only writes fields
-  allowed by the resource's `permit_params`, refuses resources that don't
-  register the `update` action, and runs every change through your
-  authorization adapter as the authenticated MCP user.
+- **Writes go through ActiveAdmin.** The `create` and `update` tools dispatch
+  the resource's real ActiveAdmin controller action, so `permit_params`, your
+  `before_save`/`after_update` callbacks, the controller's `before_action`
+  chain and your authorization adapter all apply exactly as they do when
+  someone clicks Save in the admin UI. Resources that don't register the
+  action are refused, and `describe_form` will tell a client what a given
+  resource's form accepts before it tries.
 - **Authentication is optional but built in.** Enable Bearer-token auth and the
   installer adds an "MCP Tokens" management page to your ActiveAdmin panel.
 
 ## Requirements
 
-- Ruby >= 3.0
-- Rails >= 6.1
-- ActiveAdmin >= 2.0
+- Ruby >= 4.0
+- Rails >= 7.2
+- ActiveAdmin ~> 3.5
 
 ## Installation
 
@@ -65,34 +72,230 @@ read/query setup without authentication.
 |------|-------------|
 | `list_resources` | List the ActiveAdmin resources the current user may read, along with their attributes. |
 | `query` | Query a resource the current user may read, using Ransack syntax, scoped to the records they may access (`limit` defaults to 25, capped at 100). |
-| `update` | Update an existing record, honouring ActiveAdmin's permitted params and authorization. |
+| `create` | Create a new record through the resource's ActiveAdmin create action, honouring its permitted params, callbacks and authorization. |
+| `update` | Update an existing record through the resource's ActiveAdmin update action, honouring its permitted params, callbacks and authorization. |
+| `describe_form` | Describe the fields of a resource's form — input types, labels, hints, allowed values, column types and which are required — so a `create` or `update` call need not guess them. |
+| *(per action)* | Any ActiveAdmin member, collection or batch action the application has opted in with an `mcp:` option, exposed as its own tool. |
+
+The examples below are drawn from the application the end-to-end suite builds
+and drives over HTTP, which is checked in under
+[`spec/e2e/fixture_app/`](spec/e2e/fixture_app/): `Post` permits `title` and
+`body` but not `slug`, `Author` is registered `actions :index, :show`, `Review`
+declares its own form block, and `Tag` declares no `permit_params` at all. Most
+of what this README claims is asserted against that running application in
+[`spec/e2e/`](spec/e2e/), so a claim here can be read next to the example that
+exercises it.
 
 ### Query examples
 
 ```
-Query users whose email contains "example.com"
-→ query(resource: "User", q: { email_cont: "example.com" })
+Find the post whose title mentions Earthsea
+→ query(resource: "Post", q: { title_cont: "Earthsea" })
 
-Find active posts created since the start of the month
-→ query(resource: "Post", q: { status_eq: "active", created_at_gt: "2026-08-01" })
+Find draft posts created since the start of the month
+→ query(resource: "Post", q: { status_eq: "draft", created_at_gt: "2026-08-01" })
+
+Look an author up by email
+→ query(resource: "Author", q: { email_eq: "ursula@example.com" })
 ```
 
-### Updating records
+### Creating and updating records
 
 ```
-Update a user's name
-→ update(resource: "User", id: 42, attributes: { name: "New name" })
+Create a post
+→ create(resource: "Post", attributes: { title: "Mort", body: "The fourth." })
+
+Retitle a post
+→ update(resource: "Post", id: 42, attributes: { title: "Pyramids" })
 ```
 
-The `update` tool applies the same rules as the ActiveAdmin UI:
+Both tools dispatch the resource's own ActiveAdmin `create` or `update`
+action, so a write from MCP is the same write the admin UI makes:
 
-- **Editable resources only** — resources registered without the `update`
-  action (e.g. `actions :index, :show`) are refused.
-- **Authorization** — the change runs through the resource namespace's
-  authorization adapter for the authenticated MCP user, so it can only update
-  what that user is allowed to update in admin.
+- **Registered actions only** — resources registered without the action
+  (e.g. `Author`, registered `actions :index, :show`) are refused.
+- **Authorization** — the write runs through the resource namespace's
+  authorization adapter for the authenticated MCP user, both before dispatch
+  and again inside the controller, so it can only write what that user is
+  allowed to write in admin.
 - **Permitted fields only** — attributes are filtered through the resource's
-  `permit_params`; fields the admin form doesn't accept are silently dropped.
+  `permit_params`; fields the admin form doesn't accept are silently dropped,
+  so a `slug` sent to a `Post` permitting only `title` and `body` never
+  reaches the record. A resource that declares no `permit_params` at all (like
+  `Tag`) is refused outright, with a message saying so — ActiveAdmin cannot
+  write such a resource through its own forms either.
+- **Your callbacks run** — ActiveAdmin's `before_build`, `before_create`,
+  `before_save`, `after_update` and friends all fire, because the controller
+  action is what fires them. A `before_create` that fills in a `slug` the form
+  never accepted still fills it in.
+
+A write rejected by the model comes back as a `Validation failed` error with
+the model's own messages in `details`, and nothing is written.
+
+### Describing a form
+
+```
+What can I set when writing a review?
+→ describe_form(resource: "Review")          # source: "form"
+
+What can I set when creating a post?
+→ describe_form(resource: "Post")            # source: "permit_params"
+→ describe_form(resource: "Post", action: "edit")
+```
+
+`describe_form` reads the resource's own `form do ... end` block when it
+declares one, reporting each input's `as:`, `label:`, `hint:` and — when the
+`collection:` is a literal array — its allowed values. `Review` declares one,
+so its `status` comes back as a `select` labelled "Moderation status" with
+`["pending", "approved"]` as its allowed values. Resources that declare
+no form block get a description derived from their `permit_params` instead:
+ActiveAdmin renders a bare `f.inputs` for those, which Formtastic only expands
+at render time, so there is nothing to read. The response's `source` says which
+of the two you are looking at.
+
+Either way every field is annotated from the model with the column type it is
+stored in and whether the model validates its presence. `has_many` blocks are
+reported under `nested` rather than flattened in with the record's own fields.
+
+`action:` selects the gate, not the shape — ActiveAdmin uses one form block for
+both. `"new"` (the default) requires the resource to register `create` and pass
+`create` authorization; `"edit"` requires `update`. Describing a form you could
+never submit tells you nothing you can act on, so it is refused with the same
+messages `create` and `update` use: `Author` is not creatable, and `Tag`
+declares no permitted params.
+
+Two limits worth knowing:
+
+- A `collection:` that is an `ActiveRecord::Relation` or a proc is omitted
+  rather than evaluated. Describing a form should not fire a query, and a
+  relation can be arbitrarily large. Use an action's
+  [`suggestions:`](#running-member-collection-and-batch-actions) when you want
+  dynamic values.
+- A field a form block declares but `permit_params` omits is described and then
+  silently dropped on write. This cannot arise on the `permit_params` fallback
+  path.
+
+### Running member, collection and batch actions
+
+ActiveAdmin actions are **not** exposed by default. An action becomes an MCP
+tool only when you add an `mcp:` option to it:
+
+```ruby
+ActiveAdmin.register Post do
+  member_action :publish, method: :post, mcp: {
+    description: "Publish a post with the given visibility",
+    params: {
+      visibility: { type: :string, required: true,
+                    enum: %w[public unlisted],
+                    hint: "Who can see the post once published" }
+    }
+  } do
+    # your existing action body, unchanged by opting in
+    resource.update!(status: params[:visibility])
+    redirect_to resource_path(resource), notice: "Published"
+  end
+
+  # No mcp: key, so this one is not a tool — not listed, and refused by name.
+  member_action :archive, method: :post do
+    resource.update!(status: "archived")
+    redirect_to resource_path(resource), notice: "Archived"
+  end
+end
+```
+
+That registers a `post_publish` tool, and no `post_archive` tool. Batch actions
+opt in the same way, and inherit their param types from the `form:` hash you
+already declare:
+
+```ruby
+batch_action :set_status, form: { status: :text },
+                          mcp: { description: "Set the status on the selected posts" } do |ids, inputs|
+  Post.where(id: ids).update_all(status: inputs["status"])
+end
+```
+
+That registers a `post_set_status` tool taking an `ids` array alongside the
+`status` string it took from `form:`.
+
+**Declaring params**
+
+- `type:` — one of `:string`, `:integer`, `:number`, `:boolean`, `:array`, `:object`.
+- `required:` — refuses the call when the value is missing.
+- `hint:` — static guidance shown to the agent. Always a plain string.
+- `enum:` — **binding**. A value outside the list is refused before dispatch.
+- `suggestions:` — a proc evaluated when tools are listed, e.g.
+  `suggestions: -> { Post.distinct.pluck(:status) }`. **Advisory only**, never
+  enforced, so use it for live values from the database. If it raises, the tool
+  is still listed without suggestions.
+
+On a batch action, every declared param must also appear in the action's `form:`
+hash. ActiveAdmin slices submitted inputs down to the declared `form:` keys
+before calling the block, so a param declared only under `mcp:` would be
+advertised to the client and then dropped; the declaration is refused instead.
+
+**Authorization**
+
+`permission:` is an *additional* gate, never a replacement. Every call first
+passes your ActiveAdmin authorization adapter exactly as `query` and `update`
+do; the proc can only narrow access further, never widen it. It is evaluated in
+controller context, so `current_admin_user`, `can?` and the usual admin helpers
+are available. Return `false` to refuse, or a `String` to refuse with a reason
+the agent can act on.
+
+```ruby
+# Takes the record, so it can only be resolved when the call arrives.
+member_action :feature, method: :post, mcp: {
+  description: "Feature a published post on the front page",
+  permission: ->(post) { post.status == "draft" ? "Only a published post can be featured" : true }
+} do
+  resource.update!(status: "featured")
+end
+
+# Takes no arguments, so it is resolved when tools are listed.
+collection_action :purge_drafts, method: :post, mcp: {
+  description: "Purge every draft post",
+  permission: -> { current_admin_user&.editor? }
+} do
+  redirect_to collection_path, notice: "Purged"
+end
+```
+
+Tools are also listed per user: an action whose resource the adapter refuses is
+left out of `tools/list` entirely, and a `permission:` proc that takes no
+arguments is evaluated at listing time (in the same controller context) so the
+tool is hidden rather than offered and then refused. A proc that takes the
+record cannot be resolved without one, so `post_feature` stays advertised and
+refuses at call time with the string the proc returned.
+
+For **batch actions** the adapter check is necessarily resource-level — there is
+no single record to authorize — so it is `authorized?(:<action>, YourModel)`
+rather than a per-record policy evaluation. To stop that being a hole, the ids
+the client submits are run back through the adapter's `scope_collection`, and
+the whole call is refused if any of them falls outside the scope. Nothing is
+narrowed silently: the call either acts on every id you asked for or on none.
+
+One caveat on authentication. Dispatch neutralises the namespace's
+`authentication_method` callback, because the MCP request has already
+authenticated by bearer token and that callback would otherwise redirect to a
+login page. If your `authentication_method` is a *combined* authentication-and-
+authorization method — one that also, say, rejects non-superusers — then
+neutralising it disables that authorization half too. Resource-level
+authorization still runs through the adapter, but the "we only skip
+authentication" framing is not universal; keep authorization in the adapter,
+not in the authentication callback.
+
+**What you get back**
+
+Actions are executed through your real ActiveAdmin controller, so the action's
+`before_action` chain, authorization and callbacks all run. The tool returns the
+response status, the redirect target and any flash messages — not the rendered
+HTML. An action whose body raises comes back as a generic `Post#publish failed`
+naming the resource and action, with the exception's own message — which can
+carry SQL, table names and file paths — kept away from the client.
+
+Redirect-style (submit-side) actions are the supported case; a `GET` action that
+renders a full admin view is best-effort and may fail for want of a view
+context.
 
 ## Connecting a client
 
@@ -231,16 +434,20 @@ npx @anthropic-ai/mcpb pack . ../activeadmin-mcp.mcpb
 ```
 
 That writes `activeadmin-mcp.mcpb` (a zip of `manifest.json`, `package.json` and
-`server/index.js`) to the repository root, ready to distribute. Bump `version`
-in **both** `mcpb/manifest.json` and `mcpb/package.json` before packing a
-release — Claude Desktop uses the manifest version to detect upgrades.
+`server/index.js`) to the repository root. You do not bump the bundle's
+`version` by hand: publishing a GitHub Release writes the release tag into
+`mcpb/manifest.json` and `mcpb/package.json`, packs the bundle from that, and
+attaches `activeadmin-mcp-<version>.mcpb` to the release — so the bundle
+version Claude Desktop uses to detect upgrades always matches the gem version.
+See [RELEASING.md](RELEASING.md).
 
-CI packs the bundle on every push and attaches it as a build artifact, so you
-can also download a build from the Actions tab rather than packing it yourself.
+So the bundle for any released version is on that release's page, and CI packs
+the bundle on every push and attaches it as a build artifact if you want an
+unreleased build from the Actions tab.
 
-Distribute the file however suits you: an internal file share, a GitHub release
-asset, or an S3 bucket. Anyone with the file can install it, but it is inert
-without a token.
+Distribute the file however suits you — pointing colleagues at the release
+asset, an internal file share, or an S3 bucket. Anyone with the file can
+install it, but it is inert without a token.
 
 ### Installing
 
@@ -284,7 +491,10 @@ installed bundle simply starts reporting an authentication failure.
 ## Configuration
 
 The generator writes an initializer to
-`config/initializers/activeadmin_mcp.rb`:
+`config/initializers/activeadmin_mcp.rb` carrying every option below,
+commented out. Running it with `--auth devise_token` uncomments the
+authentication method for you, so the first edit is usually just naming your
+Devise model:
 
 ```ruby
 ActiveadminMcp.configure do |config|
@@ -344,6 +554,44 @@ bundle install
 bundle exec rspec
 ```
 
+### Running the tests
+
+`bundle exec rspec` (or `rake spec`, the default rake task) runs the unit
+suite only — it's fast, and it's what CI's `rspec` job runs. It never touches
+`spec/e2e`; that directory is excluded via `.rspec`.
+
+The end-to-end suite lives in `spec/e2e` and runs separately:
+
+```bash
+bundle exec rake e2e
+```
+
+This generates a real Rails 7.2 + ActiveAdmin + Devise application under
+`tmp/e2e_app`, installs the gem into it with `path:`, boots it under Puma,
+and drives it over real HTTP with a minimal JSON-RPC client — the same way
+Claude Code or any other MCP client would. It's how the gem is tested
+against ActiveAdmin's and Ransack's actual behaviour rather than mocks.
+
+The registrations, models, migrations and seeds that application uses are
+checked in under [`spec/e2e/fixture_app/`](spec/e2e/fixture_app/) rather than
+written from heredocs, and they are the `Post`, `Author`, `Review` and `Tag`
+this README's examples are written against — so a claim above can be read next
+to both the registration it describes and the example that exercises it.
+[`spec/e2e/fixture_app/README.md`](spec/e2e/fixture_app/README.md) says which
+claim each fixture exists to support.
+
+The generated application is expensive to build (a full `bundle install`
+against rubygems.org, and a `gem install rails` if Rails 7.2.2.2 isn't
+already on your system) so it's cached in `tmp/e2e_app` between runs, keyed
+on the contents of `spec/e2e/support/app_builder.rb`. The first run costs a
+few minutes and needs network access; edit that file and the next run
+rebuilds from scratch, otherwise reruns are quick. Force a rebuild without
+editing anything by setting `E2E_REBUILD=1`:
+
+```bash
+E2E_REBUILD=1 bundle exec rake e2e
+```
+
 ## Contributing
 
 Bug reports and pull requests are welcome on GitHub.

data/app/controllers/activeadmin_mcp/mcp_controller.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 module ActiveadminMcp
   class McpController < ActionController::API
     before_action :authenticate_mcp_token!

data/app/models/activeadmin_mcp/api_token.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 require "digest"
 require "securerandom"
 

data/config/routes.rb

@@ -1,5 +1,3 @@
-# frozen_string_literal: true
-
 ActiveadminMcp::Engine.routes.draw do
   post "/", to: "mcp#call"
 end

data/lib/activeadmin_mcp/action_catalog.rb

@@ -0,0 +1,64 @@
+module ActiveadminMcp
+  # Finds every ActiveAdmin action an application has opted in to MCP.
+  #
+  # Nothing is cached: ActiveAdmin reloads resources in development, and a
+  # stale catalog would advertise tools that no longer exist.
+  module ActionCatalog
+    # Tool names the engine reserves for itself, including names Phase 2 and 3
+    # will take, so an application cannot silently shadow one later.
+    RESERVED = %w[list_resources query update create describe_form].freeze
+
+    class << self
+      def all
+        ResourceRegistry.resources.flat_map { |entry| definitions_for(entry[:config]) }
+      end
+
+      def find(tool_name)
+        all.find { |definition| definition.tool_name == tool_name }
+      end
+
+      private
+
+      def definitions_for(config)
+        candidates(config).filter_map do |action, kind|
+          definition = ActionDefinition.build(config: config, action: action, kind: kind)
+          next unless definition
+
+          next warn_and_skip(definition.errors.join("; ")) unless definition.valid?
+          next warn_and_skip("#{definition.tool_name} collides with a built-in tool") if reserved?(definition)
+
+          definition
+        end
+      end
+
+      def candidates(config)
+        pairs = []
+        pairs.concat(safe_actions(config, :member_actions).map { |a| [a, :member] })
+        pairs.concat(safe_actions(config, :collection_actions).map { |a| [a, :collection] })
+        pairs.concat(safe_actions(config, :batch_actions).map { |a| [a, :batch] }) if batch_enabled?(config)
+        pairs.select { |action, _kind| action.respond_to?(:mcp_options) }
+      end
+
+      def safe_actions(config, reader)
+        config.respond_to?(reader) ? Array(config.public_send(reader)) : []
+      end
+
+      # ActiveAdmin keeps registered batch actions even when the namespace has
+      # batch actions switched off, and hides them in the UI. Match that.
+      def batch_enabled?(config)
+        return false unless config.respond_to?(:batch_actions_enabled?)
+
+        config.batch_actions_enabled?
+      end
+
+      def reserved?(definition)
+        RESERVED.include?(definition.tool_name)
+      end
+
+      def warn_and_skip(message)
+        warn("[activeadmin_mcp] ignoring action: #{message}")
+        nil
+      end
+    end
+  end
+end

data/lib/activeadmin_mcp/action_definition.rb

@@ -0,0 +1,183 @@
+module ActiveadminMcp
+  # One ActiveAdmin action that an application has opted in to MCP, normalised
+  # so the rest of the engine does not care whether it came from a
+  # member_action, a collection_action or a batch_action.
+  #
+  # Batch actions are the special case: ActiveAdmin already knows their input
+  # names and widget types via `form:`, so those become param types and the
+  # `mcp:` declaration only layers descriptions and hints on top.
+  class ActionDefinition
+    KINDS = %i[member collection batch].freeze
+
+    # JSON Schema scalar types an application may declare.
+    TYPES = %i[string integer number boolean array object].freeze
+
+    # ActiveAdmin batch action form widgets -> JSON Schema types.
+    FORM_TYPES = {
+      text: :string,
+      string: :string,
+      select: :string,
+      datepicker: :string,
+      number: :number,
+      checkbox: :boolean,
+    }.freeze
+
+    attr_reader :config, :action, :kind, :errors
+
+    def self.build(config:, action:, kind:)
+      options = action.mcp_options
+      return nil unless options.is_a?(Hash)
+
+      new(config: config, action: action, kind: kind, options: options)
+    end
+
+    def initialize(config:, action:, kind:, options:)
+      @config = config
+      @action = action
+      @kind = kind
+      @options = options
+      @errors = []
+      validate!
+    end
+
+    def action_name
+      (@kind == :batch ? @action.sym : @action.name).to_sym
+    end
+
+    def resource_name
+      @config.resource_class.name
+    end
+
+    def tool_name
+      "#{resource_name.underscore.tr('/', '_')}_#{action_name}"
+    end
+
+    def description
+      @options[:description]
+    end
+
+    def permission
+      @options[:permission]
+    end
+
+    def http_verb
+      return :post if @kind == :batch
+
+      Array(@action.http_verb).first&.to_sym || :get
+    end
+
+    # Declared params, with batch actions inheriting their types from the
+    # ActiveAdmin `form:` hash underneath anything the declaration says.
+    def params
+      @params ||= inherited_params.merge(declared_params) do |_key, inherited, declared|
+        inherited.merge(declared)
+      end
+    end
+
+    def valid?
+      @errors.empty?
+    end
+
+    private
+
+    def declared_params
+      raw = @options[:params]
+      return {} unless raw.is_a?(Hash)
+
+      raw.each_with_object({}) { |(name, spec), acc| acc[name.to_sym] = spec }
+    end
+
+    def inherited_params
+      return {} unless @kind == :batch
+      return {} unless @action.respond_to?(:inputs)
+
+      form = @action.inputs
+      return {} unless form.is_a?(Hash)
+
+      form.each_with_object({}) do |(name, widget), acc|
+        acc[name.to_sym] = { type: FORM_TYPES.fetch(widget.to_sym, :string) }
+      end
+    end
+
+    def validate!
+      @errors << "#{tool_name}: mcp declaration needs a description" if description.to_s.strip.empty?
+      @errors << "#{tool_name}: unknown kind #{@kind}" unless KINDS.include?(@kind)
+
+      reserved = reserved_param_name
+      form_keys = batch_form_keys
+      params.each do |name, spec|
+        unless spec.is_a?(Hash)
+          @errors << "#{tool_name}: param #{name} must be a Hash"
+          next
+        end
+
+        @errors << "#{tool_name}: param #{name} is reserved" if name == reserved
+
+        # ActiveAdmin's own batch_action controller method slices the submitted
+        # inputs down to the keys of the batch action's `inputs` (its `form:`
+        # hash) before calling the block: `inputs.slice(*valid_keys)`. When
+        # there is no `form:` at all, `inputs` is nil, so `valid_keys` is nil,
+        # and `slice(*nil)` is `slice()` — which drops EVERY input, not none.
+        # So a form-less batch action permits nothing, and any declared param
+        # is a declaration error. A Proc form is evaluated by ActiveAdmin in
+        # controller context (MethodOrProcHelper.render_in_context), so we
+        # cannot know its keys here and skip the check rather than guess.
+        case form_keys
+        when :unknown_proc_form
+          nil
+        when :no_form
+          @errors << "#{tool_name}: param #{name} cannot be declared because this batch action " \
+                     "has no form: hash, so ActiveAdmin drops every input before the action runs"
+        when nil
+          nil # not a batch action, or no `inputs` method at all: no rule applies
+        else
+          unless form_keys.include?(name)
+            @errors << "#{tool_name}: param #{name} is not among the batch action's declared " \
+                       "form: keys, so ActiveAdmin would drop it before the action runs"
+          end
+        end
+
+        type = spec[:type]
+        @errors << "#{tool_name}: param #{name} has unknown type #{type}" if type && !TYPES.include?(type.to_sym)
+      end
+
+      @errors << "#{tool_name}: permission must be callable" if permission && !permission.respond_to?(:call)
+    end
+
+    # The permitted param keys for a batch action's `inputs` (its `form:`
+    # hash), distinguishing three outcomes the caller must treat differently:
+    #
+    # * not a batch action, or the action has no `inputs` method at all ->
+    #   nil, the batch form: rule does not apply.
+    # * `inputs` is a Hash -> its keys, the permitted set ActiveAdmin will
+    #   slice submitted params down to.
+    # * `inputs` is nil (no `form:` declared) -> :no_form. ActiveAdmin still
+    #   slices, against a nil key list, which yields an EMPTY permitted set
+    #   (`hash.slice(*nil)` is `hash.slice()` == `{}`), so every declared
+    #   param here is a declaration error.
+    # * `inputs` is a Proc -> :unknown_proc_form. ActiveAdmin evaluates it in
+    #   controller context via `render_in_context`, so we cannot know its
+    #   keys at declaration time. We skip the check rather than guess.
+    def batch_form_keys
+      return nil unless @kind == :batch
+      return nil unless @action.respond_to?(:inputs)
+
+      form = @action.inputs
+      return form.keys.map(&:to_sym) if form.is_a?(Hash)
+      return :unknown_proc_form if form.is_a?(Proc)
+
+      :no_form
+    end
+
+    def reserved_param_name
+      case @kind
+      when :member
+        :id
+      when :batch
+        :ids
+      else
+        nil
+      end
+    end
+  end
+end