X-Agent Policies

X-Agent Policies control what one agent is allowed to do with other agents in the workspace. Every cross-agent operation -- listing agents, reading sessions, sending messages -- is gated by a policy check. You can allow operations automatically, require interactive review each time, or block them outright.

Operations

There are three policy-controlled operations, plus one special case:

Each operation is evaluated independently. Allowing invoke does not automatically allow read, and vice versa. This lets you configure write-only access (an agent can trigger another agent but not browse its history) or read-only access (an agent can monitor another agent's sessions but not send messages).

Exception: When invoke_agent is called with sync=true, the target agent's final response is returned inline as part of the invoke result. This does not require a separate read policy -- it is part of the invoke contract.

Exception: create_agent is never stored as a policy. It always requires manual user approval, every time it is called. There is no "always allow" option for agent creation.

Decisions

Each policy resolves to one of three decisions:

• Allow -- The operation proceeds without prompting the user.
• Review -- The user is prompted to approve or deny the operation. This is the default when no policy exists.
• Block -- The operation is denied immediately without prompting the user.

Policy precedence

When an agent attempts a cross-agent operation, the policy system evaluates the decision using a most-specific-wins rule:

1. Per-target policy -- If a policy exists for this specific caller, operation, and target agent, that decision is used.
2. Global policy -- If no per-target policy exists, the global policy for this caller and operation (target = all agents) is used.
3. Default -- If no policy exists at all, the default is review (prompt the user every time).

For example, if Agent A has a global invoke policy of allow but a per-target invoke policy of block for Agent B, then Agent A can invoke any agent except Agent B.

The review flow

When a policy evaluates to review (or when no policy exists), the user sees an interactive approval prompt in the Superagent UI. The prompt appears in the caller agent's session as an orange-themed card showing:

• Which agent is requesting the action.
• What operation it wants to perform (list, read, invoke, or create).
• Which target agent is involved (for read and invoke).
• A preview of the message being sent (for invoke operations).

The user has several options:

Deny

Rejects this specific request. The calling agent receives an error that the operation was denied.

Allow Once

Approves this specific request without remembering the decision. The next time the same operation is attempted, the user will be prompted again.

Always Allow (remembered policies)

Available for list, read, and invoke operations (not create). Approves the request and saves a policy so future identical operations proceed automatically. The options vary by operation:

For list:

• "Always allow listing agents" -- Saves a global list policy so the agent can call list_agents without prompting.

For read:

• "Always allow reading " -- Saves a per-target read policy for this specific agent.
• "Always allow reading all agents" -- Saves a global read policy that applies to every agent in the workspace.

For invoke:

• "Always allow messaging " -- Saves a per-target invoke policy for this specific agent.
• "Always allow messaging all agents" -- Saves a global invoke policy for every agent.

When a global "always allow" decision is saved, any other pending review prompts for the same operation (against different targets) are automatically resolved, since the new global policy covers them.

Review timeout

If no decision is made within 5 minutes, the review times out and the operation is denied. The calling agent receives an error indicating the review timed out.

Managing policies in the settings tab

You can view and edit X-Agent Policies directly in the agent's settings dialog, under the X-Agent Policies tab (also labeled "Cross-agent permissions" in the UI). This tab shows:

Global permissions

Three toggles that control workspace-wide defaults for this agent:

• List Agents -- Whether this agent can call list_agents to see other agents. Set to Allow, Review, or Block.
• Read sessions of all agents -- The default read policy for any agent that does not have a specific per-agent setting below.
• Send messages to all agents -- The default invoke policy for any agent that does not have a specific per-agent setting below.

Per-agent permissions

A table listing every other agent in the workspace, with two policy toggles per row:

• Read sessions -- Whether the caller can read this target agent's sessions and transcripts.
• Send messages -- Whether the caller can invoke (send messages to) this target agent.

Per-agent settings override the global defaults. If you set the global "Send messages to all agents" to Allow but set a specific agent's "Send messages" to Block, the caller can message every agent except that one.

The Review state (also shown as "default") means no policy is stored -- the user will be prompted each time. Internally, review rows are not persisted to the database; the absence of a row is treated as review. This keeps the policy table clean.

You can filter the per-agent list by name or slug using the search box when you have many agents in the workspace.

Policy storage

Policies are stored in the x_agent_policies database table with the following structure:

Each combination of (caller, target, operation) is unique. When an agent is deleted, all policy rows referencing it -- whether as caller or target -- are automatically cleaned up.

Auth mode considerations

In auth mode, X-Agent Policies work alongside the existing role-based access control (ACL) system:

• list_agents results are filtered to agents the calling agent's owner has access to.
• get_agent_sessions and get_agent_session_transcript require the caller's owner to have at least viewer role on the target agent.
• invoke_agent requires the caller's owner to have at least user role on the target agent.
• create_agent copies the caller's owner ACL to the new agent, so the owner automatically has access.

ACL checks run first. If the caller's owner does not have sufficient access to the target, the request is rejected before the X-Agent Policy is even evaluated. If ACL passes, the X-Agent Policy is evaluated next.

The X-Agent Policies tab in settings respects auth mode visibility: policies targeting agents the viewer cannot see are hidden, preventing information leakage about workspace topology.

Audit trail

Cross-agent operations that go through the review flow are tracked through the proxy audit log alongside other reviewed actions like API scope approvals and MCP tool approvals. The audit log records the caller agent, the operation, the target, and the policy decision (allow, block, denied by user, or review timeout).

You can view the audit trail for an agent in the agent's settings under the Audit Log tab. For more details on audit logging across Superagent, see Audit Logging.