Skip to content

feat(acp): let claude dashboard chats share one ACP process, switch off by default - #37540

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/claude-chat-sharing
Nov 16, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/claude-chat-sharing

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

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 (a run_in_background command 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

  • Only dashboard chats share. Channel chats, members, background work and sage keep their own ClaudeAcpClient process exactly as before; claude is not added to ACP_BACKENDS_ACP_RUNTIME.
  • Sharing follows feat(acp): share one KAS process per session tree (Ultra Mode and Bot) under runtime sharing preview #37466's session-tree rule: sessions share only inside one tree (a chat and the sessions it opens), never across two unrelated chats.
  • A claude chat in Auto permission mode keeps its own process (see What changed).
  • No change for kiro-cli, KAS or codex chats, and no change to any default: the claude switch is off.

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.

  • Switch and sets. claude joins ACP_BACKENDS_CHAT_RUNTIME_SHARING and agent.chat_runtime_sharing_harnesses (default false), 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.
  • Arm choice. acp_lifecycle.start takes the runtime arm for such a harness only when resolve_prejoined_chat_share returns 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.
  • Auto permission mode. Only the per-chat client writes the SEL record for a call Claude's classifier approves without asking, so resolve_chat_share refuses a claude chat whose session would start in auto (its own ask, or KIROCREW_CC_PERMISSION_MODE), with the logged and counted reason auto_permission_mode.
  • Turns Claude Code starts on its own. The session queue create_session and load_session build on a host with per-session state is an AgentTurnQueue (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_unsolicited reads that turn through _run_turn(..., agent_started=True), ending on the usage_update that 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. AcpSessionProvider answers watch_agent_turns, agent_turn_pending and stream_unsolicited, and acp_turns routes them to it for a shared claude chat.
  • Per-session identity. Each session's KIROCREW_SESSION_KEY and stub token ride its own _meta.claudeCode.options.env (ClaudeHarness.session_meta(..., stub_token=)), so tools the chat's claude child runs see this chat, not the founder.
  • Per-session choices. The chat's permission mode, Side Chat read-only flag and memory choice travel as harness_options to prepare_session on every session start (create, load, a fresh conversation, an MCP re-send).
  • Resume and retry. A resumed session sends its own envelope on session/load, as session/new does. A resume cancelled after it registered closes its session and releases the seed. An organization-policy model substitution on session/new is adopted by ClaudeHarness.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.
  • Spec allowlists. The spec's toolsSettings shell 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.
  • Withheld tools. AcpSessionProvider.settings_withheld_cause reads the session's own harness state, so the first-turn notice that Crew's tools are withheld still shows on a shared chat.
  • Account era. claude_spawn_identity digests the signed-in account's ids (oauthAccount in Claude Code's .claude.json, under CLAUDE_CONFIG_DIR when 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_era is renamed harness_era for 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 true for 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_era keyword, 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 whatever agent_started_turns says; a chat in auto (its own ask or the operator's lever) keeps its own process and a plan chat 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 plus native_subagents and auto_permission_mode.
  • Each fix's test fails with the fix removed. Local: these files plus the provider, binding, facade-mirror and runtime tests, serially; the settings-row vitest; isort, flake8, black (pinned).

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):

Claude switch Placement log New adapter processes Extra memory during the turn B / C answered A answered
On A spawned, B and C joined 1 about 4.6 GB 2.3 / 2.7 s after asking 65.9 s
Off all three harness_switched_off 3 about 4.8 GB 3.6 / 3.1 s after asking 70.2 s

Memory falls only a little because Claude Code still runs one claude program per session; sharing saves the adapters. Each shared chat printed its own KIROCREW_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_turns on): inside one tree, a kirocrew-conductor chat opened two worker sessions that joined its process; worker 1 ran sleep 8 && echo <token> in the background, answered STARTED, 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.

Settings, default settings: Chats using Claude Code off

Settings, default settings: Chats using Claude Code on

Gateway log: a conductor and two workers on one claude process

Worker 1: background command started, then its output in a turn Claude started itself

Other suggestions

Give the shared session handle the unasked-call SEL audit for auto mode, then drop the auto_permission_mode refusal.

Related Issues

Part of #5033

Checklist

Contribution License Agreement

Contributed under the project's Apache-2.0 license.

@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 15, 2026
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

Design-level review of ed9dddaae3d0cfaa5f6683500fedfdcc2a06bcb0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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 (codex_era → harness_era) has no callers left in the tree.

Notes

  • With Auto permission mode, a claude chat keeps its own process, because only the per-chat client writes the SEL audit record when Claude's classifier approves a call without asking. That is a real gap in the shared path, not just a refusal reason. Track it with an issue so the refusal doesn't become permanent.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ✅ PASS

UX-level review of ed9dddaae3d0cfaa5f6683500fedfdcc2a06bcb0 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • chat_runtime_sharing_harness_claude_desc now makes three identical "On: … Off: …" lines in a row. Without that repeated text, the blind reader still couldn't tell the rows belong to the parent switch ("nothing says so outright"). Put the On/Off text once under "ACP runtime sharing" and leave each harness row as just its label.

[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 .github/scripts/pr-description-capture.sh over the same inputs; if it differs, the description or that evidence changed after this verdict was formed and any finding drawn from either is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of ed9dddaae3d0cfaa5f6683500fedfdcc2a06bcb0 — why this exists and whether the shipped surface is the smallest honest version. Updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

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

  • Item 9 — undeclared: the model re-send on resume (reasserts_reported_model, session_handle_model_selection.py:888) never appears in the description's "What changed". It copies the per-chat client's _reassert_adapter_resolved_model (one harness sets it, one reader reads it), and its harm is a resumed shared chat running Claude Code's built-in default model.

What this change ships

Inventory (10 items) — 9 justified

Intent: an operator who keeps several claude dashboard chats open can opt in to running them in one adapter process. ADDITION.

  1. New Settings row "Chats using Claude Code" (chat_runtime_sharing_harnesses.claude, default off) — justified
  2. With the switch on, a dashboard claude chat joins a shared ACP process inside its session tree — justified
  3. A claude chat in Auto permission mode keeps its own process, with new refusal reason auto_permission_mode — justified
  4. A reply Claude Code starts between messages reaches a shared chat (AgentTurnQueue, stream_unsolicited) — justified
  5. Each shared session's tools see their own chat's session key and stub token — justified
  6. Permission mode, Side Chat read-only flag and memory choice reach each shared session (prepare_session(options=)) — justified
  7. A resumed session sends its own envelope; an organization-policy model substitution retries once — justified
  8. Spec shell and write allowlists are stamped on every permission request of a shared session — justified
  9. A resumed inheriting session is sent back the model its adapter reports — undeclared
  10. Signing in to another Claude account starts a new process; codex_era is renamed harness_era — justified

[FIRST-PRINCIPLES-REVIEWED] ed9ddda

Description read

[DESCRIPTION-READ] ca9181816971ecac3be052979b6c2b8eee61a50b1a5e60a04be43d445b51e799

That sha256 names the PR description this verdict read. Recompute it with .github/scripts/pr-description-capture.sh; if it differs, the description changed after this verdict was formed and any finding drawn from the description is unproven.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

Reviewed ed9dddaae3d0cfaa5f6683500fedfdcc2a06bcb0 — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] ed9ddda

Verdict parsed from the review's SHA-scoped output markers for commit ed9dddaae3d0cfaa5f6683500fedfdcc2a06bcb0.

False positive or not applicable? A repository writer can comment:
/ai-review override fable ed9dddaae3d0cfaa5f6683500fedfdcc2a06bcb0 false-positive: <reason, 20 to 500 characters>

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

GPT 6.1 completed its review of ed9dddaae3d0cfaa5f6683500fedfdcc2a06bcb0 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] ed9ddda

