Skip to content

feat(acp): let a claude session tree share one process across agents and models - #37615

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/claude-shared-per-session-fields
Nov 16, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/claude-shared-per-session-fields

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

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 two kirocrew-worker sessions 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 --agent and no --model, and ClaudeHarness.resolve_spawn reads 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_generation and launch_agent are left out of a claude key. Checked per field:
    • agent: each session's settings seed and _meta.claudeCode envelope are built from its own agent in ClaudeHarness.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 with session/set_model, as before.
    • reasoning_effort: claude sets effort per session with session/set_config_option (ACP_BACKENDS_EFFORT_VIA_CONFIG_OPTION); nothing reads it at spawn.
    • spec_generation: prepare_session now 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 by ChatSharePlacement._admit_joiner.
    • launch_agent: read only by kiro-cli's spawn.
    • Kept in the key: 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.
  • Tool-surface pin only where the founder decides it. agent_pins_tool_surface reads 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 own session/new, so keys_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.md and the ChatRuntimeKey docstring 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_session is 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-conductor chat called session_create twice to open two kirocrew-worker sessions in its project. The gateway logged spawned runtime=... tenants=1 for the lead and joined ... tenants=2 and tenants=3 for 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

  • At most two commits (one is the norm), with a Conventional Commits title (feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)
  • Existing tests pass and new tests added for new functionality
  • Self-review completed; code follows project style guidelines
  • Documentation updated (if applicable)
  • No secrets, credentials, or internal references in the diff

Contribution License Agreement

Contributions are accepted under the project's Apache-2.0 license.

The conductor chat that opened two worker sessions

Gateway log and adapter process trees after the tree run

c-default-claude-off

c-default-claude-on

@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 57991e25477f26b574e47b9b885ca2911010d5e3 and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 57991e2

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

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 57991e25477f26b574e47b9b885ca2911010d5e3 touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

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

  • A lead and its workers usually share one folder and use different agents, so the stated limit applies to this PR's main case: the second spec's session runs with Crew's MCP array withheld (_share_settings_seed_if_identical). Separate processes behave the same way, so this is not a regression. Still, the description should say plainly that workers in the lead's folder lose the Crew MCP tools.

