Carry the caller into agent runs, so agents can authorize like controllers

[TonsOfFun]

Closes the gap #438 named and left open: SchemaTools ships actor: as the host's authorization seam, and nothing ever filled it.

The problem

Every dashboard run executed unattributed. AgentExecutionService#execute_tool ended at AgentToolbox.call(name, **kwargs) with no actor, so a correctly written Pundit scope resolved to the empty set and a well-wired agent answered "there are no tickets" to someone with plenty. That is a wrong answer wearing a right one's clothes — the same class of silent failure as the swallowed tools/list in #425.

Worse than unfilled, the seam was fed from model-controlled input. AgentToolbox.call read actor: out of the same keyword hash as the arguments a provider parsed from the model's tool call:

define_method(definition[:name]) { |**kwargs| service.execute_tool(definition[:name], **kwargs) }
# …
actor = kwargs.delete(:actor)   # same namespace as everything the model emitted

Nothing filters those against the declared inputSchema. An actor a model can name — through any document it reads — is not an authorization boundary. It was inert only because actor is in no tool's schema today.

What a developer writes now

class TicketAgent < ApplicationAgent
  denies_with Pundit::NotAuthorizedError      # your gem's error counts as a refusal

  before_action :authorize_tickets!, only: [:find_tickets, :get_ticket]

  def find_tickets(**filters)
    TicketTools.call("find_tickets", actor: current_user, **filters)
  end

  private

  def authorize_tickets!
    authorize Ticket, :index?                  # plain Pundit, against current_user
  end
end

TicketAgent.as(current_user).ask("which tickets are overdue?").generate_now

current_user is on the agent instance and readable from every callback, so Pundit, CanCanCan and Action Policy authorize an agent the way they authorize a controller — before_action is the same AbstractController chain, only:/except: included, so a roster is authorized tool by tool. The framework never interprets the actor.

Two failure modes, kept distinct. A refusal inside a tool call is returned to the model as { error: … }, so it can say it is not allowed rather than dying mid-run or reporting an empty set as fact. A refusal anywhere else is raised to whoever asked. Over MCP that becomes a JSON-RPC error (-32003), never an empty result.

The actor is never model input. It is not in params, never a tool argument, and actor / current_user are stripped from a model's arguments before any tool sees them. A client sending params[params][actor] to /api/agents/:id/execute is refused the same way — a keyword splat wins over the arguments before it, so that one would otherwise have named its own caller.

How it reaches a run

Surface	Caller
Dashboard run	the signed-in user (agent_actor)
MCP tools/call	the key's own caller — the identity that authenticated the request
Either	whatever ActionAgent.agent_actor_resolver returns, when a host sets it

A run records the caller as a Global ID, so a worker on another machine authorizes as the same person; one that no longer resolves yields nil rather than a fallback. Scoped SchemaTools reads now bypass the tool-result cache — one caller's rows must never be replayed for the next.

Unset resolver, no owner model: the run is unattributed and a host scope reads that as "no access". That is the safe direction, and it is why nothing here defaults to something more privileged.

Review of today's issues

Checked against main while building this:

• SchemaTools has no registration seam: tools are invisible to AgentToolbox and the agent editor #438 — closed, but its last section never shipped. The registration seam landed; "Related: an actor on the execution context" did not. This PR is that half. The forged-actor vector above is new information the issue didn't have. (SchemaTools has no registration seam: tools are invisible to AgentToolbox and the agent editor #438 is also closed by release PR chore(release): activeagent and actionagent 1.5.2 #442 rather than by its implementing PRs, so the trail doesn't point at the code.)
• Feature: a model's agent is also an MCP server, so its tools are callable in-process or by an external agent #439 — right feature, understates what exists. It asks for "a mounted Rack endpoint speaking MCP over HTTP"; Api::McpController already is one, already in MCPCatalog as the first-party entry. The work there is extending that facade with the schema-tool roster, not a second server — which the issue's own "not a parallel implementation" line warns about. Its actor_resolver is ActionAgent.agent_actor_resolver here, and its stated prerequisite Surface MCP tool-discovery failures instead of running tool-less and silent #434 has merged. Still open in Feature: a model's agent is also an MCP server, so its tools are callable in-process or by an external agent #439 and not in this PR: serving schema tools through tools/list / tools/call.
• Schema tools: derive the roster from models/agents rather than a hand-written config array #440 — headline is stale. Its preferred option (1), "drop the config array, discover SchemaTools subclasses", shipped in 46a04e2 (discovered_schema_tools, schema_tools_path). What remains is the generator and opt-in derivation; worth narrowing the issue so nobody redoes it.
• Schema tools defined at runtime: persist the declaration, build the class on demand #441 — the leak it names is still real. scope_by_policy exists, so the derived-scope half is done. SchemaTools.inherited still calls super, so anonymous subclasses are still retained in descendants — ActionAgent.schema_tool_classes only skips them during discovery, which hides the symptom without stopping the growth.

Also in this branch

The agent detail Tools tab redesign (4b7ac6a): the ~21-card glyph grid replaced by an MCP services list and a grouped tool roster with calls, errors, latency and last-seen per row over a 24h/7d/30d window, plus GET /api/agents/:id/tool_roster. Independent of the authorization work; say the word and I'll split it onto its own branch.

Testing

• 435 runs / 2078 assertions green across the framework and engine suites (15 new: test/authorization_test.rb, actionagent/test/agent_authorization_test.rb, actionagent/test/mcp_authorization_test.rb).
• Covered explicitly: a model-named actor is dropped; a client-named one is reserved; an actor survives to a worker and a dead one resolves to nobody; a scoped read is not cached across callers; a built-in never meets the actor as an argument; a refusal is a JSON-RPC error while a crash stays a tool result.
• rubocop clean on every changed file.

🤖 Generated with Claude Code

https://claude.ai/code/session_01NEwRNXQY7fUvZ4Z1UNpyyJ

---

Generated by Claude Code