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.

Anatomy

01
Named stages
The run broken into the decisions it makes, each named in the user's vocabulary rather than the system's.
02
Current stage
Which of those stages it is in now, so a person can tell where a correction would land.
03
Stop
One control beside the work, reachable while it runs.
04
Assumptions first
The premises of the first stage, shown before the second begins.
05
Redirect
A correction to one step that the run continues from, rather than a restart.

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.

Do and don't

Do
Put a stop control beside the work while it runs.
Don’t
Stream the reasoning with nothing the person can do about it.
Watching a run go wrong with no way to halt it is worse than a spinner, which at least does not tell you it is making a mistake.
Do
Show the decision points: what it chose to do, and why.
Don’t
Stream every token of deliberation, or reduce the whole run to "Thinking…".
One is volume mistaken for openness and the other gives nothing to act on. A decision point is the grain a person can disagree with.
Do
Name each step in the words the user already uses for their own material.
Don’t
List queries, tool names and internal identifiers.
If a person cannot form an opinion about a step, showing it is decoration with a performance cost.
Do
Let the person change one step and continue from there.
Don’t
Show the plan and then run it regardless.
A plan nobody can change asks for an approval the product has no way to receive.
Do
Surface the first stage's assumptions before the second begins.
Don’t
Present conclusions fluently and leave the assumptions out.
The assumption is where the error was. Most agent failures are a wrong premise in the first step, developed faithfully for the next twenty.

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.