Are you an LLM? Read llms.txt for a summary of the docs, or llms-full.txt for the full context.
Skip to content

ToolApproval

A ToolApproval captures a pending human/system approval request for a tool invocation that was flagged by a ToolPermission operation_rules verdict of approval_required.

How the Approval Workflow Works

When a tool call is flagged as approval_required:

  1. The GovernedToolRuntime returns an ErrToolApprovalRequired sentinel error.
  2. The task controller transitions the task to the WaitingApproval phase.
  3. A ToolApproval resource is created with details about the pending call.
  4. An external actor approves or denies the request via the API.
  5. The task controller reconciles the approval status:
    • Approved: task resumes to Running.
    • Denied: task transitions to Failed with approval_denied.
    • Expired (TTL elapsed): task transitions to Failed with approval_timeout.

Approval-related outcomes are non-retryable and do not consume retry budget.

ToolApproval Fields

apiVersion: orloj.dev/v1
kind: ToolApproval
metadata:
  name: db-write-approval-001
spec:
  task_ref: weekly-report
  tool: database_tool
  operation_class: write
  agent: research-agent
  input: '{"query": "INSERT INTO ..."}'
  reason: "Write operation requires human approval"
  ttl: 10m
FieldDescription
task_refName of the Task waiting for approval.
toolTool name that triggered the approval request.
operation_classThe operation class that requires approval.
agentAgent that attempted the tool call.
inputTool input payload (for audit context).
reasonHuman-readable reason for the approval request.
ttlTime-to-live before auto-expiry. Defaults to 10m.

Status

FieldDescription
phasePending, Approved, Denied, Expired.
decisionapproved or denied.
decided_byIdentity of the approver/denier.
decided_atTimestamp of the decision.
expires_atTimestamp when the approval expires.

API Endpoints

  • POST /v1/tool-approvals -- create an approval request.
  • GET /v1/tool-approvals -- list approval requests.
  • GET /v1/tool-approvals/{name} -- get a specific approval.
  • DELETE /v1/tool-approvals/{name} -- delete an approval.
  • POST /v1/tool-approvals/{name}/approve -- approve a pending request. Body: {"decided_by": "..."}.
  • POST /v1/tool-approvals/{name}/deny -- deny a pending request. Body: {"decided_by": "..."}.

Related