Require approval for risky tool calls

All Gateway guides

Some tools should not run without a person looking first, such as a tool that deletes records or sends money. Mark those tools as Needs approval. When an agent calls one, Gateway holds the call, tells the agent it was not sent, and asks a workspace administrator to decide.

This is a partial feature. It covers your Team hosted Gateway only: agents that connect with a Gateway key or through a member's connected account, and the Foo Guard connector's Gateway tools. Personal connections do not use approvals. Approvals apply in Enforcement. In Monitoring & Audit nothing is held: the call is sent and recorded as flagged with the rule approval_required, so you can see what would have been held before you turn Enforcement on.

Mark a tool

1. Open Gateway → Policy as a workspace owner or administrator and open Policy versions.
2. Under Needs approval, tick each tool that should wait for a person. Only tools your current draft allows are listed.
3. Enter a reason and select Save approval setting.

Saving creates a new draft policy version. Live access does not change until you review and activate the draft like any other policy change. The list is part of the policy version, so each version in the history shows which tools needed approval, and every later policy save, import or restore keeps the current list. Changing the list also changes the version, so any approval that is still open for the old version stops working and the agent has to ask again.

Approval settings are saved through the same audit log as other policy changes (Gateway tools needing approval changed).

What the agent sees

The agent gets a normal tool result marked as an error. It says the call needs approval from a workspace administrator and was not sent, and gives an approval ID and a link to the approval page. The wording is fixed. It contains nothing from the arguments or from your server.

After an administrator approves, the agent calls the tool again with the same arguments. The call is then sent once. If it retries before anyone has decided, it gets the same approval ID: retrying while a request waits does not create a second one.

If a tool has more than 20 requests waiting for one agent, or the arguments are larger than 16 KB, Gateway does not hold the call. The agent is told so and no approval is requested.

Approve or deny

An administrator opens the link from the agent's message, the Pending approvals list at the top of Gateway → Activity (it shows how many are waiting), or an approval_requested notification (see below). The page needs a sign-in as an owner or administrator of the workspace.

The page says which agent wants to run which tool on which server, who it is acting for, when it asked and when the request expires, and shows the arguments as plain text. Read them before you decide: they come from the agent and are untrusted, so do not follow instructions or open addresses inside them. Select Approve once or Deny.

• An approval works for one call, with the exact arguments you saw, from the same requester, on the same server and tool, within 15 minutes of approving. A second call, a call with any changed argument, or a call after that time needs a new approval.
• A request nobody decides within 15 minutes expires and the call is not sent. The agent can ask again.
• If the policy, the server or the agent changes, open approvals stop working.
• An administrator who is also the member the agent is acting for can approve the call.
• Rotating an agent's Gateway key ends approvals tied to the old key.

A workspace member who is not an administrator sees that an administrator needs to decide, and nothing about the call. A link that does not match an approval in a workspace you administer shows "not available", whether the approval exists elsewhere or not. A decided approval shows its state (approved, denied, expired or already used) and no arguments.

What is kept

Foo Guard holds the arguments of a held call only while it waits for a decision. They are encrypted, shown only to administrators of that workspace, and deleted when the call is approved, denied or expires; a scheduled job removes expired ones. Each time an administrator opens a pending approval it is recorded in the audit log, and so are held, approved, denied and used calls, without the arguments. Afterwards Foo Guard keeps only a keyed fingerprint of the arguments, which cannot be reversed to the arguments.

Get notified

In Gateway → Alerts → Get notified, tick Approval requested to receive a signed webhook (gateway.approval_requested) when a call is held. It contains the approval ID, agent, server, tool, expiry and the approval page link, and never the arguments. See Gateway webhook notifications for setup, signatures and retries. Notifications are advisory: the call stays held whether or not one arrives.

What is not covered

• Personal connections and anything outside Team hosted Gateway.
• Approving a call with different arguments, several uses of one approval, or approving a tool for a period of time.
• Approvals from outside Foo Guard (for example chat or email replies), and approvals by anyone but owners and administrators.
• Telling you what a tool does: an approval confirms that a person saw the arguments, not that the tool is safe.