False positive or not applicable? A repository writer can comment:
/ai-review override gpt ed9dddaae3d0cfaa5f6683500fedfdcc2a06bcb0 false-positive: <reason, 20 to 500 characters>

@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch 3 times, most recently from f261f5a to d927f47 Compare November 15, 2026 07:51
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch from d927f47 to fb55b5d Compare November 15, 2026 08:10
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch 3 times, most recently from 711c3ac to 983d66d Compare November 15, 2026 09:02
@chenmingwei23
chenmingwei23 marked this pull request as ready for review November 15, 2026 09:05
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch from 983d66d to a39ab66 Compare November 15, 2026 09:26
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch from a39ab66 to 43a82d8 Compare November 15, 2026 09:44
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch 2 times, most recently from 4afc9c9 to 576e70b Compare November 15, 2026 16:58
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: checking Automated validation is still running labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch from 576e70b to 39c59f0 Compare November 15, 2026 17:14
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch from 39c59f0 to aab1285 Compare November 15, 2026 18:00
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch 4 times, most recently from 7744c70 to 6ab7f62 Compare November 15, 2026 19:05
@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-chat-sharing branch 2 times, most recently from 10da134 to 49d4a34 Compare November 15, 2026 19:50
@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
…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 KiroCrewCaptain left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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 picks AgentTurnQueue) 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 in acp_lifecycle.start and the "lost its shared placement" refusal at acp_runtime_start.py:893 have the same gap. A load-path twin of the agent-started-turn test, plus one test that drives start() itself, would pin all three.
  • client_transport._note_advertised_commands now caps the per-chat claude client's command list even with the switch off. Only the early cross-session buffer in claude.py needs 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_impl skips the remote-workspace re-check the kiro path makes (acp_runtime_start.py:877). Refusing with the same remote error when remote is not None would close that narrow window.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants