Channels: allow a persistent/settings-level channel opt-in so already-running sessions can receive pushed events

Preflight Checklist

• Searched existing issues for "channels settings opt-in" / "channels always on" — none found.
• Reproduced on Claude Code 2.1.263 (macOS 15.5, arm64), claude.ai login.

Problem Statement

Channels (research preview) are the only way for a local tool to push an event into a running Claude Code session, and today they can be enabled only per session, at launch, via --channels plugin:… or --dangerously-load-development-channels server:<name>. The docs are explicit: "In all cases, no channel runs until a user opts it in for the session with --channels." There is no settings key, no environment variable, and no in-session command that turns a registered channel server on — so a session started with plain claude can never receive a channel event, and there is no way to enable it after the fact.

For local coordination tools this is an adoption blocker. Our case: Bridge lets a live Claude Code session and a live Codex session text/call each other (a two-way channel MCP server plus a reply tool). It works end-to-end — but only if the user launches Claude through a wrapper that adds the flag. Users who already have sessions open cannot be reached and must quit and relaunch (claude --resume restores context, but the interruption is exactly the friction people reject). Aliasing claude to the wrapper is the best workaround available, and it is a poor one to ask of every user.

What we verified while building this (2026-09-06/07):

• The channel server registered at user scope in ~/.claude.json is loaded by every plain claude session and its tools work; only pushed notifications/claude/channel events are dropped without the flag. So the outbound half already works everywhere; it is purely the opt-in gate that blocks inbound.
• --channels and --dangerously-load-development-channels are intentionally absent from claude --help during the preview (both literals are present in the 2.1.263 binary and the flags work), which also means tools cannot feature-detect channel support — we had to gate on the version string instead.
• The initialize params Claude sends the server carry no channel-related client capability (capabilities: {roots: {listChanged: true}, elicitation: {}}), and the server gets no registration signal either way ("Claude Code drops the events silently and returns no error to your server") — so a server cannot even tell the user why nothing arrives.
• ~/.claude/settings.json accepts no channel-related key we could find; channelsEnabled / allowedChannelPlugins are admin (managed-settings) controls that gate availability, not a user opt-in.

Proposed Solution

Any of these would remove the relaunch requirement (in rough preference order):

1. A user-settings opt-in, e.g. "channels": ["server:bridge"] (or "enabledChannels") in ~/.claude/settings.json / project settings, honoured at every session start — the same allowlist semantics as --channels, just persistent. The existing channelsEnabled / allowedChannelPlugins admin controls would continue to gate it.
2. An in-session command (/channels enable server:bridge) so a running session can opt in without restarting.
3. At minimum, expose channel support to tools: list the flags in --help (or a claude --channels-supported probe) and echo an experimental capability or a notifications/claude/channel/registered event back to the server so it can report "not registered for this session" instead of silently dropping.

Alternative Solutions

• Ship a PATH shim so claude transparently becomes the wrapper (works, but every coordination tool would install its own shim of the vendor CLI).
• Ask users to claude --resume <id> through the wrapper to convert an open session (works; the interruption is the objection).
• A SessionStart hook to give the channel server identity for outbound use (works for outbound only; inbound still needs the flag).

Priority

High for local agent-coordination tooling — it decides whether such tools are usable with sessions people already have open.

Feature Category

MCP / Channels / integrations

Additional Context

Wire-level details and the test harness we used are in the Bridge repo's docs/experiments/ (Experiment E — Claude Channel delivery and reply, verified live on 2.1.263). Happy to provide traces or try a preview build.