Docs: clarify that `claude --bg` / background dispatch sessions do not carry `agent_id` in hook payloads

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