feat(session-bridge): native channels adapter with loopback fallback - #6063
kyle-sexton wants to merge 4 commits into
Conversation
Add ChannelRelay, a second Transport adapter on Claude Code's native channels (research preview), served by a stdio MCP channel server (session_bridge.py relay). The relay holds the data dir's lease in place of watch.sh and rings the session with a channel event that carries no page text; the session reads the events through the server's events tool. select_transport picks channels only when the session opted the relay in with --channels or --dangerously-load-development-channels, auth is first-party, and no readable organization policy blocks channels; otherwise it keeps the loopback watcher and states why. Planning carries the regenerated copy but registers no channel server, so its behavior is unchanged. Closes #5855 Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
…dge-channels-adapter # Conflicts: # plugins/planning/.claude-plugin/plugin.json # plugins/planning/CHANGELOG.md
A lease conflict rang the holder name the page server sent, so a token holder
could put arbitrary text into the session's channel message. Rings now carry
fixed text only; a holder matching [A-Za-z0-9._-]{1,64} goes to stderr.
The relay validates the wait answer's shape; a bad answer or any unexpected
error releases the lease and rings a fixed stopped notice, so watch can start
again. The channel server releases its live leases when its input closes.
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
Claude finished @kyle-sexton's task in 7m 14s —— View job Code review (
|
|
Claude finished @kyle-sexton's task in 3m 40s —— View job Security review (
|
|
claude-security-review has reviewed this pull request through f3b63de; a later push is reviewed from there. |
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: f3b63de464
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
| the base file), or (None, None). MDM policies (a macOS plist, the Windows registry) are not | ||
| read, so a policy that arrives only by MDM reads as none.""" |
There was a problem hiding this comment.
With Console API-key authentication, an organization can deliver managed settings only through the macOS plist or Windows registry; this function reports that as no policy, and select_transport only treats a missing policy as blocking for Team/Enterprise subscription strings. It can therefore select channels even when an MDM policy omits or disables channelsEnabled, causing Claude Code to silently drop notifications while the loopback fallback is inactive. The official channel rules state that Console organizations deploying managed settings are blocked until channelsEnabled is true, and MDM is a supported managed source, so an unreadable MDM state must not be treated as permission to use channels: channels controls, managed-source precedence.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Classification: VALID, defer. Basis: verified against the cited docs by the finding; not reproduced locally. Both failure modes of this finding degrade to a silent drop of channel notifications, not an access-control bypass, and the fix changes the policy-fail-closed logic that the independent security review approved at 185c400. That change needs its own review pass, so it is not made in this merge. Not filed as a tracker item; reported to the owner as an open follow-up.
| merged = dict(read_json(base / "managed-settings.json") or {}) | ||
| for drop_in in sorted((base / "managed-settings.d").glob("*.json")): | ||
| merged.update(read_json(drop_in) or {}) |
There was a problem hiding this comment.
When allowedChannelPlugins is split across managed-settings.json and one or more drop-ins, dict.update replaces the earlier list with the last file's list. Claude Code's documented merge semantics union list-valued settings across these files, so if an earlier file allows this plugin and a later file adds another plugin, Claude Code registers both but this selector incorrectly chooses loopback. Merge list and nested values using the managed-settings rules rather than applying shallow replacement; see managed drop-in merge semantics.
Useful? React with 👍 / 👎.
There was a problem hiding this comment.
Classification: VALID, defer. Basis: verified against the cited docs by the finding; not reproduced locally. Replacement instead of union errs toward the loopback transport (the conservative fallback), so the observable effect is channels not being used when they could be, not a bypass. Correcting the merge touches the policy reader the independent security review approved at 185c400 and needs its own review pass, so it is not made in this merge. Not filed as a tracker item; reported to the owner as an open follow-up.
|
claude-review has reviewed this pull request through f3b63de; a later push is reviewed from there. |
1 participant
Closes #5855
Summary
session-bridge gets a second adapter on Claude Code's native channels (research preview), plus a
selection function that picks it only when channels can deliver and otherwise keeps the loopback
watcher and says why. Wave B4 follow-up of #5835, after #5907 extracted the port.
No app opts in yet. Planning carries the regenerated copy but registers no channel server and
calls neither the relay nor the selection, so the interview page, the watcher and
round.shareunchanged. The Claude-interactive tier stays closed: no rendered-views doc or page changes here.
Fix
ChannelRelay(Transport): the channels adapter. Inside the session's channel server itlong-polls the page server's
/api/waitwith the token from the 0600 env file and holds thelease in place of
watch.sh. Its log is the batch the page server delivered that the sessionhas not read. On new events it rings the session once; it does not ring again for the same
events. A 409, a changed token, the page server stopping, or 12 unreachable polls end it with a
final
stopped="1"ring naming the reason.ChannelServer(session_bridge.py relay): a stdlib stdio MCP server declaringexperimental["claude/channel"]and three tools takingdata_dir:watch,events,unwatch.data_dir,seqandcount, never page text, so nothing fromthe page reaches the session as a channel message (rendered-views rule 9, bullet 2).
eventsreturns the batch inwatch.sh's line shape with the data note, andnextis theapp's apply command.
select_transport(entries)(session_bridge.py select <entry>...): returns{"transport", "reason"}. It picks channels only when every check passes; an unreadable inputcounts as failed. The checks, in order:
--channelsor--dangerously-load-development-channels. It reads/proc, elseps; on Windows the flagscannot be read, so the result is loopback.
claude auth status --jsonreports logged in andfirstParty.has
channelsEnabled: true. With no source, ateamorenterpriseplan keeps loopback.--channelsmust be onallowedChannelPlugins.degradelines for
claude, Anthropic auth, the session opt-in and org enablement. Auth and orgenablement are not prerequisites-checker kinds, so
select_transportreports them. A plugin thatregisters the relay adds the
clauderow to itsprerequisites.json.planning0.65.2 with a CHANGELOG entry for the regenerated copy.Verification
python3 -m unittest test_session_bridge(lib/session-bridge): 54 tests OK (36 before). Thenew tests cover:
non-first-party auth, a team org without
channelsEnabled, a policy without it, and--channelsoff the allowlistinitializedeclares the channel, a ringcarries no page text,
eventsreturns the batch and the apply command, there is no re-ringfor read events,
unwatchreleases the lease, a released lease ringsstopped, andwatchwithout a server fails
selectfrom a shell not launched with a channels flag returnsloopback ("not started with --channels ... naming ..."). From a parent whose argv carries
--dangerously-load-development-channels plugin:x@y, it returns channels using the realclaude auth status.python3 -m unittest test_server test_round test_exporters test_schema: 559 OK (1 skipped)watch.test.sh27/0surface.test.sh479/0 (1 skip), with the browser suitesinterview-defenses172/0,reattach-slice23/0 andstandards-binding9/0interview-surface-decision-mirror,plan-panel(22/0),check-open-questions,check-plan-outcome,eval-scaffoldandgoal-condition-lengthall okwatch.test.sh27/0 andplan-panel22/0. The four planning Python
suites still give 559 OK (1 skipped).
sync-shared-copies.sh --check(260 copies match) and--check-bump origin/main(planningbumped).
check-declared-prerequisites.mjsis clean: theclaudecall carriesprereq-ok.check-cross-plugin-source-drift.sh --checkis clean.--check-bump,--check-orderand--check-preservedmodes.registering the relay and a session started with the development flag, which belongs to the
first adopter (C6).
Related
Claude-interactive tier opens only when rendered-views rule 9 is met, which this PR does not
change.
🤖 Generated with Claude Code