Show the agent working

Tags: agents, transparency, control

Visible reasoning is treated as a transparency feature, which makes it a display problem, which makes it easy to ship something worse than showing nothing: a person watching a long, confident process go somewhere wrong, with no control and no idea at which step it stopped being recoverable.

Transparency without agency is a better view of the accident

The stream of thought is genuinely compelling to watch. It is also, on its own, the anxiety of witnessing without the power to intervene — and that is a worse experience than a spinner, because a spinner at least does not tell you it is making a mistake.

So the question is not how much reasoning should we reveal. It is what can the user do with what they see, and the answer determines everything else about the design.

Three capabilities make revealed work worth its screen space:

Stop it. Cheap, obvious, and absent from a startling number of products. If the user can see it going wrong and cannot halt it, the visibility was cruelty.
Catch a premise early. Most agent failures are not reasoning errors, they are a wrong assumption made in the first step and faithfully developed for the next twenty. Surfacing assumptions first is worth more than surfacing conclusions fluently.
Redirect without restarting. The strongest version. The user corrects one thing and the run continues from there, rather than being thrown away.

Granularity is the whole design

Too fine and it is unreadable: a token stream of deliberation is a wall nobody parses, and it hides the decisions inside the prose. Too coarse and it is useless: "working…" reveals nothing and invites no intervention.

The right grain is the decision points. What it chose to do, and why — not how it thought about choosing. Each one should be a thing a person can disagree with, in their vocabulary rather than the system's.

That last clause does real work. A list of SQL queries shown to someone who does not read SQL is noise wearing the costume of transparency. The test is whether a user could look at a step and form an opinion about it. If they cannot, revealing it is not oversight, it is decoration with a performance cost.

Grounded in

DocRobot's redaction pass — and it is worth saying plainly that this is not an agent in the chatbot sense. It is a process deciding what to strip out of a confidential document before that document is sent to a model. That makes it a cleaner test of the pattern than most agents: the decisions are concrete, they are named in the user's own vocabulary, and the step after them cannot be taken back.

The pass was built to be watched rather than trusted. Search for a client name, a date, an account number, and every match lit up in the document itself, with a count beside it. Nothing was barred silently. The user confirmed the pass and watched the terms go dark — and only then did Save & Upload exist as an option.

Every requirement on this page is in that sequence. The grain is the decision point: each match, in place, in terms the user already uses for their own material. The premise surfaces first, before anything irreversible — a missed account number caught on this screen costs nothing, and the same miss after upload cannot be caught at all. And the stop is not a button bolted onto a running process. It is structural: the irreversible step does not exist until the work has been seen.

Detection began as manual search and later became automatic, which is exactly when a screen like this changes character — from a tool the user operates to a process the user supervises. A pass that was already built to be watched is one that can take on that change without anyone having to trust it blind.

When not to

When the reasoning is longer than the task is worth. A three-second operation does not need a narrated plan.
When the steps are not meaningful to this user. See above: unreadable steps are not transparency.
When revealing the work reveals something it should not. Intermediate reasoning can contain material the output was careful to exclude — see answer within the boundary.
When the plan is shown after execution. Then it is a receipt. Useful for audit, useless for control, and it should not be mistaken for this pattern.

Anti-patterns

A stream of thought with no stop button. The most common shape, and the one this pattern exists to argue against.
Token-level reasoning as the disclosure. Volume mistaken for openness.
"Thinking…" as the whole of it. Nothing to act on, so nothing gained.
Steps in the system's vocabulary. Queries, tool names, internal identifiers.
A plan you cannot edit. Showing the plan and then running it regardless is asking for approval you have no mechanism to receive.
Surfacing conclusions fluently and assumptions not at all. The assumption is where the error was.

The smallest version worth building

Name the stages. Show which one it is in. Put a stop control next to it.

Then surface the assumptions of the first stage before the second begins — because that is the cheapest moment a correction will ever cost, and it is the one most products skip straight past.

Declare the inputs before the run — the same argument one step earlier, about what the run will need rather than what it is doing.
Undo over confirm — for the actions inside the run, where stopping is no longer enough.
Streaming is a commitment — streamed reasoning is published reasoning, and cannot be quietly revised.
Redaction moves to the export — where the same watched pass went once local inference moved the boundary it was guarding.