Investigating Sessions and Agents

Investigating Sessions and Agents

An investigation should answer four questions: what was requested, who performed each part, what actually happened, and what evidence supports the conclusion.

Start from the session

Open the session and establish:

• provider, project, source, start time, and current state;
• the original user intent or earliest available transcript context;
• whether subagents were created;
• the newest event and newest transcript timestamp;
• token/cost totals and any unusual spike.

Do not jump directly to the final error. The preceding tool call, permission decision, or agent handoff often explains it.

Follow the agent tree

For each agent, note its parent, task, state, and latest activity. A main agent marked waiting may be behaving correctly while a child is still working. Conversely, a child marked active with no advancing events may be the actual stalled unit.

Useful CLI cross-checks include:

npx ccam sessions
npx ccam session <session-id>
npx ccam agents --session <session-id>
npx ccam events --session <session-id>
npx ccam transcript <session-id>

Run npx ccam <command> --help for the current filters and output modes.

Reconstruct the sequence

Build a compact timeline:

1. user request or task creation;
2. agent delegation;
3. tool invocation;
4. tool result or error;
5. agent response, retry, or termination.

Timestamps from different machines can be misleading if clocks drift. For remote sources, also compare event order and transcript file activity.

Distinguish failure types

Symptom	Likely layer	Next check
No session exists	Hook/import	Hook Health
Session exists, no recent events	Producer or ingestion	Process state, hook logs, remote source status
Events exist, UI is old	Client/live connection	Reload and compare CLI/API output
Tool failed but agent continued	Workload/tool	Inspect later transcript entries
Costs seem wrong	Pricing/usage normalization	Audit an Expensive Session

Record a useful finding

A good incident note includes the session ID, source, provider, affected time range, last good event, first bad event, active filters, and whether CLI/API results matched the browser. Redact prompts, paths, and tool results before sharing outside the trusted team.

Related recipes: Trace a Failed Tool Call and Recover Missing History.