Repository navigation
fix(acp): keep an agent-started turn's frames through a request wait - #29269
Conversation
UX Review (Opus 5.5) — ⏭️ skippedRevision |
Design Review (Opus 5.5) — ✅ PASSDesign-level review of Design-Verdict: PASS No design-level concerns block this: the hold sits once in the claude-only stdout claim, nothing registers Notes
[DESIGN-REVIEWED] 7467b9d Description read[DESCRIPTION-READ] a8b7b29a7a9ee771523b6133bc392aba9fce202cf35d2bcc1e2d8227330ec039 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. The fix targets the mechanism behind #22262, and the shared stdout claim covers every wrapped reader in one place. Agent-started turns are covered by an accepted RFC. What this change shipsInventory (8 items) — 7 justifiedIntent: make an agent-started Claude turn keep its first frame when a config, entitlement or compaction wait reads stdout in the hand-off window. FIX.
[FIRST-PRINCIPLES-REVIEWED] 7467b9d Description read[DESCRIPTION-READ] ba7ef751e0ca5c261de5645a2ec4a20e89abe603cbbe4b2c5f6a6a5ec0798ff9 That sha256 names the PR description this verdict read. Recompute it with |
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: |
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: |
bolichen97
left a comment
There was a problem hiding this comment.
Approving at 85f575d. Before this change, a request wait, wait_for_compaction or _drain_post_compaction_metadata running in the hand-off window filed a pending turn's start frame in _mcp_notifications. Now the stdout claim keeps those frames for the turn instead.
How it works:
_claiming_stdoutstarts a hold only when a hand-off is pending and no hold is active. When the wrapped reader returns, it puts the held frames back at the front of_bufferwithextendleft(reversed(held)), so they keep their arrival order.- The bound
_read_messageholds only frames_starts_agent_turnaccepts, and returnsNoneso the reader still checks its own deadline. It stops holding at_buffer.maxlen, so putting the frames back pushes nothing out. _cancel_idle_readerclears_agent_turn_held, and theself._agent_turn_held is heldcheck skips the put-back after a reset.- A Kiro client binds neither wrapper, so its read path is unchanged.
The tests cover all three readers, a permission request keeping its place among the chunks, held frames going ahead of unread ones, the room limit and a reset mid-wait. The old filing test is replaced.
One question, not a blocker: the room check counts _buffer when each frame is held. If the wrapped reader then puts its own deferred frames back into _buffer before the claim returns, extendleft could push the oldest unread frames off the right end. If _wait_for_response can defer a frame that _starts_agent_turn rejects, a re-check at put-back time would close that gap.
CI at this head: 82 ok, and all AI lanes and E2E pass. The remaining reds are PR Readiness and a cancelled duplicate run. Only test shards and PR Readiness are pending.
85f575d to
f295fdb
Compare
commented
Nov 3, 2026
Security Scope Review -- 🔴 could not complete (fails closed)No scope verdict for |
left a comment
There was a problem hiding this comment.
Re-approving at f295fdb so the last push has a fresh approval. This head is a rebase onto main. The PR's own code and tests are unchanged from 85f575d (client_transport.py, client_class.py, test_acp_client_agent_started_turns.py, test_client_bindings.py), and the doc only picks up main's text. My earlier review still holds.
CI at this head: every non-shard job passes, including E2E, Integration, Build Desktop, the macOS smoke install, Security Scope Review, GPT and PR Hygiene. The first runs were cancelled with no runner, and I reran the failed jobs once. Only macOS test shards and PR Readiness are still pending.
f295fdb to
0af9574
Compare
On a claude client with an agent-started turn handed off but not yet read, a request wait, wait_for_compaction or _drain_post_compaction_metadata that ran in that window filed the turn's start session/update in _mcp_notifications, so stream_unsolicited() read the turn without its first chunk. The stdout claim the claude adapter binds now keeps those frames for the turn: while a hand-off is pending, the claimed reader holds every frame of a kind that starts a turn, requests from the agent included, and puts them back at the front of _buffer in arrival order when it returns. Requests share the list because a request wait puts back the requests it defers on its own, which would reorder them against the held chunks. Other frames keep that reader's handling. A frame that would not fit in _buffer beside the held ones is not held, and a kill or reset drops the hold. Nothing registers on_agent_turn yet, so users see no change, and a Kiro client never binds the claim, so its read path is unchanged. Fixes #22262
0af9574 to
7467b9d
Compare
left a comment
There was a problem hiding this comment.
Re-approving at 7467b9d. The new change: while a claimed reader holds a pending turn's frames, the bound _read_message now also holds a frame _ends_agent_started_turn accepts. That is the autonomous usage_update that closes the turn, so the turn still ends on it instead of losing it to _mcp_notifications. Responses are excluded (msg.method is not None), so the reader still gets its own answer. test_a_reader_in_the_window_keeps_the_turns_closing_usage_update runs all three readers and checks the turn reads both chunks, completes, and leaves _buffer empty. The client_class.py line comes from main via the rebase. The rest of my earlier review holds.
CI at this head: 94 ok. The first run of Opus, GPT, Design, UX, First Principles, Sensitive Change Review and the license gate failed on infra (installation rate limit, unreadable merge-base, dependency graph). I reran each once, and all now pass. The remaining reds are the readiness publisher, and only PR Readiness and test shards are pending.
Problem / Motivation
Goal: Keep the first frame of a turn Claude Code starts on its own when a request or compaction wait reads stdout before that turn is read, with no user-visible change yet.
On the
claudebackend, the idle reader from #18285 notices a turn Claude Code starts between prompts, puts the frames it read back at the front of_buffer, records the start frame and callson_agent_turn. The hand-off stays pending until a reader takes that frame. If a request wait (_wait_for_response, for example a config-option push or an entitlement probe),wait_for_compactionor_drain_post_compaction_metadataruns in that window, it files every notification it reads in_mcp_notifications, the turn's startsession/updateincluded. The turnstream_unsolicited()reads afterwards then starts without its firstagent_message_chunkortool_call, and the restarted reader hands off a second time on the next frame (#22262).Why it matters
The dashboard PR that registers
on_agent_turnshows that turn as its own message. Without this fix, a model or mode change, or a compaction wait, that lands in the window cuts the first words or the first tool call off the agent's reply, and the reply is announced twice. Fixing it in the transport keeps that race out of the dashboard PR.Not a goal
on_agent_turn, or showing the turn in the dashboard. That is the RFC's Phase 2._bufferfull of state frames) and Claude backend: a steer or a late steering answer can end an agent-started turn early #22264 (steers inside an agent-started turn).stream_unsolicited()wait for a request wait that runs at the same time. The two do not coordinate on main either.claude.What changed (motivation → approach → change)
Users see no change from this PR: nothing registers
on_agent_turnyet.The three readers handle each frame the way they always have, and nothing tells them that a frame belongs to a pending turn. All three already take the stdout claim the claude adapter binds, so the rule lives there once, in
acp/client_transport.py, and it covers every other wrapped reader too (_drain_notifications,_read_steer_answers,ensure_ready,_initialize_session).acp/client_class.pydeclares the one new attribute, anddocs/system-specs/modules/acp-client.mdgains a bullet on the hold and drops the sentence that said a request wait files the start frame._claiming_stdoutstarts a hold (_agent_turn_held) when it claims stdout while a hand-off is pending and no hold is active; a nested claim joins it. When the wrapped reader returns, the held frames go back to the front of_bufferin arrival order, so the start frame is first again,_agent_turn_pending()is True, the idle reader stays off andstream_unsolicited()reads the whole turn._read_message_install_idle_readerbinds a_read_messageon the claude instance. While a hold is active it keeps each frame_starts_agent_turnaccepts (the five activity kinds, or a request from the agent) and returnsNoneto the reader, which then checks its own deadline. Every other frame reaches the reader as on main._buffer(itsmaxlen, 100) beside the held ones is not held and gets the reader's own handling, so putting the frames back pushes nothing out of the deque._cancel_idle_readerdrops the hold, so frames from a process that is gone are not put back.Two details go beyond the issue's wording. The hold keeps requests from the agent as well as
session/updateframes, in one list:_wait_for_responseputs the requests it defers back when it returns, before the claim puts the held frames back, so holding onlysession/updateframes would move a permission request behind chunks that arrived after it. As a result,wait_for_compactionand_drain_post_compaction_metadata, which drop any request they read, now keep one that arrives in the window. And a held frame no longer extends_wait_for_response's activity-based deadline, because the wait never sees it.Two limits stay. A turn that outgrows
_buffer's room during one wait reads the held frames, loses the overflow to_mcp_notificationsas on main, then reads the rest live. Andstream_unsolicited()called while a reader holds the frames yields nothing, since_agent_turn_pending()is False until they are back; reading beside that reader would put a secondreadline()on the stream. The frames are in_bufferagain once the reader returns.Backwards compatibility
Compatible: nothing registers
on_agent_turn, so no hand-off is pending outside tests and the hold never starts, and a client of any backend outsideACP_BACKENDS_AGENT_STARTED_TURNSbinds neither the claim nor the_read_messagewrapper, so a Kiro client's read path is main's (harness-parity H13).Removes nothing: the change adds a hold to the claim the claude adapter binds and one class attribute; every read path stays.
Tests
Proof: PROVEN test/test_acp_client_agent_started_turns.py::test_a_reader_in_the_hand_off_window_keeps_the_turns_frames_for_it[_wait_for_response], test/test_acp_client_agent_started_turns.py::test_a_reader_in_the_hand_off_window_keeps_the_turns_frames_for_it[wait_for_compaction], test/test_acp_client_agent_started_turns.py::test_a_reader_in_the_hand_off_window_keeps_the_turns_frames_for_it[_drain_post_compaction_metadata], test/test_acp_client_agent_started_turns.py::test_a_permission_request_in_the_window_keeps_its_place_among_the_turns_frames[_wait_for_response], test/test_acp_client_agent_started_turns.py::test_a_permission_request_in_the_window_keeps_its_place_among_the_turns_frames[wait_for_compaction] (head 7467b9d)
test/test_acp_client_agent_started_turns.py, over a realasyncio.StreamReaderwith a callback registered:_wait_for_response,wait_for_compactionand_drain_post_compaction_metadata, run after a hand-off on a chunk, reads a thought chunk, asession_info_updateand a second chunk before the frame that ends it. Thesession_info_updateis in_mcp_notificationsas on main, the hand-off is still pending, andstream_unsolicited()then yields the start chunk first, the thought and the second chunk after it in order, and ends on the autonomous origin._bufferas chunk, request, chunk.test_a_request_wait_that_puts_the_first_frame_back_keeps_the_hand_offfrom feat(acp): read a claude turn the agent starts between prompts #18285 (the request as the start frame) passes unchanged._buffer; a frame past the room is filed, not pushed out; a reset during the wait drops what was held.test_a_request_wait_that_reads_the_first_frame_ends_the_hand_off, which pinned the old filing, is replaced by the first test._read_messagejoins the list of methods the claude adapter binds, so the respawn test checks it is bound once and the Kiro test checks a Kiro client keeps the class method.Each of seven mutations of the production change turns at least one test red: not starting the hold, binding no
_read_message, holding onlysession/updateframes, appending instead of prepending, dropping the room check, leaving the hold in place on a reset, and putting frames back after a reset.test/test_client_bindings.pygains the_agent_turn_heldrow.test_acp_client_agent_started_turns.pypassed 10 runs at-n0and 3 at-n 4 --dist loadgroup --max-worker-restart=2besidetest_acp_client_shutdown_reset.pyandtest_acp_client_capabilities.py; it waits on observed state, never on a sleep. Alltest/test_acp_client_*.py,test_acp_copilot_backend.py,test_acp_harness_contract.py,test_claude_*.pyandtest_client_bindings.pypass (1819 tests). flake8,mypy src/kiro_crew, the black and subprocess-encoding gates,scripts/docs-lint.shandscripts/check_harness_parity.pypass.Manual verification
N/A — unit coverage sufficient: nothing registers
on_agent_turn, so no running session opens the hand-off window outside the tests, and the tests driveAcpClientover a realasyncio.StreamReaderthrough each of the three readers. The dashboard PR that registers the callback carries the live repro.Screenshots / video
N/A: no UI change.
Related Issues
Closes #22262
Refs #17566 (this is the transport slice; the dashboard phase that registers
on_agent_turnis what makes the #17566 fix visible)Continues #25134 by @rinbn. A second commit on top holds the autonomous
usage_updatethat closes the turn with the turn's other frames, so a request wait in the window no longer files it andstream_unsolicited()still ends the turn on it (GPT review finding on 0af9574). A response is never held. Pinned bytest_a_reader_in_the_window_keeps_the_turns_closing_usage_update, red for all three readers when that commit is reverted. The commit is rinbn's own, rebased onto main with an identical patch (git patch-id7198a7a87c53 on both heads), so the authorship credits them.Co-authored-by: wenlin 34065934+rinbn@users.noreply.github.com
Sibling sweep
Swept: git grep -nE "_mcp_notifications.append|self._read_message(" -- src/kiro_crew/acp/
Sibling: src/kiro_crew/acp/client_transport.py:879 -- changed here
Sibling: src/kiro_crew/acp/client_usage.py:469 -- not affected --
wait_for_compaction(L469) and_drain_post_compaction_metadata(L506) read through the claim in client_transport.py, which holds the turn's frames before they see themSibling: src/kiro_crew/acp/client_turn_control.py:1020 -- not affected --
_read_steer_answersreads through that same claimSibling: src/kiro_crew/acp/client_turn.py:420 -- not affected -- this is the turn's own read, which takes the frames as its own
Sibling: src/kiro_crew/acp/session_handle_compaction.py -- not affected -- AcpSessionHandle runs no idle reader, so it has no hand-off to keep
Pattern harvest
Not generalizable: the defect is specific to the hand-off window the idle reader opens, and the one rule now sits at the claim every stdout reader on that client already takes, which
test_every_read_message_caller_claims_stdoutenforces.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; see the Licensing section of CONTRIBUTING.md.