[FEATURE] Expose Agent Context in Hook Event Payloads for Multi-Agent Observability

Found 3 possible duplicate issues:

1. https://github.com/anthropics/claude-code/issues/16126
2. https://github.com/anthropics/claude-code/issues/7881
3. https://github.com/anthropics/claude-code/issues/6885

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

This proposal addresses gaps in existing issues with a minimal, backward-compatible solution.

This issue is still needed for global hook agent identification

After reviewing recent changelog updates (particularly v2.1.0), I wanted to provide some context on the current state.

What v2.1.0 improved

v2.1.0 introduced hooks support in agent frontmatter, allowing hooks to be scoped to specific agents. This is a useful addition—you can now attach monitoring or policy hooks directly to individual agent definitions as a workaround for some scenarios.

Why this issue is still necessary

However, global hooks (defined in .claude/settings.json at project or user level) are still triggered by both the main agent and all subagents. When a global hook fires, there is still no way to determine:

• Whether it was triggered by the main agent or a subagent
• If it was a subagent, which specific subagent triggered it

This is exactly what this issue requests: exposing agent_id, agent_type, and agent_transcript_path in the hook event payload.

Summary

Agent-scoped hooks (v2.1.0) allow you to attach hooks to specific agents, but they don't solve the problem of identifying the source agent when a global hook is triggered. For centralized observability, logging, or policy enforcement across all agents, this feature request remains necessary.

+1 for this proposal.

My use case: Building a context-tracking hook system that logs file operations per-agent. Currently impossible to attribute operations correctly when 3+ parallel agents run.

Evidence from testing: Spawned 3 parallel Explore agents - all file ops got attributed to a single agent because get_current_agent_id() returns stack top:

{"type": "glob", "agent_id": "a50287d"}  // All three agents' ops
{"type": "read", "agent_id": "a50287d"}  // get same agent_id
{"type": "glob", "agent_id": "a50287d"}  // from stack top

Binary analysis confirms: agent_id and agent_type already exist in SubagentStart/Stop payloads - just needs threading through to tool use hooks.

The minimal 3-field approach (agent_id, agent_type, agent_transcript_path) is exactly right. Hierarchical fields can come later if needed.

yes that would be reallyt nice

We ran into this exact problem — our PreToolUse hooks enforce different behavior for the main agent (force background bash, block large TaskOutput) that breaks subagents. Here's the workaround we're using in the meantime.

Detection: is this tool call from the main agent or a subagent?

The hook input includes tool_use_id (the toolu_* ID of the current tool call) and transcript_path (the main session transcript). Main agent tool calls appear in the main transcript as assistant messages with tool_use content blocks. Subagent tool calls only appear in their own JSONL transcripts under <session-dir>/subagents/.

So: grep -q <tool_use_id> <transcript_path> — if found, it's the main agent. If not, it's a subagent.

Follow-up: which subagent?

The subagent transcripts live at <transcript_path minus .jsonl>/subagents/agent-*.jsonl. Grep each for the tool_use_id — the one that matches is the calling subagent, and the agent ID is in the filename.

Handling transcript flush race:

The hook fires while the assistant message is being written to the transcript, so grep may not find the tool_use_id yet. We use exponential backoff (50ms → 4s): check main transcript, check subagent transcripts, sleep, retry. If neither matches after timeout, sys.exit(1) (fail open — tool proceeds, error logged in verbose mode only).

def is_main_agent_call(tool_use_id, transcript_path):
    wait = 0.05
    while wait <= 4.0:
        if grep_for(tool_use_id, transcript_path):
            return True
        for sa in glob(f"{transcript_path.replace('.jsonl', '')}/subagents/agent-*.jsonl"):
            if grep_for(tool_use_id, sa):
                return False
        time.sleep(wait)
        wait *= 2
    sys.exit(1)  # fail open

This works but is fragile — transcript structure is undocumented, the backoff adds latency to every guarded hook call, and concurrent subagents could hit race conditions. Would love to see agent_id in the hook payload to replace all of this.

See also #14859

🤖 Generated with Claude Code

+1

+1 this is something that has been really frustrating to deal with in our hooks. Thanks for the detailed investigation.

+1 — Built a full observability pipeline (PostToolUse → JSONL logger + SubagentStart/SubagentStop → marker files) and hit this exact wall.

Workaround we use: SubagentStart writes per-agent markers to /tmp/claude_subagent_{session_id}_{agent_id}, PostToolUse globs them to list active agents. With parallel subagents, we can only log all active agents — no way to attribute a specific tool call to a specific subagent.

Additional note: sessions-index.json and type:summary transcript entries (used for session auto-naming / /rename) appear to have stopped being written as of ~v2.1.40+. This breaks any hook-based attempt to correlate session names with agent activity. Exposing agent_id in PostToolUse would solve both attribution and naming.

+1 - The 3-field approach is the right minimal surface. Worth noting: the Agent SDK already passes tool_use_id to SubagentStop callbacks and references parent_tool_use_id in the troubleshooting section, so the runtime already tracks these associations internally.

Additional Use Case: Policy Enforcement via Environment Variable

This comment adds a complementary perspective to the excellent observability-focused proposal above — specifically the security/policy enforcement use case and an alternative implementation path.

Our Use Case: Orchestrator/Executor Pattern Enforcement

