Skip to main content
An approval holds an agent’s action until a named person decides. Nothing runs while it waits, and every decision is recorded with the name of who made it.

​
When a run waits

The agent posts a card saying what it wants to do, what it will touch and who started the run. Approve runs the action and the agent continues. Decline skips that one attempt, tells the agent, and the conversation continues. The person who asked can withdraw a pending request.
Conversation with an approval card: Write (gated mode), Wants to write a travel checklist to travel-checklist.md, buttons Decline and Approve

An approval card in a conversation. The agent wants to write a file; the run waits until an approver clicks Approve. Shown with sample data.

​
Where to find everything that is waiting

Settings > Approvals lists everything waiting for you across all agents. Approvals also arrive as notifications, and a person who is not signed in can get a link that opens that one approval.
Settings, Approvals page with a Waiting for you list and a Decided list showing Approved, Declined and Withdrawn outcomes

Settings > Approvals: Waiting for you and Decided. Shown with sample data.

​
How long a run waits

Four hours by default. Set it per agent from one to seventy-two hours (approval_hold_hours on the API). After the window the held action does not run and the rest of the task continues. A gated command’s request stays pending, so a later decision can still approve it. A marked skill action expires with “Not answered in time.”

​
Over the API

GET /v1/tasks/{task_id}/approvals lists what a task waits on. POST /v1/tasks/{task_id}/approvals/{request_id} decides one item, as the person who owns the API key, with decision (approve or decline) and an optional reason. The key must cover the task’s agent.
Each item has request_id, tool_name, tool_label, gate_reason, created_at and expires_at.

​
Answering an MCP server’s question

An MCP server can ask a question mid-call. The item then has kind set to elicitation, a message and a requested_schema. Send the answer in content, shaped by the schema:
A mismatched answer returns HTTP 400 naming the field. decline tells the server the person declined. The MCP server may stop waiting before expires_at: the MCP TypeScript SDK stops after 60 seconds by default.

​
What gets held

  • Skill actions that need approval. Set in the skill panel (“These actions need approval”) by anyone who can edit the agent. See Skills.
  • Gated commands. Shell commands containing any listed pattern, under Advanced > Commands in Agent settings. They wait in every permission mode.
  • The permission mode. Manually approve holds every shell command and file change, and on Claude Code and OpenCode every web fetch and search. Automatically approve runs them.
Gated commands editor with a list of command patterns that hold a run for approval

The Gated commands editor. A command that contains one of these strings waits for approval. Shown with sample data.

​
Who may approve

The skill panel names the approvers for each action. An agent can be set to approve its own runs for an action (“SELF APPROVE”), so a fully unattended agent proceeds on actions your organization decided are safe. Self-approvals are recorded too.

​
Next steps

Set permissions and access

The settings behind approvals.

Mark a skill's actions for approval

Choose what needs sign-off.