manage-approvals

name	manage-approvals
description	Human-in-the-loop approval workflows for governed agent actions
license	MIT
metadata	{"author":"ucsandman","version":"1.0.0","category":"operations"}

Manage Approvals

DashClaw's HITL (Human-in-the-Loop) system lets operators approve or deny agent actions before they execute. Three channels: dashboard, CLI, and SDK polling.

When Approvals Trigger

Approvals are triggered when:

1. A guard policy returns require_approval
2. An action's risk score exceeds the org's approval threshold
3. The action touches systems flagged for mandatory review

The action enters pending_approval status and the agent waits.

Approval Channels

1. Dashboard (Web UI)

Navigate to the DashClaw dashboard → Approvals or Decisions view. Pending approvals show with:

• Action type and declared goal
• Agent ID
• Risk score (color-coded)
• Systems touched
• Replay link for full decision context

Click Approve or Deny with optional reasoning.

2. CLI (Terminal)

# Interactive inbox — live updates via SSE
dashclaw approvals

# Direct approve/deny
dashclaw approve act_abc123 --reason "Reviewed deployment plan"
dashclaw deny act_abc123 --reason "Missing staging verification"

The interactive inbox (dashclaw approvals) uses SSE for real-time push notifications. New approval requests appear immediately without polling.

Keyboard shortcuts:

• A — Approve selected
• D — Deny selected
• R — Refresh
• O — Open replay in browser
• Q — Quit

3. SDK Polling (Agent-Side)

// Agent waits for approval after guard returns require_approval
try {
  await claw.waitForApproval(decision.action_id, {
    timeout: 300000  // 5 minutes
  });
  console.log('Approved — proceeding');
} catch (err) {
  if (err instanceof ApprovalDeniedError) {
    console.log('Denied:', err.message);
    return;
  }
  throw err;
}

try:
    claw.wait_for_approval(decision["action_id"], timeout=300000)
    print("Approved — proceeding")
except ApprovalDeniedError as e:
    print(f"Denied: {e}")
    return

4. API Direct

# Approve
curl -X POST "$DASHCLAW_BASE_URL/api/approvals/act_abc123" \
  -H "x-api-key: $DASHCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision": "approved", "reasoning": "Reviewed and safe"}'

# Deny
curl -X POST "$DASHCLAW_BASE_URL/api/approvals/act_abc123" \
  -H "x-api-key: $DASHCLAW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"decision": "denied", "reasoning": "Risk too high"}'

Full Approval Flow Architecture

Agent calls claw.guard({ action_type, risk_score, ... })
        ↓
Guard evaluates policies → returns require_approval
        ↓
Action created with status: pending_approval
        ↓
Agent calls claw.waitForApproval(actionId)
   (polls or uses SSE stream)
        ↓                              ↓
Operator sees in dashboard/CLI    Operator opens CLI inbox
        ↓                              ↓
Reviews: goal, risk, systems      Uses A/D keys or direct command
        ↓                              ↓
        └──────── Decision ────────────┘
                    ↓
           approved → agent continues
           denied → ApprovalDeniedError thrown
           timeout → blocked (enforce) or allowed (observe)

Claude Code Hook Approval Flow

When using the pretool/posttool hooks with Claude Code:

1. Claude Code calls a tool (e.g., Bash: git push origin main)
2. Pretool classifies: action_type=deploy, risk=80, reversible=false
3. Pretool calls POST /api/guard → gets require_approval
4. Pretool creates action with pending_approval status
5. Pretool polls for approval (30-second timeout)
6. Operator approves via dashclaw approvals in another terminal
7. Pretool receives approval → exits 0 → tool executes
8. Posttool records outcome → PATCH /api/actions/:id

If approval times out or is denied, pretool exits 2 (enforce mode) and the tool is blocked.

Listing Pending Approvals

// SDK
const pending = await claw.getPendingApprovals({ limit: 50, offset: 0 });

// API
// GET /api/actions?status=pending_approval&limit=50

Approval Best Practices

• Use SSE for real-time: The CLI inbox uses SSE streaming so approvals appear instantly
• Set reasonable timeouts: 5 minutes for interactive workflows, 30 seconds for hooks
• Include reasoning: Always provide reasoning when approving/denying — it's part of the audit trail
• Don't skip in production: HITL gates exist because the action is high-risk. Bypassing defeats the purpose.
• Use the replay link: Every action has a replay URL showing the full decision chain — use it to review context before approving