Repository navigation
feat(acp): let a claude session tree share one process across agents and models - #37615
Conversation
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: |
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the five fields really are per session on claude, and the change is reversible behind a switch that ships off. Notes
[DESIGN-REVIEWED] 57991e2 Description read[DESCRIPTION-READ] 58f71a50baa41396a7e277e921892ffd446004ff88fafbcfd428e3208184081b 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 |
First Principles Review (Opus 5.5) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks. Claude chat sharing stays off by default, so no default changes, and each of the five fields claude leaves out of the key was checked against what claude's spawn actually reads. Notes
What this change shipsInventory (5 items) — 4 justifiedIntent: when claude chat sharing is on, a lead or conductor and its workers in one session tree run on one claude-agent-acp process, even when they use different agents or models. This is an ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 57991e2 Description read[DESCRIPTION-READ] c6cb7d41a756ef4f38db595fc5472ee8533aa18b955dcec16e9a7475f08700a2 That sha256 names the PR description this verdict read. Recompute it with |
c3dc788 to
bfb4c92
Compare
bfb4c92 to
e5d68e3
Compare
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: |
e5d68e3 to
372107d
Compare
Code change approver recommendation: A person should decideWhy: the decider thinks the change is probably fine but estimates a 15% chance that this change introduces a defect, above the 12% limit for approving on its own. The PR's own commit lists claude in PER_SESSION_FIELDS_BY_BACKEND (agent, model, effort, spec_generation, launch_agent), limits the tool-surface pin to KAS (keys_tool_surface), passes each chat's own model through _harness_session_options and runs the derived-spec freshness gate per session in ClaudeHarness.prepare_session. I checked each removed field against the code. resolve_spawn reads none of them. launch_agent is always empty off kiro-cli. Effort is pushed per session through set_config_option. Tool Search and MCP-off are settled once per process only on KAS, so claude shouldn't pin. The chat's model is never empty (AcpClient defaults it to DEFAULT_MODEL), so the founder-model fallback isn't reached. A refused joiner releases its lease instead of killing the shared runtime. The work directory, environment, sandbox, account era, tree root and member scope stay in the key. Tests cover the key, the tree placement, the gate and the model seed. CI and all review lanes are green. Remaining issues are a stale ratchet comment and process items, none of which block. An automated recommendation, not a review: a maintainer still decides. It approves on its own only when the estimated chance of a defect is at most 12% and the change has at most 400 changed lines. Decider v3c (217fe607) · commit |
372107d to
16dc254
Compare
16dc254 to
11cece8
Compare
11cece8 to
c4993bc
Compare
c4993bc to
615de77
Compare
615de77 to
9bf5196
Compare
883ac4a to
4f1e3f9
Compare
4f1e3f9 to
7335f26
Compare
f95f0ff to
2c318c3
Compare
|
Review of head 2c318c3: no blocking defect in this PR's own commit. A maintainer should hold the merge until #37540 lands. This branch still carries the whole #37540 commit (ed9ddda, about 3.4k lines: claude dashboard chat sharing, the per-session stub token and the Settings switch). If this PR merges first, that code lands under this title and skips #37540's own review. Please merge #37540 first, then rebase so only 2c318c3 remains. The design is signed off under the standing maintainer sign-off for changes by team members. What the review checked on this head:
Done well: unkeying Optional:
|
…and models The runtime sharing key carries the session tree root since #37466, and a harness opts into tree sharing through PER_SESSION_FIELDS_BY_BACKEND. claude was not listed, so every field stayed keyed: an Ultra Mode tree's lead, conductor and workers run different agents and models and never shared. claude-agent-acp takes no --agent and no --model, and its spawn reads none of the five fields; each session writes its own settings seed and envelope. - CLAUDE_PER_SESSION_FIELDS leaves agent, model, reasoning_effort, spec_generation and launch_agent out of a claude key. - ClaudeHarness.prepare_session runs the spec freshness gate for the session's own agent, and seeds the chat's own model (carried in the harness options) over the runtime's, which is the founder's. - The tool-surface pin (agent_pins_tool_surface) applies only where the founder's spec decides the process's tool surface (keys_tool_surface, KAS): claude takes each session's MCP array in its own session/new.
2c318c3 to
57991e2
Compare
bolichen97
left a comment
There was a problem hiding this comment.
Approving head 57991e2. No blocking issues.
I checked what a session tree loses when the agent, model and effort leave the claude key, on two sessions with different agents on one process:
- Spawn reads none of the five fields.
ClaudeHarness.resolve_spawnandapply_spawn_envread only the argv,work_dirand sandbox mode, and those stay in the key, with env, account era, tree root and member scope. - Each session keeps its own agent spec.
_create_session_with_harness_stateresolves the session's own agent (_source_agent), andcreate_sessionbuilds the MCP array,denied_tools, stub token and the ceiling check (_refuse_over_ceiling_start) from that agent. The seed, the allowlist adoption (fail-closed insession_meta) and theoptions.envidentity are per session too. - Own model and effort. The seed now takes the chat's model from
_harness_session_options, and the start still pushesset_modeland effort per session. - Freshness gate per agent.
require_fresh_derived_specnow runs inprepare_sessionfor the joiner's agent, off the loop, before any seed is written. - Switch off equals main.
prepare_sessionruns only on the shared runtime, and goose and deepseek ignore the newmodeloption. - No new regex.
Tests run locally on this head: the 3 touched files plus the claude, goose and deepseek shared-runtime tests, the chat-runtime-sharing tests, test_acp_harness_contract.py and test_harness_parity.py. 847 passed. I also wrote one review-only test, not pushed. It puts a lead and a worker with different agents, models and permission modes on one ClaudeHarness. Each keeps its own agent, model, seed, session key and stub token, and ending the worker leaves the lead's seed and permission surface intact. It passed.
Optional, non-blocking:
- No test fails if the
keys_tool_surfacegate inresolve_chat_share(providers/chat_share.py:887) is reverted. A clauderesolve_chat_sharecase with a pinning reader that assertsagentandspec_generationare empty in the key would pin it. The tree test covers only theChatSharePlacementsite. - Workers in the lead's folder with a different spec still run with Crew's MCP array withheld (
_share_settings_seed_if_identical). This matches two per-chat processes in one folder, so it is not a regression, but it is this PR's main case. Saying it plainly in the body would help.
scan / internal-content-scan is still queued on this head, so auto merge waits for it.
AI-assisted, sent by Bolin Review bot
…Key (#37945) #37615 added test_claude_leaves_each_per_session_field_out_of_the_key with shared_scratch=None in the ChatRuntimeKey.build call. #37826, cut before #37615 landed, removed that keyword-only parameter, so on main the test's five cases raise TypeError and red every backend run. Drop the keyword from the test's base arguments. The key no longer carries the scratch directory at all, which is what #37826 intended. Co-authored-by: Bolin Chen <bolichen@amazon.com>
Problem / Motivation
Goal: with claude chat sharing on, a claude session tree (an Ultra Mode lead or conductor with its workers) runs on one claude-agent-acp process even when its sessions use different agents, models or efforts.
Since #37466 the sharing key carries the session tree root, and a harness takes key fields per session only through
PER_SESSION_FIELDS_BY_BACKEND. claude is not listed, so a claude key still carries the agent, model, effort and spec generation. A lead and its workers run different agents, so on the pod a conductor chat and the twokirocrew-workersessions it opened took two processes (the lead alone, the workers together).Stack: this branch carries #37521, #37586, #37593, #37601, #37540 and #37563 underneath one commit of its own; review only the top commit.
Why it matters
A claude session tree is where one user action fans out into several sessions. Without this, a tree pays one adapter process per distinct agent or model inside it, which is most of them.
Not a goal
What changed (motivation -> approach -> change)
claude-agent-acp takes no
--agentand no--model, andClaudeHarness.resolve_spawnreads none of the five fields KAS takes per session -> list claude for the same five, after making each of them truly per session -> one table row and two per-session steps.CLAUDE_PER_SESSION_FIELDS(acp/chat_runtime_sharing.py):agent,model,reasoning_effort,spec_generationandlaunch_agentare left out of a claude key. Checked per field:agent: each session's settings seed and_meta.claudeCodeenvelope are built from its own agent inClaudeHarness.prepare_session; the spawn takes none.model: the session's seed now names the chat's own model, carried in the harness options (_harness_session_options), not the runtime's, which is the founder's. The start then pushes it live withsession/set_model, as before.reasoning_effort: claude sets effort per session withsession/set_config_option(ACP_BACKENDS_EFFORT_VIA_CONFIG_OPTION); nothing reads it at spawn.spec_generation:prepare_sessionnow runs the derived-spec freshness gate (require_fresh_derived_spec) for the session's own agent, which the spawn ran only for the founder's. A joiner's fork governance was already checked byChatSharePlacement._admit_joiner.launch_agent: read only by kiro-cli's spawn.work_dir, the environment, the sandbox mode, the account era, the tree root and the member scope, which the claude process or its sessions' folders still depend on.agent_pins_tool_surfacereads a KAS spec to tell whether the founder's spec fixes the process's Tool Search. claude takes each session's MCP array in that session's ownsession/new, sokeys_tool_surface(backend)(KAS only) now gates both places that ask it; on claude every unreadable-spec answer would otherwise have pinned the session and undone the row.runtime-ownership.mdand theChatRuntimeKeydocstring say which fields claude leaves out and why.Known limit: two sessions with different specs in the same folder still cannot both own
settings.local.json; the second runs with Crew's MCP array withheld, exactly as two per-chat claude processes in one folder do (_share_settings_seed_if_identical).Backwards compatibility
Compatible: only claude keys change, and only while claude chat sharing is on. A claude session that shared before still shares; sessions of one tree that differed only in these fields now share too.
Removes nothing: the KAS row and every other key field are unchanged.
Tests
test_chat_runtime_tree_sharing.py: claude leaves each of the five fields out of the key and still splits on the tree root and the work directory; only KAS keys the spec for its tool surface; a claude lead and two workers with other agents and models land on one process even with a tool-surface reader that pins every spec; two claude trees never share; the table lists KAS and claude.test_claude_shared_runtime.py: a session seeds its own model over the runtime's; a session whose own spec is stale is refused before its seed is written.test_agent_admission_paths_ratchet.py:ClaudeHarness.prepare_sessionis listed as a freshness-gate site, with its fork-governance coverage named.Without the claude row, the key and tree tests fail; with the tool-surface gate ignoring the backend, the lead-and-workers test fails (6 processes for 3 sessions); without the model taken from the options, the seed test fails.
Proof: not provable -- other: feature PR, the mutations above are the check
Manual verification
On a pod running this branch with claude chat sharing on (claude-agent-acp 0.89.1, the version installed there): a
kirocrew-conductorchat calledsession_createtwice to open twokirocrew-workersessions in its project. The gateway loggedspawned runtime=... tenants=1for the lead andjoined ... tenants=2andtenants=3for the workers: one adapter for the tree, 66 processes and about 4.6 GB in its subtree. The same run on #37563 (without this PR) gave two adapters for the tree: the lead's (20 processes, about 1.5 GB) and the workers' (47 processes, about 3.3 GB). Most of the memory is each session's own MCP servers and Claude Code child, which this does not change; the saving is one adapter per extra agent in the tree. Worker 1 then ran a background command and reported its end in a turn it started itself.Screenshots / video
The lead chat that opened the workers, and the gateway's placement lines with each adapter's process tree after the run, are attached below.
Related Issues
Follows #37466. Part of the claude chat sharing stack: #37521, #37586, #37593, #37601, #37540, #37563, this PR.
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)Contribution License Agreement
Contributions are accepted under the project's Apache-2.0 license.