Skip to content

feat(acp): read claude background work per session on the shared runtime - #37593

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

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

Conversation

@chenmingwei23

@chenmingwei23 chenmingwei23 commented Nov 15, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: a claude chat on the shared ACP runtime shows the background-command end and API-retry notices and the Workflow agent cards that a chat on its own process shows, each only in its own chat.

#37512 asks claude-agent-acp for Claude Code's raw SDK messages about background tasks and API retries (_claude/sdkMessage) and reads them in AcpClient's transport reader (acp.raw_sdk_tasks). The shared runtime's session envelope asks for the same messages, but its reader puts them on the session's queue, where AcpSessionHandle reads them as nothing. Once claude chats share one process (#37540), such a chat would lose the row that says a background command ended, the warning that a request is being retried, and every Workflow agent card.

Stack: this branch carries #37521 (ClaudeHarness) and #37586 (the claude surfaces on the shared handle) underneath one commit of its own. It merges after both and is rebased to one commit then; review only the top commit. #37540 and #37563 stack on top.

Why it matters

These rows are how a user learns that work they started in the background finished or that the model is being retried. With several chats on one adapter, each message must reach the chat whose session it names and no other.

Not a goal

  • Routing any claude chat to the shared runtime: that is feat(acp): let claude dashboard chats share one ACP process, switch off by default #37540, switched off by default.
  • Claude's Agent-tool children (subagent_update) on the shared runtime: their routing, cards and the per-child Stop are the next PR in the stack.
  • No change for kiro-cli, KAS or codex: the new seam answers False on every other host, and raw_sdk_tasks checks ACP_BACKENDS_RAW_SDK_TASKS itself.

What changed (motivation -> approach -> change)

