Include agent_id in PostToolUse hook payloads for subagent attribution

Status Fixed / completed

Maintainer reply None cached

Activity 4 comments · opened Feb 1, 2026 · closed Feb 1, 2026

Problem

When multiple subagents run in parallel, hooks cannot determine which subagent made a specific tool call. The PostToolUse payload includes tool details but no agent context.

Current behavior

SubagentStart and SubagentStop hooks receive agent_id in their payloads, but PostToolUse does not:

// SubagentStart - has agent_id ✓
{"hook_event_name": "SubagentStart", "agent_id": "a1fd75b", ...}

// PostToolUse - missing agent_id ✗
{"hook_event_name": "PostToolUse", "tool_name": "Read", "tool_input": {...}, ...}

Impact

With 3 parallel subagents, all tool operations get attributed to a single agent (whichever is on top of a tracking stack), making activity logs inaccurate:

{"type": "glob", "agent_id": "a50287d"}  // Actually from agent 1
{"type": "read", "agent_id": "a50287d"}  // Actually from agent 3
{"type": "glob", "agent_id": "a50287d"}  // Actually from agent 2

Proposed solution

Include agent_id in PostToolUse (and ideally all tool-related hook payloads) when the tool call originates from a subagent:

{
  "hook_event_name": "PostToolUse",
  "tool_name": "Read",
  "tool_input": {"file_path": "/path/to/file"},
  "agent_id": "a1fd75b",  // <-- Add this field
  "session_id": "...",
  ...
}

For main agent calls, agent_id could be "main" or omitted.

Use case

Building activity tracking/context systems that log which agent performed which operations. Accurate attribution is essential for debugging multi-agent workflows and understanding agent behavior patterns.

View original on GitHub ↗

4 Comments

github-actions[bot] · 8 months ago

Found 3 possible duplicate issues:

This issue will be automatically closed as a duplicate in 3 days.

If your issue is a duplicate, please close it and 👍 the existing issue instead
To prevent auto-closure, add a comment or 👎 this comment

🤖 Generated with Claude Code

kyzzen · 8 months ago

Additional context from binary analysis

Claude Code already includes agent_id in SubagentStart/Stop hook payloads:

// SubagentStart
{"hook_event_name": "SubagentStart", "agent_id": "a497c23", "agent_type": "Explore", ...}

// SubagentStop  
{"hook_event_name": "SubagentStop", "agent_id": "aa678a8", "agent_transcript_path": "...", ...}

But PreToolUse/PostToolUse omit it:

// PostToolUse - no agent_id
{"hook_event_name": "PostToolUse", "tool_name": "Read", "tool_input": {...}, "tool_response": {...}, ...}

The tool_use_id is just toolu_XXXXX with no agent correlation.

Since agent_id tracking already exists for subagent lifecycle hooks, this should be a matter of threading it through to tool use hooks when the call originates from a subagent context.

kyzzen · 8 months ago

Closing as duplicate of #16424, which provides a more comprehensive proposal covering agent identification across all hook event types (PreToolUse, PostToolUse, PostToolUseFailure, Notification, PreCompact).

The evidence from our investigation (agent_id exists in SubagentStart/Stop but not in tool use hooks) supports the implementation path described in #16424.

Upvoting #16424 instead.