[FEATURE] 1. Agent Hierarchy in Hook Events, 2. Intermediate Text Output Hook, 3. SubagentStart Hook

Preflight Checklist

• [x] I have searched existing requests and this feature hasn't been requested yet
• [x] 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")
}

1. 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"
}

1. 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

<img width="1310" height="719" alt="Image" src="https://github.com/user-attachments/assets/e40d0382-eb1d-424c-9873-18451a5c922a" />

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

| Feature | Enables |
|----------------------|---------------------------------|
| agent_id in hooks | Grouping events by agent |
| parent_agent_id | Drawing hierarchy edges |
| SubagentStart hook | Knowing when agents spawn |
| AssistantOutput hook | Capturing Claude's explanations |

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_