Preflight Checklist

• I have searched existing requests and this feature hasn't been requested yet
• This is a single feature request (not multiple features)

Problem Statement

When Claude Code spawns sub-agents via the Task tool, all hook events share the same session_id regardless of which agent produced them. This makes it impossible to:

1. Identify which agent generated an event - A session with 3 parallel agents produces 50+ events with no way to attribute them
2. Track when sub-agents start - Only SubagentStop exists, not SubagentStart
3. Capture intermediate text output - Claude's explanations between tool calls are not exposed to hooks

This limitation prevents building observability tools, debuggers, or dashboards for multi-agent workflows.

Proposed Solution

Proposed Solution

1. Add agent hierarchy fields to all hook events

interface HookEvent {
// Existing fields
session_id: string;
hook_event_type: string;
// ...

// New fields
agent_id?: string;           // Unique ID of the agent that produced this event
parent_agent_id?: string;    // ID of the agent that spawned this one
parent_session_id?: string;  // Session ID of the parent (if different)
agent_slug?: string;         // Human-readable agent type (e.g., "Explore", "Plan")

}

2. Add SubagentStart hook

Fires when a sub-agent is spawned via the Task tool:
{
"hook_event_type": "SubagentStart",
"agent_id": "new-agent-id",
"parent_agent_id": "parent-id",
"subagent_type": "Explore",
"description": "Search for auth patterns"
}

3. Add AssistantOutput hook (optional)

Fires when Claude outputs text between tool calls:
{
"hook_event_type": "AssistantOutput",
"text": "I'll search for existing authentication patterns first...",
"is_final": false
}

Alternative Solutions

No response

Priority

Critical - Blocking my work

Feature Category

Configuration and settings

Use Case Example

Context

I'm building an observability dashboard that visualizes Claude Code sessions in real-time. The dashboard shows a canvas with nodes representing sessions, event timelines, and a detail panel for inspecting activity.

Scenario: User Asks Claude to Plan and Implement a Feature

Step 1: User submits prompt
User: "Plan how to add authentication to my app, then implement it"

Step 2: Claude spawns sub-agents
Claude decides to use the Task tool to spawn parallel agents:

• Plan agent - designs the authentication architecture
• Explore agent - searches codebase for existing auth patterns

Step 3: Sub-agents execute
Both agents run simultaneously, each making multiple tool calls (Read, Grep, Write, etc.)

Current Behavior (The Problem)

My hooks receive events, but all events have the same session_id:

{"session_id": "abc-123", "hook_event_type": "PostToolUse", "tool_name": "Read", ...}
{"session_id": "abc-123", "hook_event_type": "PostToolUse", "tool_name": "Grep", ...}
{"session_id": "abc-123", "hook_event_type": "PostToolUse", "tool_name": "Read", ...}
{"session_id": "abc-123", "hook_event_type": "PostToolUse", "tool_name": "Write", ...}

Result in my dashboard:

• ❌ Cannot show separate nodes for each agent on canvas
• ❌ Cannot group events by which agent produced them
• ❌ Cannot draw parent→child relationship edges
• ❌ All 50+ events appear in one flat timeline
• ❌ User cannot tell which agent did what

Additionally, Claude's explanatory text like "I'll search for existing auth patterns first..." never reaches my dashboard because there's no hook for intermediate output.

Desired Behavior (With Proposed Features)

Hook events would include agent hierarchy:

{"session_id": "abc-123", "agent_id": "abc-123", "hook_event_type": "PostToolUse", "tool_name": "Task", ...}
{"session_id": "abc-123", "agent_id": "plan-456", "parent_agent_id": "abc-123", "hook_event_type": "SubagentStart", ...}
{"session_id": "abc-123", "agent_id": "explore-789", "parent_agent_id": "abc-123", "hook_event_type": "SubagentStart", ...}
{"session_id": "abc-123", "agent_id": "plan-456", "hook_event_type": "PostToolUse", "tool_name": "Read", ...}
{"session_id": "abc-123", "agent_id": "explore-789", "hook_event_type": "PostToolUse", "tool_name": "Grep", ...}

Result in my dashboard:

• ✅ Canvas shows 3 nodes: Parent → Plan agent, Parent → Explore agent
• ✅ Events grouped by agent in timeline
• ✅ Purple edges connect parent to children
• ✅ User can expand each agent to see its specific activity
• ✅ Clear visualization of parallel execution

Summary

These features would enable building proper observability tooling for complex multi-agent workflows, which is increasingly important as users leverage Claude Code's Task tool for parallel execution.

Additional Context

No response