actionagent 1.5.2 → 1.6.2

data/app/models/action_agent/agent_run.rb

@@ -3,6 +3,10 @@
 module ActionAgent
   class AgentRun < ApplicationRecord
     belongs_to :agent
+    # The version of the agent this run executed under — the latest at the
+    # time, since a run is against the agent as it is.
+    belongs_to :agent_version, optional: true
+    before_create { self.agent_version_id ||= agent&.latest_version&.id }
 
     # Raised when a caller hands a run files to attach in a host app that
     # has nowhere to keep them.
@@ -20,6 +24,55 @@ module ActionAgent
     # --skip-active-storage has no has_many_attached to call.
     has_many_attached :attachments if defined?(ActiveStorage)
 
+    # The key the caller's identity is recorded under in +input_params+.
+    # Underscored so it cannot collide with a provider override, and
+    # stripped from anything a client sends (see Api::AgentsController).
+    ACTOR_PARAM = "_actor_gid"
+
+    # +input_params+ with the caller recorded alongside them.
+    #
+    # The actor is stored as a Global ID rather than as the record, so the
+    # worker that picks the run up — on another machine, minutes later —
+    # authorizes as the same person who asked for the run. A caller the host
+    # cannot address that way (a plain object, a service account) is simply
+    # not recorded: the run then executes unattributed, which a host scope
+    # reads as "no access", rather than executing as somebody else.
+    #
+    # @param params [Hash] the run's own parameters
+    # @param actor [Object, nil] the caller
+    # @return [Hash]
+    def self.params_with_actor(params, actor)
+      params = (params || {}).to_h.except(ACTOR_PARAM, ACTOR_PARAM.to_sym)
+      gid = actor.respond_to?(:to_global_id) ? actor.to_global_id.to_s : nil
+      gid ? params.merge(ACTOR_PARAM => gid) : params
+    rescue StandardError => e
+      Rails.logger.warn("[AgentRun] could not record the run's actor: #{e.class} - #{e.message}")
+      params
+    end
+
+    # The caller this run executes on behalf of.
+    #
+    # Set in memory for a synchronous run; rehydrated from the stored Global
+    # ID for one picked up by a worker. A Global ID that no longer resolves
+    # (the user was deleted) yields nil, so the run loses access rather than
+    # inheriting someone else's.
+    # @return [Object, nil]
+    def actor
+      return @actor if defined?(@actor)
+
+      @actor = locate_actor
+    end
+
+    attr_writer :actor
+
+    # Whether this run knows who it is for. A run with a recorded actor that
+    # no longer resolves is *not* unattributed — it is broken, and callers
+    # that care can tell the two apart.
+    # @return [Boolean]
+    def actor_recorded?
+      input_params.is_a?(Hash) && input_params[ACTOR_PARAM].present?
+    end
+
     # Whether runs can carry files in this host app: Active Storage loaded,
     # the macro applied, and its tables migrated. Never raises — a host
     # that skipped `rails active_storage:install` still runs agents, it
@@ -220,6 +273,16 @@ module ActionAgent
 
     private
 
+    def locate_actor
+      return nil unless actor_recorded?
+      return nil unless defined?(GlobalID::Locator)
+
+      GlobalID::Locator.locate(input_params[ACTOR_PARAM])
+    rescue StandardError => e
+      Rails.logger.warn("[AgentRun] could not resolve the run's actor: #{e.class} - #{e.message}")
+      nil
+    end
+
     def set_trace_id
       self.trace_id ||= SecureRandom.uuid
     end

data/app/models/action_agent/agent_version.rb

@@ -9,6 +9,9 @@ module ActionAgent
 
     # Scopes
     scope :recent, -> { order(version_number: :desc) }
+    # Versions cut from the agent's code on deploy, as opposed to edits made
+    # in the dashboard.
+    scope :releases, -> { where.not(release_digest: [ nil, "" ]) }
     scope :by_version, ->(num) { where(version_number: num) }
 
     # Compare two versions
@@ -36,6 +39,13 @@ module ActionAgent
     end
 
     # Check if this is the latest version
