Incident Review Playbook For Agent Sessions

Start With A Narrow Question

Do not begin an agent incident review by reading an entire transcript line by line. Start with one question: Did it change files it should not have changed? Did it spend too much? Did it stall? Did it use a denied tool? Did it summarize work inaccurately? The question determines which evidence to pull first.

For file-change surprises, start with git diff and tool events. For cost spikes, start with usage and model fields. For stalls, start with API errors, retry events, and long tool durations. For policy concerns, start with tool decision and hook events.

Build A Minimal Timeline

Create a timeline with five columns: time, actor, event, evidence pointer, and reviewer note. Actor can be user, main agent, subagent, hook, tool, or external service. Evidence pointer can be transcript line, OpenTelemetry event ID, git SHA, CI URL, or issue link.

The goal is not to recreate every token. The goal is to explain the decision path well enough that a maintainer can reproduce the failure or accept the fix.

• Mark the first prompt that made the risky action possible.
• Mark the first tool call that changed or could have changed state.
• Mark any hook denial, permission escalation, retry exhaustion, or context reset.
• Mark the final verifiable repository state.

Review Cost Without Overclaiming

The SDK cost fields are estimates, but they are still useful for incident review. Compare cost and tokens to session outcome. A long research run may be acceptable; a no-output loop is not. Break down per-step usage where available so one expensive model request does not get confused with the entire session.

Do not assign blame from cost alone. Pair it with query source, model, tool activity, cache behavior, and whether the session reached a valid stop.

Close The Loop

A good closeout has one paragraph of finding, one paragraph of evidence, one paragraph of prevention, and links to the raw internal artifacts. If the transcript includes sensitive data, link to the governed internal copy and publish only the redacted summary.

If the root cause belongs to context management, link the follow-up to Claude Context territory. If it belongs to project memory or instructions, link to Claude Memories. Claude Logs should stay focused on the evidence and review method.