Repository navigation
feat(acp): let claude dashboard chats share one ACP process, switch off by default - #37540
Conversation
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the claude sharing switch is off by default, a chat with no placement keeps its per-chat client, and the only rename ( Notes
[DESIGN-REVIEWED] ed9ddda Description read[DESCRIPTION-READ] 7cd7ff52f726d84e7f954b04b0fca86c7c1020a23a8660b17c3e6864e19123a3 That sha256 names everything this verdict read: the PR description, plus the 1 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
UX Review (Opus 5.5) — ✅ PASSUX-level review of UX-Verdict: PASS Nothing blocks. The one new control, the "Chats using Claude Code" switch, appears off in shot-01 and on in shot-02, and the blind reader understood it ("this kind of chat now shares the background program") and would use it. Notes
[UX-REVIEWED] ed9ddda Description read[DESCRIPTION-READ] c548a1bde665d2ba85c8777a2c04f7da167b8a4362b247a489e0c850700a1d11 That sha256 names everything this verdict read: the PR description, plus the 7 evidence file(s) the workflow collected from it and handed this review. It covers that evidence because the media strip replaces every attachment URL with the same placeholder, so an edit swapping one attachment for another would leave the description's captured text identical while what this review judged changed. Recompute it with |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. The new claude switch is off by default, so no default changes. Each added seam has a real consumer in the claude shared-session path. Notes
What this change shipsInventory (10 items) — 9 justifiedIntent: an operator who keeps several claude dashboard chats open can opt in to running them in one adapter process. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] ed9ddda Description read[DESCRIPTION-READ] ca9181816971ecac3be052979b6c2b8eee61a50b1a5e60a04be43d445b51e799 That sha256 names the PR description this verdict read. Recompute it with |
Opus 5.5 Review — ✅ no blocking findingsReviewed Verdict parsed from the review's SHA-scoped output markers for commit False positive or not applicable? A repository writer can comment: |
GPT 6.1 Review — ✅ no blocking findingsGPT 6.1 completed its review of This comment is updated in place on each push. Review detailsNo findings. False positive or not applicable? A repository writer can comment: |
f261f5a to
d927f47
Compare
d927f47 to
fb55b5d
Compare
711c3ac to
983d66d
Compare
983d66d to
a39ab66
Compare
a39ab66 to
43a82d8
Compare
4afc9c9 to
576e70b
Compare
576e70b to
39c59f0
Compare
39c59f0 to
aab1285
Compare
7744c70 to
6ab7f62
Compare
10da134 to
49d4a34
Compare
…ff by default A dashboard chat on the claude harness joins the shared ACP runtime when the ACP runtime sharing preview and its own "Chats on the Claude harness" switch are both on. Every other claude session (channels, members, background work, sage) keeps its own AcpClient process exactly as before. - claude joins ACP_BACKENDS_CHAT_RUNTIME_SHARING and the per-harness switch table (default off). ACP_BACKENDS_SHARED_RUNTIME_ONLY_FOR_CHATS marks it as served by the runtime only for a chat that got a shared placement. - The provider asks for the placement before choosing its arm, and the runtime start uses that placement; a refused placement keeps the per-chat client. - Each session's identity (session key, stub token) rides its own _meta.claudeCode.options.env instead of the founder's process env. - The chat's permission mode, side read-only and memory choices travel to ClaudeHarness.prepare_session with each session start. - The account era of a claude process is a digest of Claude Code's own credentials file, so a sign-in to another account founds a new process. - A resumed session sends its own envelope on session/load, as session/new does, and a resume cancelled after it registered closes its session. - An organization-policy model substitution on session/new is adopted and the start re-sent once, as the per-chat client does. - The spec's toolsSettings shell and write allowlists, which claude never reads, are read at session setup, carried by the envelope's ask rules and stamped on the shared session's permission requests, as the per-chat client does. - A substitution retry whose re-seed finds Crew's settings file replaced is refused instead of re-sending the array authorized under it, and a load abandoned mid-request is closed once the request settles. - A start cancelled or refused inside the starting-mode pin closes its session, and a refusal on the shared connection reads as a failed pin; the envelope's Connection asks read this session's own array.
KiroCrewCaptain
left a comment
There was a problem hiding this comment.
Reviewed at ed9ddda against current main. The review read the whole 72-file diff. With the claude switch off, the kiro, KAS and codex paths change only by a backend-set or flag read. The related test set (572 tests) passed on this head, both serially and under xdist. The Settings row screenshots match the off and on states. No open PR duplicates this work: #37567, #37615 and #37646 stack on this commit and merge after it. Done well: the race tests build every interleaving from events with a named deadline and no sleep barrier, and the claude account era maps oauthAccount to a random token instead of a digest.
Security: several chats' sessions now share one adapter process, but each one is fenced. ClaudeHarness.session_meta raises when the spec allowlists were not adopted, so shell and write tools cannot run unasked. Permission requests are stamped only for the claude backend, and child calls carry the same native_child_call marking as the per-chat client. A chat in Auto permission mode is refused a shared placement, so the per-chat client's unasked-call audit record still covers it. The stub token already travels in the mcpServers array, so putting it in options.env adds no new exposure.
The design is signed off under the standing maintainer sign-off for changes by team members.
Optional:
runtime_session_load.py:541(load path picksAgentTurnQueue) has no behaviour test. Removing it leaves every test green, but a shared claude chat resumed after a restart would stop showing turns Claude Code starts on its own. The routing operand inacp_lifecycle.startand the "lost its shared placement" refusal atacp_runtime_start.py:893have the same gap. A load-path twin of the agent-started-turn test, plus one test that drivesstart()itself, would pin all three.client_transport._note_advertised_commandsnow caps the per-chat claude client's command list even with the switch off. Only the early cross-session buffer inclaude.pyneeds that cap. Either keep main's unbounded per-chat body, or declare the cap under Backwards compatibility.- When a claude chat already has a placement,
_start_kiro_runtime_implskips the remote-workspace re-check the kiro path makes (acp_runtime_start.py:877). Refusing with the same remote error whenremote is not Nonewould close that narrow window.
Problem / Motivation
Goal: dashboard chats on the claude harness can share one ACP process, behind a per-harness switch that is off by default, and with that switch on they share under the default settings.
Every claude chat runs its own claude-agent-acp process today (
ClaudeAcpClient). The shared runtime can drive claude per session (#37521), and the ACP runtime sharing preview has per-harness switches (#37472), but no claude chat is routed to the runtime. Claude Code can also start a turn between a chat's messages (arun_in_backgroundcommand finishes and it answers the task notification, or a background agent asks for a permission); the per-chat client sees that turn with its idle reader, and a shared session needs the same.This PR now also carries what was #37563 (turns Claude Code starts on its own), so the switch works with the default settings. #37563 is closed as merged into this one.
Stack: this branch sits on #37601 (which carries #37593) and is rebased to one commit once those merge; review only the top commit. The diff against main therefore also shows #37593's background-work reader and #37601's
session_handle_claude_children.py(Agent-tool children on the shared handle); those are reviewed on their own PRs.Why it matters
Each claude chat costs its own adapter process. An operator who keeps several claude chats open in one session tree can turn on "Chats using Claude Code" and run them in one adapter. Chats still reply at the same time and never see each other's messages, a reply Claude Code starts on its own still reaches its chat, and turning the switch off restores one process per new chat.
Not a goal
ClaudeAcpClientprocess exactly as before; claude is not added toACP_BACKENDS_ACP_RUNTIME.What changed (motivation -> approach -> change)
A claude chat should take the shared runtime only when a placement exists for it -> the provider asks for the placement before it chooses its arm -> a chat without one keeps its per-chat client.
ACP_BACKENDS_CHAT_RUNTIME_SHARINGandagent.chat_runtime_sharing_harnesses(defaultfalse), with its row in Settings: Chats using Claude Code, "On: new chats on this harness share one background program and use less memory. Off: each chat runs its own program."ACP_BACKENDS_SHARED_RUNTIME_ONLY_FOR_CHATS = {claude}marks a harness the runtime serves only for a chat that shares.acp_lifecycle.starttakes the runtime arm for such a harness only whenresolve_prejoined_chat_sharereturns a placement (dashboard origin, switch on, persistent memory, no member, no remote workspace). The placement is kept on the provider and used by_start_kiro_runtime_impl, which never founds a process of its own for claude.resolve_chat_sharerefuses a claude chat whose session would start inauto(its own ask, orKIROCREW_CC_PERMISSION_MODE), with the logged and counted reasonauto_permission_mode.create_sessionandload_sessionbuild on a host with per-session state is anAgentTurnQueue(acp/session_handle_agent_turns.py): each frame it takes is shown to the handle, and a frame that starts a turn while no turn or awaited request reads marks the turn pending and schedules the chat's callback.stream_unsolicitedreads that turn through_run_turn(..., agent_started=True), ending on theusage_updatethat closes Claude Code's own cycle, so tool rows, permission cards and the terminal are the user turn's own. A second cycle queued behind the first is handed off as its own turn (_rearm_agent_turn); a prompt that starts while such a turn is pending reads its frames as its own. An announced child's permission or question between the owner's turns goes to that watched queue instead of being refused.AcpSessionProvideranswerswatch_agent_turns,agent_turn_pendingandstream_unsolicited, andacp_turnsroutes them to it for a shared claude chat.KIROCREW_SESSION_KEYand stub token ride its own_meta.claudeCode.options.env(ClaudeHarness.session_meta(..., stub_token=)), so tools the chat'sclaudechild runs see this chat, not the founder.harness_optionstoprepare_sessionon every session start (create, load, a fresh conversation, an MCP re-send).session/load, assession/newdoes. A resume cancelled after it registered closes its session and releases the seed. An organization-policy model substitution onsession/newis adopted byClaudeHarness.adopt_substituted_model, which re-seeds the settings, and the start is sent once more, as the per-chat client does; a re-seed that finds Crew's settings file replaced refuses the retry instead. A load abandoned mid-request is closed once the request settles.toolsSettingsshell and write allowlists, which claude never reads, are read at session setup (ClaudeSharedSession.prepare), carried by the envelope's ask rules, and stamped on every permission request of the shared session, a native sub-agent's included, as the per-chat client does.AcpSessionProvider.settings_withheld_causereads the session's own harness state, so the first-turn notice that Crew's tools are withheld still shows on a shared chat.claude_spawn_identitydigests the signed-in account's ids (oauthAccountin Claude Code's.claude.json, underCLAUDE_CONFIG_DIRwhen set), so a sign-in to another account founds a new process; it does not read.credentials.json, which Claude Code rewrites on token refreshes.codex_erais renamedharness_erafor both harnesses.Backwards compatibility
Compatible: the claude switch defaults off, and with it off every claude chat takes the same per-chat path as before. A stored
truefor a harness outside the table still reads as off. Only claude sessions on the shared runtime get the new queue.Removes nothing: every change adds a path behind the new switch; no key, row or function is removed or renamed apart from the internal
codex_erakeyword, whose only callers are updated here.Tests
test/test_chat_runtime_sharing.py: claude is off until its switch is stored true; a claude chat shares only from the dashboard with its switch on (channel origin, member and switched-off all refuse); the loader fills claude's default.test/test_chat_runtime_sharing_cleanup.py: a claude chat shares whateveragent_started_turnssays; a chat inauto(its own ask or the operator's lever) keeps its own process and aplanchat logs no warning; the claude era follows the signed-in account.test/test_claude_shared_agent_turns.py(new): a turn the agent starts between prompts is read whole with nothing written; a prompt that starts first reads the pending frames as its own; a second queued cycle is its own turn; a frame during a turn starts nothing; a background child's permission between turns opens its owner's turn, and an unwatched owner still refuses it; a host without per-session state keeps a plain queue.test/test_claude_shared_runtime.py: allowlists reach the envelope and the requests of the session and of its native sub-agent; the shared provider reads its own session's withheld-tools cause; substitution retry, resume envelope, cancelled and abandoned loads, mode-pin refusals, per-session key and stub token, the placement path and the chat's options.test/metrics/test_chat_runtime_share.py: the refusal reasons are the rule's branches plusnative_subagentsandauto_permission_mode.Proof: not provable -- other: new feature behind an off-by-default switch, not a fix
Manual verification
Pod runs with real claude-agent-acp and Claude Code.
Sharing (three dashboard chats in one project; chat A runs a 60-second shell command, chats B and C ask at 5 seconds):
harness_switched_offMemory falls only a little because Claude Code still runs one
claudeprogram per session; sharing saves the adapters. Each shared chat printed its ownKIROCREW_SESSION_KEY. After a gateway restart all three chats came back on one process and each repeated its own previous answer. These runs predate #37466's session-tree key; on today's main unrelated chats take a process each, and a tree run is recorded on #37615.Turns Claude Code starts on its own (default settings,
agent.agent_started_turnson): inside one tree, akirocrew-conductorchat opened two worker sessions that joined its process; worker 1 ransleep 8 && echo <token>in the background, answeredSTARTED, and then posted the command's output in a turn it started itself, with no message sent.Screenshots / video
Settings with the default settings, on this head: the Claude row off (its default) and on. The worker screenshot shows a reply Claude Code started on its own on the shared process.
Other suggestions
Give the shared session handle the unasked-call SEL audit for
automode, then drop theauto_permission_moderefusal.Related Issues
Part of #5033
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...) -- not yet: the branch carries feat(acp): read claude background work per session on the shared runtime #37593 and feat(acp): route claude Agent-tool children per session on the shared runtime #37601 below its own commit until they merge, then it is rebased to one commitContribution License Agreement
Contributed under the project's Apache-2.0 license.