Issue Station
Sign In
Tools hereToolbox

claude-code - 💡(How to fix) Fix Docs: clarify that `claude --bg` / background dispatch sessions do not carry `agent_id` in hook payloads

Official PRs (…)
ON THIS PAGE

Recommended Tools

×6

Utilities matched from this issue’s tags and category — try them while you read without losing context.

GitHub issue graph ai analysis

Paste a GitHub issue URL. We fetch that issue, discover linked issues from bodies/comments/timeline, collect linked pull requests, and produce a structured English report.

The report is written in English Markdown for sharing and archival.

Helpful · Quick feedback

Loading…

hooks.md states agent_id is "present only when the hook fires inside a subagent call," but does not specify how background-dispatched sessions behave.

Empirically (and per agent-view.md: "each background session is its own Claude Code process"), a background dispatch session is a top-level process, so its hook payloads do NOT contain agent_id; only a subagent it itself spawns does.

Root Cause

hooks.md states agent_id is "present only when the hook fires inside a subagent call," but does not specify how background-dispatched sessions behave.

Empirically (and per agent-view.md: "each background session is its own Claude Code process"), a background dispatch session is a top-level process, so its hook payloads do NOT contain agent_id; only a subagent it itself spawns does.

Fix Action

Fix / Workaround

Discovered while piloting single-terminal background dispatch (claude agents / claude --bg) for real development work on Claude Code 2.1.157.

Summary

hooks.md states agent_id is "present only when the hook fires inside a subagent call," but does not specify how background-dispatched sessions behave.

Empirically (and per agent-view.md: "each background session is its own Claude Code process"), a background dispatch session is a top-level process, so its hook payloads do NOT contain agent_id; only a subagent it itself spawns does.

RAW_BUFFERClick to expand / collapse

Discovered while piloting single-terminal background dispatch (claude agents / claude --bg) for real development work on Claude Code 2.1.157.

Summary

hooks.md states agent_id is "present only when the hook fires inside a subagent call," but does not specify how background-dispatched sessions behave.

Empirically (and per agent-view.md: "each background session is its own Claude Code process"), a background dispatch session is a top-level process, so its hook payloads do NOT contain agent_id; only a subagent it itself spawns does.

Why it matters

Users building hook-based delegation/guard logic (e.g. "block production-code writes on the main thread, allow in subagents" keyed on agent_id) must know that a background dispatch session counts as a main thread, not a subagent. This determines the correct topology: the dispatch session must spawn its own subagent for code writes.

Request

Add an explicit note to hooks.md (and/or agent-view.md): background/dispatched sessions are top-level and do not include agent_id; only Task-tool subagents do.

Environment

  • Claude Code 2.1.157, docs as of 2026-05-31

Vote matrix · Quick signals

Works
Did the solution work? Tap to confirm.
Easy Fix
Was it a quick fix?
Time Saver
Did it save you time?
Blocking
Was it severely blocking?
Common Issue
Are others likely hitting this too?
Flaky / Intermittent
Is it intermittent?
Verified / Reproducible
Can you reproduce it reliably?
Loading…

Still need to ship something?

×6

Another batch ranked right after the header list — different links, same matching logic.

Back to top recommendations

TRENDING

claude-code - 💡(How to fix) Fix Docs: clarify that `claude --bg` / background dispatch sessions do not carry `agent_id` in hook payloads