[DOCS] Channels: print mode (-p) never delivers channel events, but the page reads as if it does

Documentation Type

Unclear/confusing documentation

Documentation Location

https://code.claude.com/docs/en/channels

Section/Topic

Running channels in non-interactive mode (-p)

Current Documentation

When you run channels in non-interactive mode with -p, tools that need terminal input, such as multiple-choice questions and plan mode approval, are disabled so the session never stalls waiting for input.

What's Wrong or Missing?

That sentence reads as if a -p session can listen on a channel. On Claude Code 2.1.287, 2.1.288 and 2.1.289 (Windows 11, subscription auth) it cannot: in print mode the channel gate never runs, so no channel event reaches the context.

Setup: a stdio MCP server that declares capabilities.experimental['claude/channel'] and sends notifications/claude/channel, loaded with --dangerously-load-development-channels server:<name>.

• Interactive session: the debug log prints <name>: Channel notifications registered, and a pushed event reaches the transcript as a channel-origin user turn within a second. Works as documented.
• Print mode (claude -p ... --mcp-config <file> --strict-mcp-config --dangerously-load-development-channels server:<name> --debug): the server completes the MCP handshake and sends the same notification within 20 ms of the source event, and nothing reaches the context. Seven probes across the three versions, including a long-lived --input-format stream-json session kept open with stdin idle for 45 s after the event. The debug log shows

``
[session-notices] advertise=false mode=bypassPermissions flag=true(payload) pollChannel=false remote=false remoteEnv=false nonInteractive=true
``

and never prints Channel notifications registered or Channel notifications skipped: <reason>, though the binary carries both strings and the interactive run printed the first.

Suggested Improvement

One of:

1. Say on the Channels page that channel events need an interactive session, and reword the -p sentence so it does not read as a supported listener mode; or
2. Run the channel gate in print mode, so a long-lived -p session (for example under --input-format stream-json) receives events.

Either way, a Channel notifications skipped: non-interactive debug line would make the behavior discoverable.

Impact

Medium - Makes feature difficult to understand

Additional Context

Repro: any channel server (ours is a small zero-dependency stdio server; the docs' fakechat example should serve, though we did not run it). Run it once interactively with the development flag and once under -p with the same flag, push one notification in each, and compare the transcripts and --debug logs. Related but distinct: #78028 and #90160, where the flag is lost on resume or re-hosting; this is print mode from a clean start. #90048 reports the same silence from the VS Code extension, which runs the CLI with --input-format stream-json; the nonInteractive=true line above may be the mechanism it was guessing at.