In delegation workflows, the main agent acts as an orchestrator and subagents execute implementation tasks. The goal is to enforce this separation via hooks:

• Block the main agent from directly writing code files (Write/Edit tools on .py, .js, .ts, etc.)
• Allow subagents to write those same files when delegated by the orchestrator

This is a compliance/guardrail pattern: the orchestrator should plan and delegate, not implement directly.

Why Current Workarounds Fail

We tested every available identifier:

| Identifier | Result |
|---|---|
| CLAUDECODE env var | Same in both |
| CLAUDE_CODE_ENTRYPOINT | Same in both |
| CLAUDE_CONFIG_DIR | Same in both |
| CLAUDE_SESSION_ID | Same in both |
| $$ (PID) | Same process — identical |
| $PPID | Same parent — identical |
| SubagentStart/SubagentStop hooks + state file | Race conditions with parallel subagents |

Result: impossible to distinguish orchestrator from executor in hook bash scripts.

Alternative Implementation: Environment Variable

In addition to the JSON stdin approach proposed above, an environment variable would be simpler for bash hooks:

# Option A: env var set before hook execution
CLAUDE_AGENT_TYPE=main   # or "subagent"

# Hook script can then do:
if [[ "$CLAUDE_AGENT_TYPE" == "main" ]]; then
  if [[ "$TOOL_NAME" == "Write" ]]; then
    echo "Orchestrator cannot write code directly — delegate to subagent" >&2
    exit 2
  fi
fi

Compared to JSON stdin parsing (Option B in #16424), the env var:

• Requires no JSON parsing in bash scripts
• Is accessible to any subprocess spawned by the hook
• Can be checked with a simple [[ "$VAR" == "value" ]]

Both approaches (env var + JSON field) are complementary and could be shipped together.

Impact

| Without agent identification | With agent identification |
|---|---|
| Block ALL Write calls (breaks subagents) | Block only main-agent Write calls |
| Warn ALL (no enforcement possible) | Enforce orchestrator-executor separation |
| No delegation compliance hooks | Full hook-based delegation compliance |

This pattern benefits anyone building hook-based compliance, security, or delegation enforcement systems on top of Claude Code.

---

Strong +1 to this feature request. The env var addition would make the bash-hook use case particularly ergonomic.

We're hitting this exact limitation building an OTLP-based observability pipeline to track Claude Code usage across our team.
Out of three metric categories we need — sessions, skills, agents — agent tracking is completely blocked.
When tool_name ="Task", the tool_parameters field is empty. We can see "some Task executed" but have no way to determine which subagent type was invoked (Explore, Plan, custom agents), which model it used, or attribute cost.

Sessions work (via user_prompt events), skills work (via tool_parameters.skill_name on Skill tool calls), but agent usage is a blind spot.

The three fields proposed here — agent_id, agent_type, agent_transcript_path — would unblock this entirely. Even just agent_type alone in hook payloads and OTLP events would be enough for the most critical use cases: usage dashboards, cost attribution per agent type, and anomaly alerting, usage of skills in agents.

Strong +1 to this feature request

Very strong + 1 to this feature. Agent formatter doesn't really help to identify individual agents.
We struggle a lot trying to deduplicate per-agent work in our plugins.

If parallel agents use case is growing, being able to identify them is a must.

+1 on this. Running multi-agent workflows (tribe-lead coordinating squad-workers in worktrees) and hitting this exact blind spot.

Specific pain point: Sub-agent git commits are unverifiable after the fact. A sub-agent claims it committed, but since its internal tool calls (Bash, Edit, Write) don't appear in OTEL, we can't confirm what actually happened without manual git log --grep forensics. The Task tool only emits the spawn and return spans — everything in between is a black box.

What would unblock us: Agent context in hook payloads (as proposed here) would work great, provided we can emit those hook events as OTEL spans to a collector. Our pipeline is OTEL Collector → ClickHouse, and we need sub-agent tool calls to show up as nested child spans under the parent Task span so we can query them in ClickHouse alongside everything else.

Concretely, if hook events included agent_id, parent_agent_id, and agent_slug (as proposed in #14859), and we could forward those as span attributes to the OTEL collector, that would fully close the observability gap for multi-agent coordination workflows.

The workaround today (PreToolUse hook writing to a flat audit log) works but loses the parent-child span relationship that makes ClickHouse queries useful.

@AlexandrePh
This proposed only agent_id, agent_type and agent_transcript_path.
not agent_id, parent_agent_id, and agent_slug.

Please fix it. its is needed for observablitity

Would love to see this land. We run parallel agents across different models and the attribution problem is very real.

Right now we work around it with a receipt log (each agent action gets logged with the agent identity), but having agent_id and agent_type in hook payloads natively would simplify things a lot. parent_agent_id would be great too for tracking delegation chains.

For anyone dealing with this today, we built a receipt and audit system into IDE Agent Kit that tracks which agent did what. Not as clean as native hook support, but it works for production multi-agent setups.

Looks like they added agent_id to the hook event in 2.1.69.

Docs specifically mention the use cases described in this ticket.

https://code.claude.com/docs/en/hooks#common-input-fields

2.1.69
Added agent_id (for subagents) and agent_type (for subagents and --agent) to hook events

This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.