Template
Approval Workflow
Pause before irreversible, external, costly, or permissioned actions.
Use
Workflow Guidance
Use when an agent sends, publishes, spends, modifies records, or changes external state.
Human Control
Users see impact, affected objects, cost, provenance, and rollback before approving.
What Can Fail
The action scope changes after preview, rollback is unavailable, or permission is insufficient.
Recovery Behavior
Invalidate the approval, refresh the preview, and require a new confirmation.
State Matrix
Required States
A template is only useful when it shows normal, blocked, and recovery states.
State Coverage
User sees
System does
User sees
System does
User sees
System does
| State | User Sees | System Does |
|---|---|---|
| Preview | Action summary, affected objects, and reversibility. | Locks the preview payload used for approval. |
| Approved | Committed action with audit trail. | Executes the exact approved payload. |
| Revoked | Approval expired or changed. | Requires a fresh review before execution. |
Implementation
Pattern Pieces
Templates are guidance; registry items stay smaller so teams can compose them into their own product surface.
| Element | Spec |
|---|---|
| Observable Work | A step disclosure pattern for showing visible agent work, touched sources, state, and completion without exposing hidden reasoning traces. |
| Action Preview | A locked consequence preview for approvals, external actions, document changes, and rollback-aware agent work. |
| Decision Surface | A composable confirmation surface for approvals, risky actions, clarifying interruptions, and rollback decisions. |
| Badge | Stock shadcn/ui badge used for status, scope, and state labels. |
- ApprovalRisky external actions use a Decision Surface before execution.
- ProvenanceSources, memory, cost, and owner metadata stay visible at the decision point.
- RecoveryBlocked states expose the next input needed instead of showing indefinite activity.