+    # Whether this version was cut from the agent's code (it carries the
+    # release digest) rather than from a dashboard edit.
+    # @return [Boolean]
+    def release?
+      release_digest.present?
+    end
+
     def latest?
       agent.latest_version&.id == id
     end

data/app/models/action_agent/evaluation.rb

@@ -35,6 +35,17 @@ module ActionAgent
 
     scope :recent, -> { order(updated_at: :desc) }
 
+    # MySQL cannot give a JSON column a default, so a row inserted there
+    # without `criteria` or `config` reads back nil. Both readers answer with
+    # the empty value the column default supplies on other databases.
+    def criteria
+      super || []
+    end
+
+    def config
+      super || {}
+    end
+
     def latest_run
       evaluation_runs.order(created_at: :desc).first
     end

data/app/models/action_agent/evaluation_run.rb

@@ -8,6 +8,10 @@ module ActionAgent
   # See #average_score, which is what has to tolerate both shapes.
   class EvaluationRun < ApplicationRecord
     belongs_to :evaluation
+    # The version of the evaluated agent this run scored, so a pass rate is
+    # a statement about a release rather than about "the agent".
+    belongs_to :agent_version, optional: true
+    before_create { self.agent_version_id ||= evaluation&.agent&.latest_version&.id }
     has_many :scenario_results, class_name: "EvaluationScenarioResult", dependent: :destroy
 
     enum :status, { pending: 0, running: 1, complete: 2, failed: 3 }

data/app/models/action_agent/telemetry_trace.rb

@@ -43,6 +43,8 @@ module ActionAgent
     scope :for_date_range, ->(start_date, end_date) { where(timestamp: start_date..end_date) }
     # The dashboard agent this trace was attributed to on ingest, if any.
     belongs_to :agent, class_name: "ActionAgent::Agent", optional: true
+    # The release of the agent this trace came from (see #attach_agent_version!).
+    belongs_to :agent_version, class_name: "ActionAgent::AgentVersion", optional: true
 
     scope :for_account, ->(account) { where(account: account) if ActionAgent.multi_tenant? }
 
@@ -252,7 +254,10 @@ module ActionAgent
       # dashboard-authored agent by guessing a primary key.
       attrs[:agent_id] = agent&.id
 
-      create!(attrs).tap { |record| AgentRegistrar.call(record) }
+      create!(attrs).tap do |record|
+        AgentRegistrar.call(record)
+        record.attach_agent_version!
+      end
     end
 
 
@@ -265,6 +270,28 @@ module ActionAgent
       tokens.fetch("input", 0).to_i + tokens.fetch("output", 0).to_i + tokens.fetch("thinking", 0).to_i
     end
 
+    # Pins this trace to the version of its agent that produced it. The
+    # instrumentation stamps the root span with `agent.version` — the digest
+    # ActiveAgent::Release computes from the class — and a release cut on
+    # deploy carries the same digest, so the two meet here. A trace from a
+    # dashboard run carries no digest and takes the agent's latest version.
+    #
+    # @return [AgentVersion, nil]
+    def attach_agent_version!
+      return if agent_version_id.present? || agent_id.blank?
+
+      digest = root_span&.dig("attributes", "agent.version").presence
+      version = if digest
+        AgentVersion.find_by(agent_id: agent_id, release_digest: digest)
+      else
+        AgentVersion.where(agent_id: agent_id).order(version_number: :desc).first
+      end
+      return unless version
+
+      update_columns(agent_version_id: version.id)
+      version
+    end
+
     # Returns the root span of this trace.
     #
     # @return [Hash, nil] The root span or nil

data/app/services/action_agent/agent_execution_service.rb

@@ -45,6 +45,13 @@ module ActionAgent
       new(agent_record, run).call
     end
 
+    # Tool-call keywords that name the caller. The model's arguments and the
+    # run's actor share one keyword namespace by the time they reach a tool,
+    # so anything a model emits under these names is dropped before the call:
+    # an actor a model can name is not an authorization boundary, and the
+    # documents a model reads are attacker-reachable.
+    ACTOR_KEYWORDS = %i[actor current_user].freeze
+
     def initialize(agent_record, run)
       @agent_record = agent_record
       @run = run
