Agents Should Show Their Work, Not Their Chain of Thought
Chain-of-thought traces are often wrong. Real transparency means showing the files read, commands run, and decisions made — not the reasoning monologue.
Chain-of-thought isn't transparency. When an AI coding agent shows you its reasoning before acting — "First I'll read the file, then I'll analyze the structure, then I'll make the edit" — that narration describes an intent, not a record of what happened. The actual transparency that matters for an AI coding agent is different: which files it read, which commands it ran, what it changed, and which decisions it made that weren't obvious from your prompt. Claude Code's tool call display gets closer to this than most agent UIs. But even it leaves gaps.
The Problem With Reasoning Traces
Chain-of-thought prompting (asking a model to reason step by step before answering) improves accuracy on certain task types. It does not produce a reliable account of what the model actually did. Reasoning traces are often post-hoc rationalizations — the model generates a plausible-sounding explanation of the steps it would take, then generates the output. The trace and the output are often generated somewhat independently.
This matters for trust. If a user reads the chain-of-thought and thinks they understand why the agent did what it did, they may trust the output more than they should. The trace says "I checked the types file first to understand the data model." Did it? You can't verify that from the trace. What you can verify is whether it called the Read tool on src/types/index.ts.
The tool call log is the ground truth. The reasoning trace is a narrative.
What "Showing Work" Actually Means
For a coding agent, showing work means surfacing the concrete record of its actions in the session:
- Files read: which files did the agent access, and when
- Files written or modified: exact diffs, not summaries
- Shell commands run: the exact command with arguments, the exit code, the output
- Decisions that weren't specified: when the agent chose an approach that wasn't in your prompt, that choice should be surfaced explicitly
Claude Code does the first three reasonably well. Every tool call is visible in the UI — you can see each Read, Edit, Bash invocation in sequence. That's a genuine record of what happened, not a narrative about what was planned.
The fourth item — surfacing non-obvious decisions — is where every agent tool has work to do.
Claude Code's Tool Call Display
The tool call stream in Claude Code is the closest thing the current generation of tools has to a real audit log. Each turn shows you the tool invocations in sequence:
✓ Read(src/components/Button.tsx)
✓ Read(src/components/Button.test.tsx)
✓ Edit(src/components/Button.tsx) — modified 3 lines
✓ Bash(npx tsc --noEmit) — exit 0
This is useful because it's verifiable. You can open Button.tsx and confirm the diff. You can re-run the type check yourself. The tool call log and the filesystem state are in correspondence — if they're not, something went wrong and you can see where.
The gap is that this display is designed for developers. It requires knowing what npx tsc --noEmit means, being able to read a diff, understanding why a particular file was read. For non-developer users of AI agents, the tool call display is noise, but there's no better alternative in the current UI.
What a Better Agent UI Would Look Like
For a non-developer user, the ideal agent transparency layer translates actions into intent:
| What happened | What it means |
|---|---|
Read 4 files in src/auth/ | Examined how authentication currently works |
Modified auth/session.ts (lines 47-53) | Updated how session tokens are generated |
Ran npm test auth | Verified the change doesn't break existing tests (all passed) |
This is still grounded in the concrete record — the file, the lines, the test result — but it's translated into intent that a non-developer can evaluate. Did the agent look at the right things? Did it change something in a place you didn't expect?
The translation shouldn't replace the raw record. It should sit above it, with the raw record accessible for anyone who wants to verify.
The Trust Model This Implies
Agent transparency has a specific goal: it should give the user enough information to decide whether to accept the agent's output without having to fully re-do the work themselves. That's the bar.
Showing chain-of-thought doesn't meet the bar because it's not verifiable. Showing tool calls meets the bar for developers. A translated action summary meets the bar for a broader audience.
The design question for any agent UI is: after the agent finishes, does the user understand what it did well enough to make an informed decision about whether to trust it? If the answer is "they have to take it on faith," the transparency layer isn't doing its job.