Design the Permission Approval UX
Design approval prompts users actually read: diffs, risk framing, scoped grants, and pacing that prevents approval fatigue.
The route
4 steps to Done
- 01
Audit the current approval moments
Count them, read them, feel the fatigue.
Preview prompt + verify gate ▾ Hide ▴
Audit approvals as they exist. Instrument or review recent sessions and collect: approvals per task (average and worst case), what each prompt actually displayed, time-to-decision per approval, and any decline-then-nothing dead ends. Classify prompts by information sufficiency: could the user decide correctly from the prompt alone, or did they approve on faith? Interview or observe one real user session if possible. Deliver the audit: the fatigue numbers, the faith-approval percentage, and the three worst prompt examples verbatim.
- ✓ Approvals-per-task measured
- ✓ Faith approvals identified honestly
- ✓ Worst prompts captured verbatim
- 02
Rebuild the prompt content
Decisions need diffs, commands, and consequences - inline.
Preview prompt + verify gate ▾ Hide ▴
Redesign the approval prompt per action type. FILE EDITS: render the unified diff (bounded to the changed hunks with context lines), the file path, and a one-line summary of intent; for new files show the full content when small, the head plus structure when large. COMMANDS: exact command string, working directory, a plain-language effect line ('installs package X globally'), and the rule that triggered the ask. NETWORK/EXTERNAL: destination, payload summary, and what data leaves the machine. Every prompt states the agent's stated reason for the action. Implement and verify each type renders correctly with realistic examples.
- ✓ Diffs render with hunk context
- ✓ Commands show cwd and effect line
- ✓ Triggering rule named on each ask
- 03
Make friction proportional to risk
Routine should be quick; dangerous should be impossible to miss.
Preview prompt + verify gate ▾ Hide ▴
Implement risk-tiered presentation. ROUTINE (session-tier edits, contained commands): compact prompt, single-key approve, muted styling. ELEVATED (installs, network, config changes): standard prompt, explicit approve button, distinct accent color. DANGEROUS (destructive patterns, protected-path overrides): unmissable styling per the app's danger tokens, blast-radius statement ('this deletes 34 files, not undoable'), a deliberate confirmation (typed phrase or hold-to-confirm), and no default focus on approve. Map the permission tiers from the hook layer to these presentation tiers. Verify with side-by-side screenshots that a user could never mistake tiers at a glance.
- ✓ Routine is one-action quick
- ✓ Dangerous requires deliberate confirmation
- ✓ Screenshot check confirms distinctness
- 04
Add scoped grants and measure the win
Fewer, better questions - proven with numbers.
Preview prompt + verify gate ▾ Hide ▴
Finish with grants and measurement. GRANTS: every session-tier prompt offers scope choices - allow once / allow for session / allow for this directory (where sensible); choices route to the grant store; an active-grants view supports revocation. BATCHING: when the agent plans N similar actions (editing 6 files for one refactor), offer one batched approval listing all targets rather than six prompts. MEASUREMENT: re-run the audit tasks and compare approvals-per-task, time-to-decision, and faith-approval rate against baseline; goal is fewer prompts with higher information, rules unchanged. Report the before/after table.
- ✓ Scope choices on session-tier prompts
- ✓ Batch approval for planned multi-edits
- ✓ Before/after table shows improvement without loosened rules
Research-backed
Sources behind this flow
Tier 1 · claude-code-internals
claude-code-book (SCUTBrothers)
A second book-length Chinese treatment of Claude Code's source ('Understanding Claude Code In Depth') with a compiled PDF and LaTeX sources. Focuses on turning the complex system into reusable engineering knowledge: source structure, runtime mechanics, permissions and extension points, security and context strategy.
Tier 4 · coding-agents
Cline
A leading VS Code agent that popularized the human-in-the-loop approval UX: every file edit and terminal command is presented for approval with diff previews, plan/act modes, and checkpoints.
Tier 4 · coding-agents
Roo Code
A fork-descendant of Cline that pushed multi-mode agent UX further: custom modes with per-mode permissions and prompts, letting one agent switch personas (architect, coder, reviewer) with different tool rights.
Tier 1 · claude-code-internals
Deep Dive: Dual-Defense Architecture - Prompt + Code
Argues that because LLMs are probabilistic, prompts alone are gambling and code alone wastes the model's flexibility. Maps how Claude Code pairs every soft prompt rule ('use Edit instead of sed', 'NEVER force-push') with an independent deterministic check (sed validators, destructive-git detection, sandbox gates), analyzes the four failure combinations of the two layers, and distills five reusable design principles for any tool-calling agent system.