Tool Approvals

Tool approvals control whether an agent runs a tool automatically or pauses for a human to approve it first. This matters most for actions — automated agent runs triggered by webhooks — where a tool might post a public reply, send an email, or update an external system on your behalf.

Every approval-gated tool resolves to one of three modes.

The three modes

You set the default mode for each tool in the console under Actions → your webhook → Approval rules. A sender can also override a tool's mode per event, and individual users can set their own preference (see Precedence).

How "Agent" mode decides

This is the powerful one: instead of a fixed Allow/Ask, the agent makes the call each time based on the situation — for example, auto-post 4–5★ review replies but pause for approval on 1–3★ reviews.

Mechanically, AgentPress adds a hidden decision to the tool the agent is about to call. The agent fills in requiresApproval (and a short rationale) by following its own instructions, and AgentPress enforces the result:

Two things must both be true for Agent mode to work the way you want:

1. The tool's mode is agent (set as the rule default, or sent per request).
2. The agent's prompt encodes the policy. Selecting the mode is necessary but not sufficient — the agent only knows when to require approval if you tell it in its instructions.

It is fail-closed: if the agent is unsure, omits the decision, or the value is malformed, the call is staged for approval. The agent never silently runs a call it was uncertain about.

Example: a review responder

Configure the review-reply tool as Agent, then add a policy to the agent's prompt:

When replying to reviews, decide whether the reply needs human approval:

• For 4 and 5 star reviews, reply automatically (no approval needed).
• For 1, 2, and 3 star reviews, require human approval before posting. Always include a one-sentence rationale for your decision.

Now a 5★ review is answered automatically, while a 2★ review is staged and waits for a person — from a single tool, decided per review.

The agent's reasoning is saved as an approval rationale and shown on the staged action and in outbound callbacks (e.g. "1-star review; instructions require approval"), so reviewers see why it paused.

Per-request overrides (for senders)

If you send events to AgentPress via webhooks, you can override a tool's mode for a single event with a top-level toolApprovals field:

{
  "eventType": "review.created",
  "data": { "rating": 2 },
  "toolApprovals": { "respondToReview": "ask" }
}

This is how a multi-location product gives each location its own setting (auto-respond → allow, require approval → ask, let the agent decide → agent) on every event.

Overrides are only honored when the webhook has Allow per-request overrides enabled (off by default — a one-time toggle on the webhook). Sending toolApprovals to a webhook without that toggle is ignored; the event still succeeds.

Per-user preferences

Where supported, an individual user can set their own per-tool preference — Allow, Ask, or Agent — which applies to actions attributed to them.

Precedence

When more than one setting applies to the same tool, the highest wins:

1. A user's "always deny" — a hard floor. The call is always staged and auto-rejected; nothing can override it.
2. A per-request override (only if the webhook allows overrides).
3. A user's preference (Allow / Agent).
4. The rule's default (Allow / Ask / Agent from the console).

So a sender's per-event override beats the configured default — except a user who has explicitly denied the tool.

What you'll see

• An ask or agent-staged call puts the action in pending approval; approve or reject it from the Actions ledger.
• Approved/terminal outbound callbacks include the staged tool call and, for agent-decided approvals, the agent's agentApprovalRationale.
• Lifecycle events are the same whether a human ask or the agent caused the pause: action.pending_approval → action.approved / action.rejected → action.completed.

Related

• Webhooks reference — the toolApprovals payload field and override gate.
• Creating agents — where you write the agent's approval policy into its prompt.
• SDK — toolApprovals, ToolApprovalMode, and agentApprovalRationale types.