@@ -52,6 +59,14 @@ module ActionAgent
       @event_sequence = 0
     end
 
+    # The caller this run executes on behalf of, or nil when it runs
+    # unattributed. Passed to every tool as +actor:+ — a host's SchemaTools
+    # scope block, Pundit policy or agent callback decides what that means.
+    # @return [Object, nil]
+    def actor
+      @run.actor
+    end
+
     # Emits a progress event on the run (streamed to the UI by pollers).
     # Never lets telemetry break execution.
     def emit_event(**kwargs)
@@ -266,6 +281,12 @@ module ActionAgent
     # execution) and recorded in @tool_invocations so tool names, arguments
     # and durations reach Traces and the persisted conversation.
     def execute_tool(name, **kwargs)
+      forged = kwargs.slice(*ACTOR_KEYWORDS)
+      if forged.any?
+        Rails.logger.warn("[AgentExecutionService] dropped caller-named arguments from #{name}: #{forged.keys.join(', ')}")
+        kwargs = kwargs.except(*ACTOR_KEYWORDS)
+      end
+
       # Record the absolute URL browse_page will actually fetch, not the bare
       # path the model passed — spans/events/persisted args stay unambiguous.
       kwargs[:url] = AgentToolbox.resolve_browse_url(kwargs[:url]) if name.to_s == "browse_page" && kwargs[:url]
@@ -309,7 +330,9 @@ module ActionAgent
         else
           # A tool one of the agent's own MCP servers serves is called there;
           # AgentToolbox answers the rest.
-          mcp_dispatcher.call(name, kwargs) || AgentToolbox.call(name, **kwargs)
+          # `actor:` comes from the run, never from kwargs (see
+          # ACTOR_KEYWORDS): it is who the run is for, not what it is about.
+          mcp_dispatcher.call(name, kwargs) || AgentToolbox.call(name, actor: actor, **kwargs)
         end
       rescue StandardError => e
         Rails.logger.warn("[AgentExecutionService] Tool #{name} failed: #{e.class} - #{e.message}")
@@ -529,7 +552,10 @@ module ActionAgent
         private :persist_tool_messages_to_context
       end
 
-      agent_class.public_send(action).generate_now
+      # `as` carries the caller onto the agent instance, so an agent's own
+      # before_action callbacks (ActiveAgent::Authorization) authorize
+      # against the same person the tools are scoped to.
+      agent_class.as(actor).public_send(action).generate_now
     end
 
     # Function-calling schemas for the agent's enabled tools that have

data/app/services/action_agent/agent_registrar.rb

@@ -77,8 +77,22 @@ module ActionAgent
       ActionAgent.multi_tenant? ? @trace.try(:account) : nil
     end
 
+    # The set an observed agent is deduplicated within.
+    #
+    # `for_owner(nil)` is `none` — correct for a multi-tenant read, where an
+    # unresolved tenant must see nothing. But a single-tenant dashboard has no
+    # owner to resolve and legitimately registers with `owner` nil (see
+    # #owner_for_trace), and `none` makes every dedupe lookup miss: each trace
+    # created another copy of the same agent, and the MAX_OBSERVED_PER_OWNER
+    # cap never engaged because the count it reads was always zero. Scoping to
+    # the whole table when there is no owner concept is what `for_owner`
+    # already does for a model with no owner association.
+    def agents_for_owner(owner)
+      owner.nil? && !ActionAgent.multi_tenant? ? Agent.all : Agent.for_owner(owner)
+    end
+
     def find_or_create_agent(owner)
-      agents = Agent.for_owner(owner)
+      agents = agents_for_owner(owner)
       existing = agents.find_by(
         service_name: @trace.service_name,
         agent_class_name: agent_class,
@@ -86,6 +100,14 @@ module ActionAgent
       )
       return existing if existing
 
