Skip to content

feat(acp): show the claude surfaces on shared-runtime chats - #37586

Merged
chenmingwei23 merged 1 commit into
mainfrom
feat/claude-shared-surfaces
Nov 15, 2026
Merged

chenmingwei23 merged 1 commit into
mainfrom
feat/claude-shared-surfaces

Conversation

@chenmingwei23

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a claude chat on the shared ACP runtime shows the same claude-agent-acp notices, mode changes, checklist, Read previews and compaction summaries as a chat on its own process, each only in its own chat.

#37512 added these surfaces to the per-chat AcpClient readers (client_turn, client_tool_events). A chat on the shared runtime reads its frames through AcpSessionHandle, which calls none of them, so once claude chats can share one process (#37540) those chats would lose the adapter's rate-limit and retry notices, the mode-change line, the plan checklist, the Read image preview and the summary on the compaction card.

Stack: this branch carries #37521 (ClaudeHarness, not routed) underneath one commit of its own. It merges after #37521 and is rebased to one commit then; review only the top commit. #37540 and #37563 stack on top of it.

Why it matters

Without this, turning on claude chat sharing silently drops display rows the user sees today on a per-chat claude process. With several chats on one adapter, each of these rows must also land in the chat whose session sent it and in no other.

Not a goal

  • Routing any claude chat to the shared runtime. Nothing here changes which arm a chat takes; that is feat(acp): let claude dashboard chats share one ACP process, switch off by default #37540, and its switch is off by default.
  • The surfaces that come from claude's raw SDK messages (background task end, API retry notices), Workflow agent cards, and child card Stop on the shared handle. Those are the next PR in the stack.
  • Crew-spawned subagent card titles: claude is not in ACP_BACKENDS_SESSION_SHARING, so a claude chat's subagents keep their own process, where CardToolTitles already applies.
  • No change for kiro-cli, KAS or codex sessions: every reader added here checks its own ACP_BACKENDS_* set first.

What changed (motivation -> approach -> change)

The handle should show what the per-chat client shows -> reuse the #37512 readers instead of copying them -> one wrapper around the handle's frame parser calls them for this session's own frames.

  • New owner module acp/session_handle_harness_surfaces.py. AcpSessionHandle._handle_update is now its _handle_update, which wraps the parser (renamed session_handle_updates._handle_update_frame). For a frame naming this session it:
    • turns an adapter notice into a text chunk with harness_notice attached (harness_notices.adapter_notice);
    • keeps a compaction's streamed summary chunks off the turn (compaction_summary.note_chunk) and titles the completed card with the summary;
    • emits the checklist (plan_checklist.todo_event) and the mode-change notice (harness_notices.mode_notice_event) before the frame's own events;
    • sets read_path_arg on Read tool events.
      A frame of another session, or of a backend outside the sets, goes to the parser unchanged.
  • Handle fields the readers take: a backend property (the runtime's backend id), _acp_config_options (the stored config options), the mode names and last mode report (_harness_mode_names, _harness_mode, written by the readers), and its own CompactionSummaries. store_session_config notes the session's mode names (harness_notices.note_session_modes), as the client does on session/new.
  • Thinking and the Fast mode switch already reach a shared chat: thought chunks go through the shared parser, and the dashboard provider reads fast from the session provider's acp_config_options. They get the same two-chat tests.
  • test_session_handle_bindings inventory and test_harness_parity's identity declaration follow the rename.

Backwards compatibility

Compatible: the readers act only for a backend in their ACP_BACKENDS_* set, and only claude is in them; no claude chat takes the shared runtime until #37540's switch is on.

Removes nothing: _handle_update keeps its name and signature on the handle; the parser it wrapped is renamed _handle_update_frame and has no other caller.

Tests

test/test_claude_shared_surfaces.py: two claude chats on one runtime, frames written to the runtime's stdout and read by its real reader loop. Each test sends chat A's frame and checks A's turn shows the surface and B's turn shows none of it:

  • an adapter notice reaches only its own chat;
  • a mode change notice and a checklist stay with their chat;
  • a Read call names its preview argument;
  • a compaction summary titles A's completed card and is no text of the turn;
  • a thought reaches only A, as thinking;
  • the Fast mode switch reads per chat (A on, B still off).

With _handle_update pointed back at the bare parser, the first four fail; the last two are routed by the runtime and pass either way.

Proof: not provable -- other: feature PR, the mutation above is the check

Also run, serially: test_session_handle_bindings, test_harness_parity, test_runtime_bindings, test_acp_runtime, test_claude_shared_runtime, test_security_posture, and every test file that calls _handle_update or the #37512 readers (all pass).

Manual verification

N/A for this PR alone: no chat reaches this path until #37540's switch is on. The pod check of #37563 (the top of the stack) looks at each surface on a shared chat.

Related Issues

Follows #37512. Part of the claude chat sharing stack: #37521, this PR, #37540, #37563.

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.

@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

UX Review (Opus 5.5) — ⏭️ skipped

Revision cacf90822466a75f8369972cdd339288a26a1154 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 cacf90822466a75f8369972cdd339288a26a1154 — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

No design-level concerns: the #37512 readers are reused through one wrapper around the handle's parser, each reader checks its backend set and the session id first, and the renamed _handle_update_frame has no caller outside this PR.

[DESIGN-REVIEWED] cacf908

Description read

[DESCRIPTION-READ] a9b055c1187289afe4b024b9a64dfa50b6174b83c35265bbd6002a42adb06fef

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 cacf90822466a75f8369972cdd339288a26a1154 — 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: every surface reuses the #37512 readers, each one is limited to its own ACP_BACKENDS_* set and its own session, and no chat reaches this path until #37540's switch is on.

Notes

  • Item 5 — duplicate of src/kiro_crew/acp/client_usage.py:300-325: _fold_compaction_summary restates when a summary is forgotten and when it titles the card, by scanning the parsed events afterwards. Subtraction: delete _fold_compaction_summary and call compaction_summary.completed_summary/forget where the handle's parser builds the EVENT_COMPACTION_STATUS event, so one place decides it.

What this change ships

Inventory (7 items) — 6 justified

Intent: a claude chat on the shared ACP runtime shows the same adapter rows a per-chat claude process shows, each only in its own chat — ADDITION.

  1. An adapter notice (rate-limit or retry) shows as a row in its own shared chat only — justified
  2. A mode-change line appears on a shared claude chat — justified
  3. The plan checklist appears on a shared claude chat — justified
  4. A Read call on a shared chat shows the image preview — justified
  5. The compaction card carries its summary, and the summary's chunks stay out of the reply — duplicate of client_usage.py fold policy
  6. The handle records the session's mode names on session/new (store_session_config) — justified
  7. _handle_update now wraps the parser, which is renamed _handle_update_frame, and the handle gains a backend property — justified

[FIRST-PRINCIPLES-REVIEWED] cacf908

Description read

[DESCRIPTION-READ] 951e7fd79f0519bb997f279acee18e05d3dd0cb7c61e067d4a0e6b21bf1be24c

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

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] cacf908

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

