Permissions

Control which tools your teammate can use with permission modes and pre-approval policies. This lets you build human-in-the-loop workflows where sensitive actions require explicit approval.

Permission Modes

Set the mode when creating a run:

Autonomous Mode

The default — the teammate runs without pausing. All assigned tools are auto-approved.

Use this for trusted operations like read-only queries, internal reports, or tasks with no side effects.

Approval Mode

The teammate pauses whenever it wants to use a tool. You poll for pending requests and approve or deny each one:

Remember Decisions

Pass remember=True to auto-approve the same tool in future runs:

Plan Mode

The teammate creates a plan before executing. It pauses for approval of the plan, then proceeds:

Use plan mode for high-stakes operations where you want to review the approach before execution.

Plan approval uses the AskUserQuestion tool internally. You can also respond to plan approval (and any other agent question) using runs.answer():

Human-in-the-Loop

By default, API runs are fully autonomous (human_in_the_loop=false). Enable it to use approval or plan modes:

Note: permission_mode values other than "autonomous" require human_in_the_loop=true. See the Human-in-the-Loop guide for the complete interactive workflow.

Pre-Approve Tools

Skip the approval step for specific tools by creating permission policies:

Now when runs for cust_123 use approval mode, Slack and Linear calls are auto-approved — only other tools will pause for approval.

Manage Policies

Bulk Pre-Approval During Onboarding

Production Integration

Use webhook events to build an approval UI:

1. Register for run.awaiting_input webhook events
2. When the webhook fires, poll client.runs.permissions(run_id) for pending requests
3. Show the request details to your user
4. Call client.runs.approve() with their decision

What's Next

• Human-in-the-Loop — full interactive features guide
• Webhook Events — get notified when runs need input
• Tools — connect tools for your end-users