Reading Why a Run Actually Failed, Not Just That It Did
Why the diagnostics screen shows a failure code and a separate detail instead of the raw error message, and the measurement that led to building it at all.
"My agent run failed and I have no idea why" is one of the most common frustrations with any agent product, cloud or local. Piskes's diagnostics screen was built directly in response to that problem — and it's worth understanding both why it exists and why it's deliberately incomplete in one specific way.
The measurement that started it
The diagnostics feature exists because someone actually measured the problem instead of assuming it. Looking at a sample of 54 production runs, 12 had failed and 6 more had been abandoned outright — and none of those 18 could be explained beyond a stray console.error written into an isolate that had, by the time anyone went looking, already shut down and taken its context with it. That's a historical snapshot that motivated the feature, not a live number you should expect to see reproduced today — but it's the honest reason diagnostics exists at all: failures were happening and nobody could say why.
What the screen actually shows
Two habits from that origin story show up directly in how diagnostics presents failures now. First, it always shows a failure count against its denominator — "12 of 54," not just "12 failures" — because a bare count with no base rate is close to meaningless; a dozen failures out of 54 runs is a very different signal than a dozen out of 5,000.
Second, and more deliberately, it splits every failure into a code and a separate detail, and it does not surface the raw error_message directly. That's not a missing feature — it's a safety decision. The detail field of a failure can end up quoting whatever untrusted content a tool was reading when it failed, and echoing that content straight back onto a screen is exactly the kind of behavior a prompt injection attempt would be hoping for. Splitting code from detail lets you get a structured, categorized reason for the failure without the system reflexively repeating back arbitrary text it encountered along the way.
Using it
When a run fails, start with the code — it tells you the category of what went wrong without the risk of surfacing raw, potentially untrusted content. If the code alone isn't enough to understand what happened, the detail is there to give more context, but treat it as exactly that: additional context, not a guaranteed verbatim transcript of everything the run touched. That tradeoff — a little more friction diagnosing an edge case, in exchange for not blindly echoing untrusted content back onto your screen — is the deliberate design decision here, not an oversight.
The larger point is that "why did my run fail" now has a real, structured answer instead of a silent isolate and a console log nobody can retrieve. That's a meaningfully better starting point than what prompted the feature to get built in the first place.