The fastest way to debug a failing agent is not a better prompt; it's a better record of what the tools changed. Chat logs capture what the model said. A run receipt captures what the workspace did. Keep the second, and the first becomes optional.
Most agent debugging starts too late. The run fails, the transcript scrolls away, and you're left reconstructing history from git blame and guesswork. That is archaeology, not debugging. Observability for an agent run has to be written down at the moment of each tool call, by a wrapper that does not care which model produced the call.
Think of a courier. The tracking page says "in transit" and then "delivered", and nobody can tell you which driver stopped where or who signed. An agent is worse, because each step mutates a shared filesystem. A courier that issued a signed receipt per stop would be simple to audit. An agent that emits one JSON line per tool call is exactly that.
The minimal version needs three ingredients: a stable run id, a git workspace, and a wrapper around the tool-call boundary. The skeleton below is unexecuted example code, not a tested library; adapt it to your agent's loop.
// receipt.js — one JSONL record per tool call
