claude-code - 💡(How to fix) Fix MCP channel push: non-blocking delivery mode for active sessions (multi-agent coordinator use case)

Note: This is a re-filing of #62136, which was auto-closed as a duplicate of #44380. I've posted an explanation on that issue, but the repo doesn't allow non-maintainer reopens on auto-closed duplicates. Explaining the distinction here so this doesn't get caught by the same classifier.

Why this is not a duplicate of #44380 / #61797 / #36431

Those three issues all report that channel messages don't arrive or don't wake an idle session — the session sits at ❯ and nothing happens. That is a delivery failure bug.

This issue is the opposite situation: delivery works correctly. The session is active, messages arrive and display as expected. The problem is the UX cost of each inbound message on a high-volume active session.

Summary

--dangerously-load-development-channels + notifications/claude/channel enables MCP servers to push messages into a running Claude Code session — exactly the primitive needed for multi-agent / inter-instance coordination. But the receive-side UX requires the user to press Enter twice to clear and resume input. At high message volumes this dominates the interaction and breaks the value proposition of the underlying capability.

Use case

We're building patterns where one Claude Code instance acts as a coordinator for many subordinate Claude Code instances (workers/lieutenants), and instances message each other over an MCP-backed peer broker. Concrete patterns in active use:

• Battalion — coordinator spawns ~5–10 workers, each reports status, sub-results, and completion back. The coordinator pane receives ~30–60 messages/minute on a hot run.
• Swarm — multiple Claude instances running in parallel on a single task, exchanging intermediate state.
• claude-peers (open-source MCP) — general inter-instance messaging, the substrate the above two run on.

At Battalion's traffic level, "press Enter twice per inbound message" becomes 60–120 Enter presses per minute, which destroys the workflow.

Current workaround and its failure mode

The community workaround is to skip the --dangerously-load-development-channels flag and instead use a Stop hook to surface queued messages, then force a Stop event by writing a single character (.) into the target session via iTerm AppleScript. This works except when the user is actively typing into the target pane: the . gets appended to their in-progress composer text and Enter is auto-pressed, submitting a fragment of their intended prompt.

A focus-aware variant of the poke (check if the session is the keyboard-focused pane, defer if so) reduces the failure rate but doesn't eliminate it, and it depends on screen-scraping the TUI for state — fragile against any future Claude Code UI changes.

Both paths involve real engineering effort to work around what looks like a UX gap in an existing capability.

Ask

Some shape of "inline channel push that doesn't require composer ack." Possibilities, in roughly increasing order of complexity:

1. Stabilize the channel flag with a delivery mode that doesn't block on composer ack — e.g., surface inbound channel messages as system messages or hook-style output that don't intercept the user's input line.
2. A new MCP capability along the lines of "inject system message" or "fire user-prompt-submit hook externally."
3. An externally-triggerable Stop event — e.g., the MCP server can call a method that fires the Stop hook without requiring a fake submission.

Option 1 is probably the closest to current architecture and would unblock the use cases above with the smallest delta.

Why this is worth shipping

Multi-agent coordination patterns are clearly something Anthropic wants to support (Managed Agents, the Agent SDK, the Stop/SubagentStop hook surface all point in this direction). The MCP channel primitive is the right shape — it just needs a delivery mode appropriate for high-volume machine-to-machine traffic.

Happy to share the workaround code as a concrete reference for the use case if useful.