Monitoring and Debugging Multi-Agent Systems

Why Multi-Agent Systems Are Harder to Debug

A single-session workflow fails in front of you. You see the error, you see what tool call caused it, you fix it and continue. Multi-agent systems fail differently. A background agent might silently produce wrong output. A nested agent three levels deep might hit a permission error that surfaces only as a missing result in the parent. A parallel agent might run fine but return results that conflict with another agent's findings.

Debugging these systems requires tools beyond the main session's conversation view.

The Agent View

The Agent view, launched in May 2026, gives you a live dashboard of all subagents active in your current session.

Access it with: claude agents

The view shows each active subagent with:

• Status: running (actively executing a turn), blocked (waiting for a permission approval), or done (finished and summarized)
• Current tool: the tool the agent is currently calling, if any
• Elapsed time: how long the agent has been running

Blocked agents are the most important status to catch. A blocked agent is waiting for a permission approval that will never come unless you approve it in the main session. Permission prompts from background agents surface in the main session labeled with the agent's name — look for them if an agent appears blocked.

Reading Transcript Logs

Every subagent writes a complete transcript to disk during its run:

~/.claude/projects/{project-hash}/{session-id}/subagents/agent-{agent-id}.jsonl

Each line is a JSON object. The key event types to look for:

• Tool call events: what tool was called, with what inputs
• Tool result events: what the tool returned (or what error it raised)
• Model turn events: Claude's reasoning and response text
• Final result: the summary the agent returned to the parent

To find the transcript for a specific agent, note the agent ID from the Agent view (or from the parent conversation's tool call output) and look for the corresponding agent-{id}.jsonl file.

Common Failure Modes and How to Diagnose Them

Silent failure: the agent finishes but the result is wrong or incomplete.
Check the transcript. Look at the final tool calls and model turns before the result was returned. Often the agent encountered an error, decided the task was "done enough," and summarized incorrectly. The transcript shows exactly where the reasoning went wrong.

Permission block: the agent is stuck waiting.
Check the Agent view for blocked status. Look in the main session for a permission prompt with the agent's name. Approve it there. For recurring permission blocks on specific tools, add those tools to the agent's permissionMode: acceptEdits or pre-approve them in the agent definition.

Context exhaustion: the agent stops mid-task with a context limit error.
The agent's transcript will show a truncation or compaction event near the end. Solutions: narrow the agent's tool access so it reads fewer files, split the task into smaller subtasks, or use the Explore subagent type for read-heavy research tasks (it is optimized for searching without loading full file contents into context).

Conflicting results from parallel agents.
This is expected when multiple agents investigate the same code from different angles. The orchestrator's job is to synthesize conflicts, not expect agreement. If you see conflicting results and want to resolve them automatically, spawn a dedicated reconciler agent that receives both reports and produces a unified finding.

Using Hooks for Structured Logging

For complex pipelines in production, transcript files alone are not enough. Add structured logging via SubagentStart and SubagentStop hooks that write to a central log:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/scripts/log-agent-start.py"
          }
        ]
      }
    ],
    "SubagentStop": [
      {
        "matcher": "*",
        "hooks": [
          {
            "type": "command",
            "command": "python3 ~/.claude/scripts/log-agent-stop.py"
          }
        ]
      }
    ]
  }
}

Each script receives the hook's JSON payload on stdin, which includes the agent type, agent ID, and event metadata. Write it to a structured log file so you can trace the full execution history of every agent in your pipeline across sessions.