+      # A host that mirrors its agent classes into the dashboard (a sync, a
+      # release) names the class on the record and nothing else: that record
+      # stands for every action of the class, so a trace from the class is
+      # its trace — not an observed twin's. Observed records are per action
+      # and are only ever matched on all three keys above.
+      mirrored = agents.where.not(status: "observed").find_by(agent_class_name: agent_class)
+      return mirrored if mirrored
+
       return if agents.observed_agents.count >= MAX_OBSERVED_PER_OWNER
 
       create_observed_agent(owner)

data/app/services/action_agent/agent_release.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # Cuts a version of every dashboard agent that mirrors a host class, from
+  # that class's release digest — what a deploy runs so the dashboard's
+  # versions line up with the code that shipped.
+  #
+  # The host owns the mirror: whatever syncs its ActiveAgent classes into
+  # Agent records sets `agent_class_name`, and this reads it back. A record
+  # whose class no longer resolves, or whose class predates
+  # ActiveAgent::Release, is reported and skipped rather than failed.
+  #
+  # Idempotent: a redeploy of an unchanged agent cuts nothing, so running it
+  # on every deploy is the intended use (`rake action_agent:agents:release`).
+  class AgentRelease
+    Row = Struct.new(:agent, :version, :cut, :skipped, keyword_init: true)
+    Result = Struct.new(:rows, :revision, keyword_init: true) do
+      def cut = rows.select(&:cut)
+      def skipped = rows.select(&:skipped)
+    end
+
+    # @param revision [String, nil] the deploy (git SHA, release label);
+    #   ActiveAgent::Release.revision when nil
+    # @param agents [ActiveRecord::Relation] the records to release; every
+    #   record naming a host class by default
+    # @param released_by [String, nil] recorded on each version cut
+    def self.call(revision: nil, agents: nil, released_by: nil)
+      new(revision: revision, agents: agents, released_by: released_by).call
+    end
+
+    def initialize(revision: nil, agents: nil, released_by: nil)
+      @revision = revision.presence || ActiveAgent::Release.revision
+      @agents = agents || Agent.where.not(agent_class_name: [ nil, "" ])
+      @released_by = released_by
+    end
+
+    # @return [Result]
+    def call
+      rows = @agents.order(:name).map { |agent| release(agent) }
+      Result.new(rows: rows, revision: @revision)
+    end
+
+    private
+
+    def release(agent)
+      klass = agent.agent_class_name.to_s.safe_constantize
+      unless klass.respond_to?(:release_digest)
+        return Row.new(agent: agent, version: nil, cut: false, skipped: "#{agent.agent_class_name} does not resolve to a releasable class")
+      end
+
+      before = agent.latest_version&.id
+      version = agent.record_release!(
+        digest: klass.release_digest,
+        manifest: klass.release_manifest,
+        revision: @revision,
+        released_by: @released_by
+      )
+      Row.new(agent: agent, version: version, cut: version.id != before, skipped: nil)
+    end
+  end
+end

data/app/services/action_agent/agent_tool_roster.rb

