Skip to main content
An approval is a human decision required before an agent takes a risky or irreversible action.

​
Approval fields

Each approval request carries the following fields:
FieldTypeDescription
idstringUnique identifier (e.g., approval_456).
titlestringShort description of what needs approval.
reasonstringWhy the action requires a human decision.
risklow / medium / highHow dangerous or irreversible the action is.
statuspending / approved / rejected / canceledCurrent state of the approval.
agentIdstringID of the agent that made the request.
taskIdstringOptional ID of the task the action relates to.

​
What always requires approval

The following actions always require a human approval, regardless of risk level or task settings:
  • Merging a pull request
  • Deploying to any environment
  • Creating or modifying infrastructure
  • Changing production data
  • Spending money
  • Issuing refunds
  • Sending external email
  • Any external tool action that is not clearly read-only
Read-only tool actions — those whose slug contains FETCH, GET, LIST, SEARCH, READ, or FIND — do not require manual approval. Dench enforces this distinction automatically when you use dench tool run.

​
Requesting approval

When your agent reaches a step that requires human sign-off, call dench approval request before taking any action. 
dench approval request "Deploy backend service to production" \
  --task task_123 \
  --json
The response includes an approval ID. Your agent should pause and wait for the human to decide before continuing.
Never take the action before receiving a decision. Request the approval, inform the human, and wait for an explicit yes or no.

​
How humans decide

Humans review and act on approval requests in the Dench dashboard under Approvals inbox. Pending requests appear first, sorted by risk level. Each card shows the title, reason, risk, requesting agent, linked task, and creation time. Workspace admins can click Approve or Reject directly from the dashboard. Only admins can make approval decisions.

​
Recording decisions from the agent

After the human decides, record the outcome through the CLI using the approval ID. 
dench approval approve approval_456 \
  --evidence "User approved in chat: 'yes, deploy it'" \
  --json
The --evidence flag captures where and how the human gave their decision. Include a short quote or description so there is an audit trail.
Humans decide. Agents only record an explicit human yes/no with evidence, or wait for dashboard approval. Agents never approve their own requests.

​
Tool approvals

When you run a non-read-only external tool through dench tool run, Dench automatically returns a requiresApproval response with an approval ID instead of executing the action. 
dench tool run GITHUB_CREATE_PR \
  --args '{"title": "Fix checkout", "base": "main"}' \
  --json
If the tool requires approval, the response includes requiresApproval: true and an approvalId. Ask the human, then rerun with --approval <approvalId> once approved. 
dench tool run GITHUB_CREATE_PR \
  --args '{"title": "Fix checkout", "base": "main"}' \
  --approval approval_456 \
  --json

​
Approval lifecycle

pending → approved → (agent proceeds)
        → rejected → (agent stops or finds alternative)
        → canceled → (request withdrawn before decision)
Once an approval moves out of pending, the decision is final. The Dench dashboard shows the 10 most recent decided approvals below the pending queue so you have a record of recent decisions.