Show the user the next decision, not every artifact the agent produced.
Show the user only the next decision they need to make — when to surface the chain of thought, the tool call, the diff; and when to keep it folded. Sits beside approval & confirmation UX: that one is about what to confirm; this one is about how much to show while confirming.
Agents produce more artifacts than any user wants to read.
A single agent turn now emits a planning trace, a tool-call argument list, an observation, a partial diff, sometimes a follow-up plan, and a final natural-language reply. Dumping all of it into the UI is the visual equivalent of leaving console.log statements in production — it is debugging output exposed to end users, and it competes with the one thing they actually need to evaluate: the next decision in front of them.
Progressive disclosure is the discipline of treating each of those artifacts as collapsible rather than printable. The default is folded; the user expands only when they have a reason to. The agent does not get to claim the user's attention just because it generated bytes.
Four expand-collapse layers, in order of "always show" → "show on demand".
Useful agent UIs converge on roughly four layers:
- Layer A — the action being requested or taken. Always shown, never folded. One sentence: "Send invoice #4218 to Acme for $12,300." This is what the user is being asked to evaluate.
- Layer B — the structured payload. One click away. The exact diff, tool arguments, or destination. The user reaches for this when Layer A is ambiguous or the stakes feel high.
- Layer C — the reasoning. Two clicks away, or off by default. The plan, the chain of thought, the retrieved context the agent leaned on. Useful for debugging trust, not for routine flow.
- Layer D — raw traces. Debug-only. Token-level logs, raw model output, internal scratchpads. Hidden behind a developer toggle; never on the user's default view.
The order is not aesthetic — it is calibrated to how often each layer changes a decision. Layer A always does. Layer D almost never does. Real estate on the default view should be allocated in that order.
Surface one next decision at a time. Don't bundle approvals.
The dual failure mode of "show everything" is "ask for everything." A panel that simultaneously asks the user to approve a draft email, confirm a calendar invite, and authorize a refund is a panel where one of those decisions gets attention and the other two get a reflex click. Progressive disclosure applies to the decision queue too: present one consequential gate, let the user clear it, then present the next.
This is not about hiding work — the agent can run safe parallel actions in the background and queue up the human checkpoints. What progressive disclosure forbids is stacking unrelated decisions into a single confirmation surface. Each gated action gets its own focused view, with its own Layer A through D.
"Approve all" as a default button is the architectural opposite of progressive disclosure. It exists only so the user can clear the queue without reading. Either tier those actions to not need approval, or give each one its own gate — never both at once.
When to break the rule.
Progressive disclosure is the right default, not a universal law. Three legitimate exits:
- High-trust expert users on a hot path. A reviewing engineer running 80 agent diffs an hour benefits from Layer B (the diff) being open by default — Layer A alone wastes a click. Make this a per-user setting; do not flip it for everyone.
- Batch workflows. Reviewing 50 classifier decisions at once is a different task than handling one consequential action; a denser table view that exposes more per row earns its keep here.
- Debug / "show me everything" mode. A toggle that opens Layers C and D for the current session, for the user who is actively diagnosing why the agent did something weird. Off by default; opt-in; resets at session end.
In all three cases the user is explicitly choosing more density. The anti-pattern is making that choice for them.
The anti-patterns to design against.
Three recurring shapes will fight you if you let them:
- The overloaded modal. A confirmation dialog that includes the diff, the reasoning, and a follow-up question all in one. The user reads none of it. Split it into Layer A + an expand affordance for Layer B.
- The chat-only UI that hides the diff. A chat transcript that says "I updated three files" without showing which lines changed pretends to be simple but is actually opaque. Layer B must be reachable from the chat turn, not buried in a separate panel.
- Default-expanded chain of thought. Showing every internal monologue by default trains users to scroll past it, which then trains them to scroll past the actions too. Reasoning lives at Layer C precisely so users learn to expand it when, and only when, they need it.
The test is simple: ask whether the next decision is the first thing on the user's screen, and whether everything else is one well-labeled click away. If not, you have a progressive-disclosure bug, regardless of how pretty the layout looks.