Docs / The agent
Traces and self-review
A local record of every turn, and read-only tools that let the agent catch its own loops.
Every turn the agent takes is recorded locally: each tool call, whether it succeeded, what failed, what was checked, and what it cost. Traces is the panel that shows that record, and a set of read-only tools lets the agent read the same record while it works, so it can notice that it is going in circles and change course.
Nothing here is sent anywhere. The record lives in your project and the panel and tools read it from disk.
Opening the panel
Open Traces from the sidebar, or search for it in the command palette (Ctrl+K). It shows the session for the conversation you are in, and you can switch to any earlier session from the dropdown.
The panel uses the full width of the window in three columns, each scrolling on its own.
| Area | Shows |
|---|---|
| Turns (left) | One row per turn: your prompt, rounds, tool calls, failures, edits, a health bar, and a marker if something serious was found. A filter limits the list to turns with problems |
| Verdict (centre) | A one-line read on the selected turn: clean, finished with warnings, or in trouble, with the main reason |
| Flight strip | One column per round, stacked by what happened in it (reads, edits, checks, failures). Notices and oscillation warnings are marked on it. Click a round to jump to it in the timeline |
| Diagnosis | Problems detected in the turn, each with a severity, the rounds involved, and a suggested correction |
| Timeline | Every tool call grouped by round, with filters for failures, edits, checks, and self-review. Failures show the error line |
| Session health (right) | Health across turns, so you can see where a session started to go wrong |
| Agent self-review | Each time the agent looked at its own trace, and each automatic notice with its outcome: whether the agent recovered, kept failing, or the turn ended |
| Recurring failures | Failures across the whole session, grouped by tool and message, so one blocked command repeated forty times shows up as one line |
| Token economy and files | Tokens, cache hit rate and cost, and the files the turn touched |
While a turn is running the panel refreshes every few seconds and shows a live indicator. Once the turn ends it stops polling.
What counts as a problem
Findings are computed from the record, not guessed by a model. A turn can produce any of these:
| Finding | Raised when |
|---|---|
| Repeated failure | The same tool fails three or more times with the same error. Numbers are ignored, so port 3001 and 3002 count as the same error |
| Edit churn | One file is edited five or more times in a single turn |
| Re-read loop | A file is read six or more times and never edited |
| Oscillation | The agent's reasoning flipped between competing explanations many times |
| Notice ignored | An automatic notice fired and the same failures continued in the next few rounds |
| Verification failing | The last build, test, or typecheck run failed |
| Never verified | Files were edited and no verification ran |
| Stale verification | Files were edited after the last passing check |
| Claim mismatch | The final summary contradicted what the workspace shows |
| Reverted | A change set was rolled back after failing verification |
| Text-only rounds | Three or more rounds produced no tool calls |
| Provider errors | Two or more model or connection errors in the turn |
| Context churn | The context was compacted three or more times |
The health score starts at 100 and drops for failures and findings. For finished turns it uses the score the harness already computed, so the panel and the command-line reports agree.
How the agent uses it
In Code mode the agent has four read-only tools. Plan mode gets the first and last.
| Tool | Returns |
|---|---|
trace_status | Where the current turn stands: round, failures, edits, verification state, cost, health, and the last few turns |
trace_turn | The round-by-round timeline of a turn, defaulting to the current one |
trace_errors | Failures grouped by tool and message, for the current turn or the whole session |
trace_diagnose | The findings above for the current turn, plus patterns that repeat across turns |
The agent is told to reach for them when something has failed more than once, when it suspects a loop, or before it claims a long, rocky turn is done. It is told not to call them on healthy turns.
Automatic notices
The harness also watches for the most common loops and, when it sees one, adds a short [TRACE_NOTICE] message to the conversation pointing the agent at trace_diagnose. It fires when:
- the same tool has failed three times in a row,
- three rounds in a row produced only failures,
- the agent's reasoning was flagged as flip-flopping, or
- fourteen rounds went by without a single file change, with at least three failed calls along the way. This catches an investigation that is going nowhere even though no single tool keeps failing. A long read-only review with no failures never triggers it.
Each situation produces one notice, and a turn gets at most three. A healthy turn gets none. The notice is a pointer, not an order: it suggests reading the trace, changing approach, and, if the blocker is outside the project (a missing credential, a service that is down), saying so plainly and stopping. It also tells the agent not to hunt the machine for credentials it was not given. The agent still decides what to do next, and the panel records whether it recovered.
Separately, the completion gate already refuses to end a turn that edited files without a passing verification. Traces does not replace that gate. It helps the agent see why it is failing before it gets that far.
Limits
These tools are meant to help a stuck agent, not to become something it loops on.
- Read-only. They cannot change files, settings, or the record itself.
- Each conversation turn allows 12 trace calls. After that the tool says the budget is spent and tells the agent to act on what it learned.
- Output is capped at a few thousand characters, summarized rather than dumped.
- The agent sees only the current project's current session. It cannot read other projects.
- A trace call is not a guarantee of a better next step. A weak model can still ignore the advice.
Where the data lives
Sessions are JSONL files under .rescriptum/editor/sessions/ in your project, one per conversation. The IDE adds .rescriptum/ to the repository's local git exclude, so these files stay out of your commits. Delete a file to remove that session from the panel.
Tool output previews in the record can contain code or command output from your project. If you share a session file, review it first.
This is separate from sharing fixes with other people. Traces never uploads anything. Any future option to contribute redacted failure patterns to a shared library would be off by default and shown in the interface before anything was sent.
Related
- Verification and rollback covers the checks the findings refer to.
- Headless harness scores recorded sessions from the command line.
- Tools lists everything else the agent can call.