The handle should read these messages as the per-chat client does: in the reader, into the session's own state, on no queue -> reuse raw_sdk_tasks and give it a per-session state the runtime's reader can reach -> a harness seam and a handle property.

  • Seam HarnessAdapter.take_session_frame(state, msg) (default False). The runtime's reader asks it for each notification that names a session, with that session's harness state; a frame it takes is put on no queue, so a turn, a waiting request and an idle reader all read past it. ClaudeHarness takes a _claude/sdkMessage into the session's ClaudeSharedSession._raw_sdk (raw_sdk_tasks.take), which already checks the session id. The reader resolves the seam once, as it does the harness's capability declaration, and acts only on an explicit True.
  • Handle. AcpSessionHandle._raw_sdk reads that state (the handle's own empty one when the host keeps none). _dispatch_events takes the dashboard's mark (begin_draw) and draws what waits before each frame (pending_events), as client_turn._dispatch_events does. _native_child_roster lists the handle's announced children ahead of a Workflow's agents. native_child_resume_refusal refuses a Workflow agent's card and report_native_children counts the agents still running, as on the client.
  • Provider. AcpSessionProvider._raw_sdk exposes the handle's state, so the dashboard's mark (expect_dashboard_turn), its kept-open cards (live_card_ids) and its lost-cards callback (on_cards_lost) reach the session through the slot's client.
  • Line cap. AcpSessionProvider.rekey and reclaim move whole into acp/session_provider_claim.py, bound on the class as before, so session_provider.py stays under the 2,000-line cap with the new property. They read schedule_claim and schedule_session_token_publish off acp.session_provider at call time, so a patch there still reaches them.
  • End. ClaudeHarness.end_session forgets the session's tasks (raw_sdk_tasks.forget_tasks), which runs the lost-cards callback, as the client does when its session or process goes.

Backwards compatibility

Compatible: the seam answers False on every host but claude, and no claude chat takes the shared runtime until #37540's switch is on.

Removes nothing: every change adds a reader or a field; no key, row or function is removed or renamed.

Tests

test/test_claude_shared_background.py: two claude chats on one runtime, frames written to the runtime's stdout and read by its real reader loop. Chat A's messages arrive while chat B's dashboard turn reads; then A's dashboard turn runs.

  • a background command's end is one notice in A and none in B;
  • an API retry is one warning in A and none in B;
  • a Workflow's running agent is a card in A only: kept open, refused as a resume target and counted for A, none of these for B;
  • a turn the dashboard did not mark draws nothing, and the next marked turn draws it;
  • ending A's session runs A's lost-cards callback and not B's.

With the reader's seam call switched off, or the dispatch's begin_draw replaced by False, the first four fail; without forget_tasks in end_session, the last fails.

Proof: not provable -- other: feature PR, the mutations above are the check

Also run, serially: test_session_handle_bindings, test_runtime_bindings, test_harness_parity, test_acp_runtime, test_claude_shared_runtime, test_claude_shared_surfaces, test_claude_raw_sdk_tasks*, test_security_posture, and every test file that touches the reader loop, the handle's dispatch or native children, or the harness seams (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) runs a background command and a retry on a shared chat.

Related Issues

Follows #37512. Part of the claude chat sharing stack: #37521, #37586, this PR, then the Agent-tool children 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 d8221ed4bfe9eeca050dcb83160acad8504a6cfb 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 d8221ed4bfe9eeca050dcb83160acad8504a6cfb — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the change adds a seam that answers False on every host but claude, and no chat reaches this path until #37540's switch is on.

Notes

  • The description leaves out one behaviour the diff adds. end_session now keeps up to 64 ended sessions' _raw_sdk in _carried_raw_sdk_by_session, and bind_started hands that state to the next session with the same id. That carry-over is per harness instance and survives a reload, so the "End" bullet should describe it.
  • When a session is closed for good, its carried entry is not removed; it stays until the 64-entry cap pushes it out (the diff's own shortcut: comment admits this). A later session that reuses the id would inherit stale seen_cards and the old dashboard_turn mark. Keying the removal on the session's eviction is the simple fix.

[DESIGN-REVIEWED] d8221ed

Description read

[DESCRIPTION-READ] c7be590bbb1079616c04c960ea2224a56220418790cd398b6bf89d9d51d7c41b

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 d8221ed4bfe9eeca050dcb83160acad8504a6cfb — 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 item carries the existing raw_sdk_tasks reader over to the shared handle, and claude chats only reach it once #37540's switch is on. One cache that carries state across a reload is not in the description.

Notes

  • Item 6 — undeclared: the description never mentions _CARRIED_RAW_SDK_CAP = 64 / _carried_raw_sdk_by_session, which keeps an ended session's dashboard_turn and seen_cards for the next session with the same id. The diff's own comment admits that "a session closed for good leaves its entry until the cap drops it". Subtraction: drop the carry from ClaudeHarness.end_session/prepare_session unless a test in test_claude_shared_background.py shows a reload losing a card without it.

What this change ships

Inventory (7 items) — 6 justified

Intent: a claude chat on the shared runtime shows its own background-command-end and retry notices and Workflow agent cards, and none from other chats. ADDITION.

  1. The shared runtime's reader passes a session's _claude/sdkMessage frames to that session's harness state (new take_session_frame seam, False by default) — justified
  2. A dashboard turn on a shared chat draws background-end and retry notices before each frame — justified
  3. A Workflow agent's card appears, is refused as a resume target, and is counted in the native-children report — justified
  4. The provider exposes _raw_sdk, so the dashboard's mark and lost-cards callback reach the session — justified
  5. Ending a claude session closes its kept-open cards (forget_tasks) — justified
  6. An ended session's dashboard mark and seen card ids carry over to a later session with the same id, capped at 64 — undeclared
  7. rekey/reclaim move into session_provider_claim.py to stay under the line cap — justified

[FIRST-PRINCIPLES-REVIEWED] d8221ed

Description read

[DESCRIPTION-READ] 6645b7a188ab2316714f63889c4ce916472076f4048be36bdcc2cbd17b70861a

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 d8221ed4bfe9eeca050dcb83160acad8504a6cfb and found no blocking issues.

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] d8221ed

False positive or not applicable? A repository writer can comment:
/ai-review override gpt d8221ed4bfe9eeca050dcb83160acad8504a6cfb 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 d8221ed4bfe9eeca050dcb83160acad8504a6cfb — this comment is updated in place on each push.

Review details

No findings.

[OPUS-REVIEWED] d8221ed

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

False positive or not applicable? A repository writer can comment:
/ai-review override fable d8221ed4bfe9eeca050dcb83160acad8504a6cfb 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 does what it says. The shared runtime's reader passes a session's _claude/sdkMessage frames to that session's own ClaudeSharedSession state through a new harness seam, which answers False by default. The claude reader takes only frames of the matching session. The handle and provider expose that state, so the dashboard mark, kept-open cards and lost-cards callback work as on the per-chat client. end_session calls forget_tasks. The session state's writers (create/load) and its removers (terminate/evict, both calling end_session) are consistent. The harness is cached per runtime, so the carry-over is per runtime, and a reload ends the old state before the new one is set up. Non-claude hosts are unaffected because every reader-side check tests the backend. The rekey/reclaim move is unchanged code that still looks up its patched helpers at call time. Tests cover isolation between chats, the dashboard-mark gating, forget_tasks on end and the reload carry. Remaining gaps are an undeclared carry cache, spec docs not updated and test CI still pending, none 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 d8221ed4bf · 580 changed lines. If this recommendation is wrong, reply here: replies are how the approver is evaluated.

@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-background branch from 2d96bd9 to c29c3c1 Compare November 15, 2026 12:22
@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-background branch 2 times, most recently from 3bb1c5f to 41fc534 Compare November 15, 2026 12:53
@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-background branch from 41fc534 to 02a16ea Compare November 15, 2026 14:04
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention 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 readiness: checking Automated validation is still running labels Nov 15, 2026
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-background branch from 02a16ea to 23b81b1 Compare November 15, 2026 15:29
@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 added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 15, 2026
claude-agent-acp sends Claude Code's background-task and API-retry
messages as _claude/sdkMessage notifications. The per-chat AcpClient
reads them in its transport reader; on the shared runtime they went to
the session's queue, where the handle read them as nothing, so a
shared claude chat lost the background-command end and API-retry
notices and the Workflow agent cards.

- A new harness seam, take_session_frame, lets the runtime's reader
  hand a session's notification to that session's harness state.
  ClaudeHarness reads a _claude/sdkMessage into the session's own
  ClaudeSharedSession._raw_sdk (raw_sdk_tasks.take), on no queue.
- AcpSessionHandle reads that state as _raw_sdk; its dispatch takes
  the dashboard's mark (begin_draw) and draws what waits before each
  frame (pending_events), as the client's dispatch does. The handle
  lists its announced children ahead of a Workflow's agents
  (_native_child_roster), refuses a resume of a Workflow agent's card
  and counts the agents that still run.
- AcpSessionProvider exposes the handle's state, so the dashboard's
  mark, its kept-open cards and its lost-cards callback reach it.
- Ending the session forgets its tasks (ClaudeHarness.end_session),
  which closes the cards the dashboard kept open.

Tests run two chats on one runtime through the real reader loop: chat
A's messages, sent while chat B's turn reads, are drawn by A's next
dashboard turn and never by B's.
@chenmingwei23
chenmingwei23 force-pushed the feat/claude-shared-background branch from 23b81b1 to d8221ed Compare November 15, 2026 16:05
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed merge conflict Branch has merge conflicts with its base — author must resolve before merge readiness: checking Automated validation is still running labels Nov 15, 2026
@chenmingwei23
chenmingwei23 enabled auto-merge (squash) November 15, 2026 17:16

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

Approving. On head d8221ed the review checked these points. The runtime reader gives a session-tagged _claude/sdkMessage frame only to the harness state for that frame's own session, and raw_sdk_tasks.take checks sessionId a second time, so chat A's frames never reach chat B. Non-claude hosts answer False at the new seam and see no behaviour change. The moved rekey/reclaim code is identical to the original and still reads its patch seams at call time. The review ran the new test file and the related raw_sdk_tasks, runtime, handle and provider tests on the extracted head, and all passed. It also re-ran the body's stated mutations, and each one turned its named test red.

Done well: every isolation test drives two live chats through the real runtime reader loop and checks both sides.

Optional:

  • docs/system-specs/modules/claude-code-provider.md still calls client_transport._read_message "the only stdout reader". The acp-client and providers specs do not list take_session_frame beside holds_replayed_permission. A follow-up doc edit would fix both.
  • The 64-entry carry of an ended session's dashboard mark and seen cards in ClaudeHarness.end_session is not described in the PR body, and no test covers its cap. A short note in "What changed" and a cap test would help. The AcpSessionHandle._raw_sdk setter has no caller and could be dropped.
  • The Stack and Manual verification paragraphs still point at #37563, which closed without merging. Pointing them at the current top of the stack would keep them accurate.

@chenmingwei23
chenmingwei23 merged commit d8f79dd into main Nov 15, 2026
99 checks passed
@chenmingwei23
chenmingwei23 deleted the feat/claude-shared-background branch November 15, 2026 17:42
@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