Permissions & Escalations

Keep humans in the loop for sensitive actions.

Some tools shouldn’t run without a human pressing approve — sending an email blast, charging a card, posting publicly, dropping a table. agntdata supports two complementary mechanisms.

always_ask tools

In the agent’s tool picker, mark sensitive tools as Always ask before using. The agent’s system prompt is automatically augmented with the rule:

Before calling any of [tool list], you MUST first call escalate_to_human describing the action and getting explicit approval. Do not call those tools without an approving response.

This pushes the gating into the agent’s reasoning loop instead of intercepting the call mid-flight, which keeps the conversation responsive and the audit trail clear.

Common always_ask candidates:

• Outbound connection_* writes (Stripe charges, Linear issue creation, posting to public Slack channels).
• DDL via agnt_db_apply_migration.
• Bulk outbound — sending an email batch, processing a queue of items.
• Anything that costs money or notifies people.

escalate_to_human

A built-in utility tool every agent can call:

{
  "name": "escalate_to_human",
  "input": {
    "question": "OK to email the 142 prospects in this list with the draft below?",
    "context": { "subject": "…", "body": "…" }
  }
}

What happens:

1. A row is written to agent_escalations with status pending.
2. If your workspace has a Slack install with a default escalation channel, a message is posted there with deep links back to the dashboard.
3. The question shows up in Inbox (/dashboard/inbox).
4. A human responds — the answer is returned as the tool result so the agent can continue.

Cancelled escalations return a structured error so the agent stops trying.

Approval mode in the Builder

For Builder-side actions (e.g. testing a connector by sending a real Slack message), there’s a separate per-call approval gate. The Builder writes a meta_agent_pending_tool_call_approvals row and pauses; you confirm or cancel from the chat. This is the Builder-context equivalent of always_ask — useful when you want to dry-run a workflow without committing to side effects.

Audit trail

Every escalation, every approval, and every tool call is logged:

• agent_escalations — every escalate_to_human call, with the question, context, response, and final status.
• meta_agent_pending_tool_call_approvals — Builder-side approval-mode events.
• usage_logs — every tool call (success or failure), with the deployed agent id and the exact tool name.
• agent_compute_usage — every model turn, with token + runtime cost.

Combined with the per-session transcript (see Sessions), this gives you a complete record of what the agent did, what it asked, and how a human answered.

Next steps

Sessions

The full event history per conversation.

Tools

Mark sensitive tools always_ask from the picker.

Slack connector

Configure the escalation channel.