Approvals

The approval system lets you require human confirmation before an agent executes specific tools or actions. This is essential for high-stakes operations like file writes, shell commands, deployments, or any action that cannot be easily undone.

How approvals work

When an agent attempts to call a tool that is in the requireApproval list, the agent loop pauses before executing the tool and emits an approval.requested event. The event is delivered to all configured approval handlers (webhook, Slack notification, API response, etc.).

The agent waits up to timeoutMs for a response. If approved, the tool executes and the loop continues. If denied or if the timeout expires with defaultOnTimeout: deny, the tool call is skipped and the agent receives an error result instead.

Configuration

yaml

approval:
  requireApproval:
    - tool: file_write          # Require approval for all file_write calls
    - tool: shell_exec          # Require approval for all shell commands
    - tool: deploy              # Require approval for deployments
    - agent: deploy-agent       # Require approval for ANY action by this agent
  timeoutMs: 300000             # Wait up to 5 minutes for a decision
  defaultOnTimeout: deny        # deny | allow

Approval rule types

Rule type	Config key	Description
Tool-level	`tool: <name>`	Require approval every time the named tool is called, by any agent
Agent-level	`agent: <id>`	Require approval for every action taken by the named agent

Responding to approval requests

Approval requests can be responded to via the REST API:

bash

# List pending approvals
GET /approvals

# Approve a pending request
POST /approvals/:requestId/approve

# Deny a pending request
POST /approvals/:requestId/deny

# Approve with a note
POST /approvals/:requestId/approve
{"note": "Confirmed: this write is intentional"}

Webhook notifications

When an approval is requested, Open Astra fires a webhook to any configured WEBHOOK_URL. The payload includes all the information a human needs to make a decision:

json

{
  "event": "approval.requested",
  "requestId": "apr_abc123",
  "agentId": "code-agent",
  "tool": "file_write",
  "params": {
    "path": "./src/auth/middleware.ts",
    "content": "..."
  },
  "context": "Agent is attempting to overwrite authentication middleware",
  "expiresAt": "2026-02-24T03:35:00Z",
  "approveUrl": "https://your-astra/approvals/apr_abc123/approve",
  "denyUrl": "https://your-astra/approvals/apr_abc123/deny"
}

⚠Set defaultOnTimeout: deny for any approval rule that guards destructive operations. A timed-out approval should never silently proceed.