[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 .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 57991e25477f26b574e47b9b885ca2911010d5e3 — 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. 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

  • Item 3 — one consumer, generalized: FOUNDER_TOOL_SURFACE_BACKENDS = frozenset({ACP_BACKEND_KAS}) is a set with one entry and is read only by keys_tool_surface. It is also exported in __all__. Because KAS's per-session row already contains TOOL_SURFACE_FIELDS, the and bool(per_session_fields(backend) & TOOL_SURFACE_FIELDS) half never changes the answer. Grep: FOUNDER_TOOL_SURFACE_BACKENDS has one consumer in src/, and keys_tool_surface( has two (chat_share.py:594, :887). Subtraction: delete the constant and its __all__ entry, and shrink keys_tool_surface to backend == ACP_BACKEND_KAS.

What this change ships

Inventory (5 items) — 4 justified

Intent: 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.

  1. A claude session tree with sessions on different agents, models, efforts or spec generations now shares one process (CLAUDE_PER_SESSION_FIELDS row) — justified
  2. Each claude session's settings seed now names that chat's own model, not the founder's (_harness_session_options["model"]) — justified
  3. On claude, the tool-surface pin no longer forces a session onto its own process (keys_tool_surface) — one consumer, generalized
  4. A joining claude session whose own derived spec is stale is now refused in prepare_session, matching the per-session gate at kas.py:1277 — justified
  5. Spec and docstring now say which fields claude leaves out of the key — justified

[FIRST-PRINCIPLES-REVIEWED] 57991e2

Description read

[DESCRIPTION-READ] c6cb7d41a756ef4f38db595fc5472ee8533aa18b955dcec16e9a7475f08700a2

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.

@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-per-session-fields branch from c3dc788 to bfb4c92 Compare November 15, 2026 13:57
@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-shared-per-session-fields branch from bfb4c92 to e5d68e3 Compare November 15, 2026 14:04
@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
@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 57991e2

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

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

@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-per-session-fields branch from e5d68e3 to 372107d Compare November 15, 2026 14:18
@KiroCrewCaptain

KiroCrewCaptain commented Nov 15, 2026 •

Copy link
Copy Markdown
Collaborator

Code change approver recommendation: A person should decide

Why: 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 2c318c3333 · 3719 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-per-session-fields branch from 372107d to 16dc254 Compare November 15, 2026 15:01
@github-actions github-actions Bot added merge conflict Branch has merge conflicts with its base — author must resolve before merge 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-shared-per-session-fields branch from 16dc254 to 11cece8 Compare November 15, 2026 16:44
@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-shared-per-session-fields branch from 11cece8 to c4993bc Compare November 15, 2026 16:58
@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-shared-per-session-fields branch from c4993bc to 615de77 Compare November 15, 2026 17:16
@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-shared-per-session-fields branch from 615de77 to 9bf5196 Compare November 15, 2026 18:04
@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-shared-per-session-fields branch 2 times, most recently from 883ac4a to 4f1e3f9 Compare November 15, 2026 23:00
@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-shared-per-session-fields branch from 4f1e3f9 to 7335f26 Compare November 15, 2026 23:57
@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-shared-per-session-fields branch 3 times, most recently from f95f0ff to 2c318c3 Compare November 16, 2026 01:54
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 16, 2026
@KiroCrewCaptain

Copy link
Copy Markdown
Collaborator

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:

  • The shared ClaudeHarness.resolve_spawn and apply_spawn_env read none of the five fields this commit drops from the key.
  • The joiner's own agent, model and effort reach every per-session path.
  • keys_tool_surface leaves KAS unchanged and is a positive set membership check.
  • The new require_fresh_derived_spec call in prepare_session runs off the event loop and fails closed before any seed is written.
  • The PR's tests pass on an extracted copy. Three of the mutations the body names turn them red, including the "6 processes for 3 sessions" failure.

Done well: unkeying spec_generation comes with a per-session freshness refusal in the right place, and the admission-paths ratchet records it as a new site.

Optional:

  • No test fails if the keys_tool_surface gate in resolve_chat_share (providers/chat_share.py:887) is reverted. A resolve_chat_share case for a claude provider with pinned=True that asserts agent and spec_generation are empty in the key would pin it.
  • The comments at harness/claude.py:700 and providers/acp_runtime_start.py:482 say the runtime model is the founder's. Every shared claude AcpRuntime is built with no model, so the seed now names the chat's own model where before it named none.
  • FOUNDER_TOOL_SURFACE_BACKENDS has one member and one reader, and the second clause in keys_tool_surface is always true for KAS. Please answer the First Principles note on it either way, so the choice is on record.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 16, 2026
…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.
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-per-session-fields branch from 2c318c3 to 57991e2 Compare November 16, 2026 03:42
@chenmingwei23
chenmingwei23 enabled auto-merge (squash) November 16, 2026 03:42
@github-actions github-actions Bot added readiness: checking Automated validation is still running and removed readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge labels Nov 16, 2026

@bolichen97 bolichen97 left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

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_spawn and apply_spawn_env read only the argv, work_dir and 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_state resolves the session's own agent (_source_agent), and create_session builds 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 in session_meta) and the options.env identity are per session too.
  • Own model and effort. The seed now takes the chat's model from _harness_session_options, and the start still pushes set_model and effort per session.
  • Freshness gate per agent. require_fresh_derived_spec now runs in prepare_session for the joiner's agent, off the loop, before any seed is written.
  • Switch off equals main. prepare_session runs only on the shared runtime, and goose and deepseek ignore the new model option.
  • 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_surface gate in resolve_chat_share (providers/chat_share.py:887) is reverted. A claude resolve_chat_share case with a pinning reader that asserts agent and spec_generation are empty in the key would pin it. The tree test covers only the ChatSharePlacement site.
  • 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

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 16, 2026
@chenmingwei23
chenmingwei23 merged commit a0fc2c7 into main Nov 16, 2026
158 of 167 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/claude-shared-per-session-fields branch November 16, 2026 10:30
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 16, 2026
bolichen97 added a commit that referenced this pull request Nov 16, 2026
…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>
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.

5 participants