@github-actions

github-actions Bot commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] cacf908

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

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

@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 14% chance that this change introduces a defect, above the 12% limit for approving on its own.

The PR wraps the shared handle's session/update parser so a claude chat on the shared runtime gets the per-chat client's surfaces (#37512): adapter notices, mode-change notices, the plan checklist, the Read preview argument and compaction summaries. It reuses the existing readers, each gated on its own ACP_BACKENDS_* set and on the session id. Frames from other sessions and native children go to the existing parser unchanged. Mode names are recorded on both session/new and session/load. The new backend property matches what batch_guard already fell back to, and no raw_sdk_tasks path changes. The shared runtime declares the same claude capabilities as the per-chat client, so these surfaces are live once routing is on. The compaction fold matches the client for completed, failed, cancelled and repeated-terminal frames. The two-chat tests drive the real reader loop and would fail without the wrapper. Nothing routes to this path until #37540. The remaining concerns are a speculative compaction edge case and doc drift, neither of which blocks.

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

@github-actions github-actions Bot added 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: checking Automated validation is still running labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-surfaces branch from f3843ff to 7f42776 Compare November 15, 2026 12:20
@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
@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-surfaces branch from 7f42776 to a78c459 Compare November 15, 2026 12:40
@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
A claude chat on the shared runtime reads its frames through
AcpSessionHandle, which had none of the claude-agent-acp surfaces the
per-chat AcpClient shows. The handle's _handle_update now wraps the
frame parser (renamed _handle_update_frame) with the same readers, for
this session's own frames only:

- an adapter notice becomes its reply text with the notice attached;
- a mode change and a plan's checklist are events before the frame's;
- a read tool call names the argument the row previews;
- a native compaction's streamed summary is kept off the turn's text
  and titles the completed card.

The handle gains the fields those readers take (backend,
_acp_config_options, the mode names noted at session start, and its
own CompactionSummaries).

Tests run two chats on one runtime through the real reader loop and
check each surface reaches only its own chat; thinking and the Fast
mode switch are covered the same way.
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-surfaces branch from a78c459 to cacf908 Compare November 15, 2026 14:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision 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 enabled auto-merge (squash) November 15, 2026 15:32

@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.

This review checked the diff on this head (one commit on top of current main) along with the shared-handle code it touches. The new wrapper reuses the existing claude surface readers, and each reader still checks its own claude-only backend set and its own session. Kiro, KAS and codex frames come out unchanged. The new two-chat tests pass (6 of 6) in a serial run. Pointing _handle_update back at the bare parser makes the first four fail, exactly as the body says. Each mutated production line we tried reds a test. Done well: the per-chat readers are reused through one wrapper instead of copied, and the tests drive real frames through the runtime's reader loop with two chats on one process.

Optional:

  • docs/system-specs/modules/acp-client.md has no owner-table row for acp/session_handle_harness_surfaces.py, and three passages still name _handle_update as the parser. client_usage.py:268 still says the handle's twin reads no summary. A follow-up could fix all four.
  • _fold_compaction_summary decides the compaction outcome a second time, after parsing. If the forget and completed-summary calls moved into the handle's compaction twin, the same way client_usage.py does it, the wrapper would be gone and the repeated-start forget difference with it.
  • A two-chat case where chat B gets frames of its own would pin the session guard at line 54 and the per-handle CompactionSummaries. Today both survive mutation, because the runtime's routing already keeps B's frames away.

@chenmingwei23
chenmingwei23 merged commit c4f432a into main Nov 15, 2026
99 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/claude-shared-surfaces branch November 15, 2026 15:53
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 15, 2026
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.

3 participants