Skip to main content

Documentation Index

Fetch the complete documentation index at: https://dench.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

Approvals are how agents check with a human before taking a consequential action. An agent requests approval, the human reviews it in the Dench dashboard or in chat, and the agent records the outcome. Every decision is logged with evidence so there is a clear audit trail.

​
When to request approval

Always request human approval before any of the following actions:
  • Merging a pull request
  • Deploying to any environment
  • Spending money or issuing refunds
  • Sending external email
  • Changing production data
  • Creating or modifying infrastructure
  • Running any external tool action that is not clearly read-only
Read-only tool actions — those with slugs containing FETCH, GET, LIST, SEARCH, READ, or FIND — do not require a separate approval request. Run them directly through Dench and let Dench enforce policy.

​
dench approval request

Request human approval before a risky action. This creates a pending approval in the Dench workspace that the human sees in their approvals inbox. 
dench approval request "Merge PR #42 to main" \
  --reason "All tests passed and the change is ready to ship." \
  --risk high \
  --task task_123 \
  --json
​
message
string
required
A clear description of what you want to do and why. The human reads this when deciding whether to approve. Pass it as the first positional argument.
​
--task
string
Associate this approval request with a specific task ID. Omit to attach it to the workspace generally.
​
--reason
string
Additional explanation for why the action is needed. In development mode, the CLI defaults this to Agent requests human approval before a risky action. when omitted.
​
--risk
string
Risk level for the approval. Accepted values are low, medium, and high. Defaults to high.
After running this command, ask the human directly in chat to review and decide. Do not proceed with the action until you have recorded a decision.

​
dench approval approve

Record that the human approved the request. Always include evidence of how the approval was given. 
dench approval approve <approvalId> --evidence "User said yes in chat" --json
​
approvalId
string
required
The ID of the approval request to approve. Get this from the JSON output of dench approval request.
​
--evidence
string
A description of how you know the human approved. Quote what they said, reference the message, or describe the explicit confirmation you received.

​
dench approval reject

Record that the human rejected the request. Always include evidence of how the rejection was given. 
dench approval reject <approvalId> --evidence "User said no in chat" --json
​
approvalId
string
required
The ID of the approval request to reject.
​
--evidence
string
A description of how you know the human rejected. Quote what they said or describe the explicit refusal.

​
The full approval workflow

1

Ask the human in chat first

Before running any approval commands, ask the human directly whether they want to proceed with the action. Do not record a decision until you have a clear yes or no.
2

Request the approval

Run dench approval request to create a formal record of what you are asking to do.
dench approval request "Deploy backend v2.3 to production" \
  --task task_456 \
  --json
Save the approvalId from the response.
3

Human reviews in the dashboard

The human sees the pending approval in their Dench approvals inbox, sorted by risk. They can also approve directly in chat.
4

Record the decision

Once you have a clear answer, record it with evidence:
# If approved
dench approval approve ap_789 \
  --evidence "User confirmed in chat: 'yes go ahead'" \
  --json

# If rejected
dench approval reject ap_789 \
  --evidence "User said 'not yet, wait for QA'" \
  --json
5

Proceed or stop

If approved, proceed with the action and log what you did. If rejected, log the outcome and wait for further instructions.

​
Rules

Humans decide. Agents only record an explicit human yes/no with evidence, or wait for dashboard approval. Agents never approve their own requests.
Ask the human in chat before recording a decision. The approve and reject commands record a decision the human has already made — they do not prompt the human.
When dench tool run returns a requiresApproval field with an approval ID, it means the tool action needs a human check before it can proceed. Ask the human in chat, then rerun the tool command with --approval <approvalId> once you have their explicit confirmation.
# First attempt — returns requiresApproval
dench tool run GITHUB_CREATE_ISSUE --args '{"title":"Bug report"}' --json

# After human approves in chat
dench tool run GITHUB_CREATE_ISSUE \
  --args '{"title":"Bug report"}' \
  --approval ap_789 \
  --json
Humans review pending approvals in the Dench dashboard. Requests are sorted by risk level so high-risk actions appear first. Each request shows the agent name, the action description, the associated task, and a timestamp.