Hooks: no way to intercept or suppress teammate idle_notification messages delivered to the lead (UserPromptSubmit does not fire on them)

Status Open
Reported on v2.1.263
Maintainer reply None cached
Activity 1 comment · opened Sep 8, 2026

Version: Claude Code 2.1.263, macOS, interactive CLI with CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1.

Problem. When a named teammate finishes, the lead receives an idle_notification as a harness-injected user turn (Another Claude session sent a message:\n<teammate-message ...>{"type":"idle_notification", ...}). In practice that message almost always follows a report the teammate already delivered via SendMessage 10 s – 3 min earlier, so it carries no new information — yet it triggers a full model turn in the lead (in one measured 87-minute orchestration session: 11 of 23 lead turns were idle notifications, ~22.7k output tokens and 11 user-facing messages with zero new content).

What I tried. A UserPromptSubmit hook that exits 2 when the prompt is an idle_notification whose report was already received (decision based on the lead's own transcript_path). Measured in a live session with a logging wrapper registered in both ~/.claude/settings.json and the project's .claude/settings.local.json: the hook fires on a human prompt (ping → 1 invocation) but never on teammate-message deliveries (4 deliveries incl. one pure idle_notification → 0 invocations). The hooks docs don't say whether UserPromptSubmit covers harness-injected messages; empirically it doesn't.

Also observed: several teammate messages (report + idle_notification, or multiple teammates) can be batched into ONE injected prompt, so any receiving-side filter must judge per block, not per prompt.

Ask (either would do):

  1. A hook event on the receiving side for teammate messages (or make UserPromptSubmit fire for them, with a field identifying the source), so a hook can block a redundant idle_notification with exit 2 / decision: block.
  2. Or a setting / spawn option to suppress idle_notification delivery when the teammate has already sent a message to the lead (or suppress it entirely).

Happy to share the hook script and the replay test against the real transcript if useful.

View original on GitHub ↗

This issue has 1 comment on GitHub. Read the full discussion on GitHub ↗