@@ -0,0 +1,295 @@
+# frozen_string_literal: true
+
+module ActionAgent
+  # One agent's tool roster, as the agent editor's Tools tab reads it: every
+  # tool the agent can be offered and every MCP service it can be given, each
+  # carrying what the window actually recorded for it.
+  #
+  # Three groups, one row vocabulary — the same one the Tools and MCP
+  # Services pages use, so a roster reads the way the observability views do:
+  #
+  # * **Agent-defined** — the tools this agent's own generations offered
+  #   (ToolDiscovery's +agent+ origin), plus every schema tool the host
+  #   declares, on or off. Two kinds share the group. A *schema tool* — one
+  #   a host ActiveAgent::SchemaTools class generates — is offered only while
+  #   +agent.tools+ names it: that is the reading AgentToolbox takes at
+  #   generation time, and the evaluation runner, dashboard runs and the MCP
+  #   facade all follow it. So it is selected here, and switchable, and every
+  #   one has a row because any agent may enable any of them
+  #   (Agent.available_tools) and a tool switched off has to keep its row to
+  #   be switched back on. A tool the agent class declares *in code* is
+  #   offered by the class itself; the dashboard reports it and cannot switch
+  #   it, so its row is read-only — a checkbox that cannot add or remove the
+  #   tool is a control that changes nothing.
+  # * **Dashboard** — Agent::AVAILABLE_TOOLS, the capabilities the builder
+  #   offers every agent. These are the roster: +agent.tools+ is what
+  #   AgentToolbox turns into function schemas at generation time.
+  # * **MCP** — never stored on the roster. Computed from the services the
+  #   agent enables, which is where they are edited.
+  #
+  # Enablement reads the agent's own configuration: +tools+ for the dashboard
+  # capabilities and the schema tools, +mcp_servers+ for services and their
+  # per-server allow-lists (an entry with no +tools+ key offers everything
+  # the server serves).
+  class AgentToolRoster
+    AGENT_DEFINED = "agent_defined"
+    DASHBOARD = "dashboard"
+    MCP = "mcp"
+
+    # Ordering for the services list: what this agent uses, then what the
+    # workspace already talks to, then the rest of the catalog.
+    STATUS_RANK = { "active" => 0, "configured" => 1, "available" => 2, "idle" => 3 }.freeze
+
+    attr_reader :agent, :discovery
+
+    # @param agent [ActionAgent::Agent] the agent being edited
+    # @param traces [ActiveRecord::Relation] the traces the caller may read
+    # @param hours [Integer] the window the usage columns are scoped to
+    def initialize(agent:, traces:, hours: ToolDiscovery::DEFAULT_WINDOW_HOURS)
+      @agent = agent
+      @discovery = ToolDiscovery.new(
+        traces: traces.for_agent(agent.telemetry_agent_class),
+        agents: Agent.where(id: agent.id),
+        hours: hours
+      )
+    end
+
+    def as_json(*)
+      {
+        window_hours: discovery.window_hours,
+        # Whether any record source had rows in this window. False means the
+        # usage columns have nothing behind them, and the view renders them
+        # as "—" rather than as a row of honest-looking zeroes.
+        usage_available: inventory[:sources].values.any?,
+        services: services,
+        tools: tools
+      }
+    end
+
+    private
+
+    def inventory
+      @inventory ||= discovery.inventory
+    end
+
+    def detected
+      inventory[:tools]
+    end
+
+    def saved_tools
+      @saved_tools ||= Array(agent.tools).map(&:to_s)
+    end
+
+    # --- services ------------------------------------------------------
+
+    def services
+      rows = service_keys.map { |key| service_row(key) }
+      rows.sort_by do |row|
+        [ row[:enabled] ? 0 : 1, STATUS_RANK.fetch(row[:status], 9), -row[:calls], row[:name].to_s.downcase ]
+      end
+    end
+
+    # The catalog, plus anything this agent's traffic or configuration names
+    # that the catalog doesn't describe.
+    def service_keys
+      (MCPCatalog.keys + detected_by_server.keys + configured_servers.keys).uniq
+    end
+
+    def detected_by_server
+      @detected_by_server ||= detected.reject { |tool| tool[:mcp_server].blank? }.group_by { |tool| tool[:mcp_server] }
+    end
+
+    def service_row(key)
+      catalog = MCPCatalog.find(key)
+      used = detected_by_server[key] || []
+      calls = used.sum { |tool| tool[:calls] }
+      enabled = configured_servers.key?(key)
+
+      {
+        key: key,
+        name: catalog ? catalog[:name] : key,
+        description: catalog&.dig(:description),
+        docs_url: catalog&.dig(:docs_url),
+        first_party: catalog ? catalog[:first_party] : false,
+        known: !catalog.nil?,
+        transport: transport_label(catalog),
+        status: service_status(calls, enabled, catalog),
+        enabled: enabled,
+        calls: calls,
+        errors: used.sum { |tool| tool[:errors] },
+        last_seen: used.filter_map { |tool| tool[:last_seen] }.max,
+        tools: service_tools(key, catalog, used)
+      }
+    end
+
+    # How to reach the server, in the one line the expanded panel shows:
+    # "Streamable HTTP · <url>" for the ones the dashboard can call,
+    # "sandbox · <command>" for the ones it can start, "stdio · <command>"
+    # for the rest.
+    def transport_label(catalog)
+      return nil if catalog.nil?
+
+      transport = catalog[:transport].to_s
+      return [ "Streamable HTTP", catalog[:url] ].compact.join(" · ") if transport == "http"
+
+      prefix = catalog[:sandbox] ? "sandbox" : transport.presence
+      [ prefix, catalog[:command] ].compact.join(" · ").presence
+    end
+
+    def service_status(calls, enabled, catalog)
+      return "active" if calls.positive?
+      return "configured" if enabled
+      return "available" if catalog
+
+      "idle"
+    end
+
+    # What the service offers: the catalog's tool hints unioned with the
+    # tools this agent was actually seen calling on it, so a server whose
+    # roster has drifted from the catalog still lists what it really serves.
+    def service_tools(key, catalog, used)
+      by_name = used.index_by { |tool| tool[:base_name] }
+      allowed = allowed_tools(key)
+      names = (Array(catalog&.dig(:tools)) + by_name.keys).uniq
+
+      names.map do |name|
+        usage_row(by_name[name]).merge(
+          name: name,
+          description: by_name[name]&.dig(:description),
+          enabled: allowed.nil? || allowed.include?(name)
+        )
+      end
+    end
+
+    # --- tools ---------------------------------------------------------
+
+    def tools
+      agent_defined_rows + dashboard_rows
+    end
+
+    # Agent-defined tools: whatever this agent's generations offered that is
+    # neither an MCP tool nor one of the dashboard's own, plus every schema
+    # tool the host declares, whether or not the window saw it.
+    def agent_defined_rows
+      observed = detected
+        .select { |tool| tool[:origin] == ToolDiscovery::ORIGIN_AGENT }
+        .reject { |tool| dashboard_function_names.include?(tool[:name]) }
+        .index_by { |tool| tool[:name] }
+
+      (observed.keys + ActionAgent.schema_tool_names).uniq.map do |name|
+        tool = observed[name]
+        schema = schema_tool?(name)
+
+        usage_row(tool).merge(
+          key: name,
+          name: name,
+          source: AGENT_DEFINED,
+          description: tool&.dig(:description) || schema_tool_description(name),
+          # A schema tool is offered only while the roster names it — the
+          # window may still show it being called, but that is history. A
+          # tool the agent class declares in code is offered by the class.
+          enabled: schema ? saved_tools.include?(name) : true,
+          editable: schema
+        )
+      end
+    end
+
+    def schema_tool?(name)
+      @schema_tool ||= Hash.new { |cache, key| cache[key] = ActionAgent.schema_tool_class_for(key).present? }
+      @schema_tool[name]
+    end
+
+    def schema_tool_description(name)
+      AgentToolbox.schema_tool_definitions(name).first&.dig(:description)
+    end
+
+    def dashboard_rows
+      Agent::AVAILABLE_TOOLS.map do |capability|
+        usage_row(capability_usage(capability)).merge(
+          key: capability,
+          name: capability,
+          source: DASHBOARD,
+          description: Agent::TOOL_DESCRIPTIONS[capability],
+          enabled: saved_tools.include?(capability),
+          editable: true
+        )
+      end
+    end
+
+    # A capability is one checkbox over the several functions it exposes
+    # ("memory" is save_memory + recall_memory), so its usage is their sum.
+    def capability_usage(capability)
+      names = (AgentToolbox::DEFINITIONS[capability]&.map { |definition| definition[:name].to_s } || []) + [ capability ]
+      rows = detected.select { |tool| names.include?(tool[:name]) }
+      return nil if rows.empty?
+
+      timed = rows.filter_map { |row| [ row[:avg_duration_ms], row[:calls] ] if row[:avg_duration_ms] }
+      weighted = timed.sum { |average, calls| average * [ calls, 1 ].max }
+      samples = timed.sum { |_average, calls| [ calls, 1 ].max }
+
+      {
+        calls: rows.sum { |row| row[:calls] },
+        errors: rows.sum { |row| row[:errors] },
+        avg_duration_ms: samples.positive? ? (weighted / samples).round : nil,
+        last_seen: rows.filter_map { |row| row[:last_seen] }.max
+      }
+    end
+
+    def usage_row(tool)
+      {
+        calls: tool ? tool[:calls] : 0,
+        errors: tool ? tool[:errors] : 0,
+        avg_duration_ms: tool ? tool[:avg_duration_ms] : nil,
+        last_seen: tool ? tool[:last_seen] : nil
+      }
+    end
+
+    # Every function name the dashboard's own toolbox implements, so a
+    # builtin never lands in the agent-defined group under its bare name.
+    def dashboard_function_names
+      @dashboard_function_names ||= ToolDiscovery.builtin_tools | Agent::AVAILABLE_TOOLS.to_set
+    end
+
+    # --- the agent's MCP configuration ---------------------------------
+
+    # server key => the entry the agent stores for it. Entries are bare
+    # strings or builder hashes, and an agent seeded from an older template
+    # carries a top-level Hash keyed by server name — the same three shapes
+    # EvaluationToolResolver tolerates.
+    def configured_servers
+      @configured_servers ||= configured_entries.each_with_object({}) do |entry, map|
+        key = entry_key(entry)
+        map[key] = entry if key.present?
+      end
+    end
+
+    def configured_entries
+      servers = agent.mcp_servers
+
+      if servers.is_a?(Hash)
+        servers.map { |key, value| value.respond_to?(:key?) ? value.to_h.stringify_keys.merge("key" => key.to_s) : key.to_s }
+      else
+        Array(servers)
+      end
+    end
+
+    def entry_key(entry)
+      return entry.to_s.strip.presence if entry.is_a?(String) || entry.is_a?(Symbol)
+      return nil unless entry.respond_to?(:key?)
+
+      (entry["key"] || entry[:key] || entry["name"] || entry[:name]).to_s.strip.presence
+    end
+
+    # The per-server allow-list, or nil when the entry names none — which
+    # means the agent is offered every tool the server serves.
+    def allowed_tools(key)
+      entry = configured_servers[key]
+      return nil unless entry.respond_to?(:key?)
+
+      names = entry["tools"] || entry[:tools]
+      return nil if names.nil?
+
+      Array(names).filter_map { |tool| (tool.respond_to?(:key?) ? tool["name"] || tool[:name] : tool).to_s.presence }
+    end
+  end
+end

