CLI Reference: HITL Approvals (pending, approve, deny)
Commands for human-in-the-loop (HITL) approval of pending tool requests.
When an agent attempts to invoke a tool that requires human approval (marked as sensitive in its schema, or matched by a trust-level policy), the request is held in a pending queue until an operator approves or denies it. See HITL Approvals for background.
ash pending
List all pending tool approval requests.
ash pending
Output per request:
| Field | Description |
|---|---|
request_id | UUID of the request, used to approve or deny it |
agent_id | Agent that submitted the request |
tool_name | Tool to be invoked |
input | Tool input (JSON); sensitive values are shown as [REDACTED] |
submitted_at | RFC3339 timestamp |
status | Always Pending in this list |
ash approve
Approve and execute a pending tool request.
ash approve <request-id> [--operator <token>]
| Argument/Flag | Description |
|---|---|
request-id | UUID from ash pending |
--operator | Optional operator identity token for the audit trail |
On approval, agentd immediately executes the tool on behalf of the waiting agent and returns the result to it. The agent resumes from the Act state.
Example:
ash approve a1b2c3d4-e5f6-7890-abcd-ef1234567890
ash approve a1b2c3d4-e5f6-7890-abcd-ef1234567890 --operator alice@example.com
ash deny
Deny (cancel) a pending tool request.
ash deny <request-id> [--operator <token>]
On denial, the agent receives a ToolError::HumanDenied response. The agent is responsible for handling this error in its plan-act-observe loop (e.g. by aborting the task or trying an alternative approach).
Example:
ash deny a1b2c3d4-e5f6-7890-abcd-ef1234567890 --operator alice@example.com
Workflow
# 1. Check what's waiting
ash pending
# 2. Review the request details (agent, tool, input)
# 3. Approve or deny
ash approve <request-id>
# or
ash deny <request-id>
Audit trail
All approvals and denials are recorded in the audit log with:
- Operator identity (if
--operatorwas provided) - Request ID
- Tool name and agent ID
- Timestamp
Related: tool proposal approvals
Dynamic tool registration proposals (not invocations) use a separate command:
ash tools proposed # list proposals
ash tools approve <id> # approve registration
ash tools deny <id> # deny registration