data/app/services/action_agent/agent_toolbox.rb

@@ -231,13 +231,22 @@ module ActionAgent
       def call(name, **kwargs)
         return { error: "Unknown tool: #{name}" } unless function?(name)
 
-        schema_tool = ActionAgent.schema_tool_class_for(name.to_s)
-        if schema_tool
+        # Who the call is for is never one of the call's arguments: it comes
+        # off here, before a tool sees them. That keeps a built-in from
+        # meeting an unexpected keyword, and keeps the cache key below over
+        # the arguments alone.
+        actor = kwargs.delete(:actor)
+
+        if (schema_tool = ActionAgent.schema_tool_class_for(name.to_s))
           # `actor:` is the host's authorization seam — the scope block runs
           # inside the call. It is passed through untouched, including nil,
           # so a host scope decides what an unattributed run may read rather
           # than the engine widening it.
-          return schema_tool.call(name.to_s, actor: kwargs.delete(:actor), **kwargs)
+          #
+          # Deliberately not cached: a scoped read is one caller's answer,
+          # and replaying it for the next caller would hand them rows their
+          # own scope would have refused.
+          return schema_tool.call(name.to_s, actor: actor, **kwargs)
         end
 
         return public_send(FUNCTIONS.fetch(name.to_s), **kwargs) if UNCACHED_FUNCTIONS.include?(name.to_s)