Skip to content

fix(acp): keep an agent-started turn's frames through a request wait - #29269

Merged
bolichen97 merged 2 commits into
mainfrom
fix/agent-turn-handoff-hold-22262
Nov 4, 2026
Merged

bolichen97 merged 2 commits into
mainfrom
fix/agent-turn-handoff-hold-22262

Conversation

@buluoray

@buluoray buluoray commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

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 claude backend, 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 calls on_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_compaction or _drain_post_compaction_metadata runs in that window, it files every notification it reads in _mcp_notifications, the turn's start session/update included. The turn stream_unsolicited() reads afterwards then starts without its first agent_message_chunk or tool_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_turn shows 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

What changed (motivation → approach → change)

Users see no change from this PR: nothing registers on_agent_turn yet.

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.py declares the one new attribute, and docs/system-specs/modules/acp-client.md gains a bullet on the hold and drops the sentence that said a request wait files the start frame.

Piece What it does
Hold at the claim _claiming_stdout starts 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 _buffer in arrival order, so the start frame is first again, _agent_turn_pending() is True, the idle reader stays off and stream_unsolicited() reads the whole turn.
Bound _read_message _install_idle_reader binds a _read_message on the claude instance. While a hold is active it keeps each frame _starts_agent_turn accepts (the five activity kinds, or a request from the agent) and returns None to the reader, which then checks its own deadline. Every other frame reaches the reader as on main.
Room A frame that would not fit in _buffer (its maxlen, 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.
Kill or reset _cancel_idle_reader drops 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/update frames, in one list: _wait_for_response puts the requests it defers back when it returns, before the claim puts the held frames back, so holding only session/update frames would move a permission request behind chunks that arrived after it. As a result, wait_for_compaction and _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_notifications as on main, then reads the rest live. And stream_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 second readline() on the stream. The frames are in _buffer again 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 outside ACP_BACKENDS_AGENT_STARTED_TURNS binds neither the claim nor the _read_message wrapper, 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 real asyncio.StreamReader with a callback registered:

  • Each of _wait_for_response, wait_for_compaction and _drain_post_compaction_metadata, run after a hand-off on a chunk, reads a thought chunk, a session_info_update and a second chunk before the frame that ends it. The session_info_update is in _mcp_notifications as on main, the hand-off is still pending, and stream_unsolicited() then yields the start chunk first, the thought and the second chunk after it in order, and ends on the autonomous origin.
  • With a permission request between two chunks, each of the three readers leaves _buffer as chunk, request, chunk. test_a_request_wait_that_puts_the_first_frame_back_keeps_the_hand_off from feat(acp): read a claude turn the agent starts between prompts #18285 (the request as the start frame) passes unchanged.
  • Held frames go back ahead of frames the reader left unread in _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_message joins 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 only session/update frames, 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.py gains the _agent_turn_held row. test_acp_client_agent_started_turns.py passed 10 runs at -n0 and 3 at -n 4 --dist loadgroup --max-worker-restart=2 beside test_acp_client_shutdown_reset.py and test_acp_client_capabilities.py; it waits on observed state, never on a sleep. All test/test_acp_client_*.py, test_acp_copilot_backend.py, test_acp_harness_contract.py, test_claude_*.py and test_client_bindings.py pass (1819 tests). flake8, mypy src/kiro_crew, the black and subprocess-encoding gates, scripts/docs-lint.sh and scripts/check_harness_parity.py pass.

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 drive AcpClient over a real asyncio.StreamReader through 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_turn is what makes the #17566 fix visible)

Continues #25134 by @rinbn. A second commit on top holds the autonomous usage_update that closes the turn with the turn's other frames, so a request wait in the window no longer files it and stream_unsolicited() still ends the turn on it (GPT review finding on 0af9574). A response is never held. Pinned by test_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-id 7198a7a87c53 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 them
Sibling: src/kiro_crew/acp/client_turn_control.py:1020 -- not affected -- _read_steer_answers reads through that same claim
Sibling: 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_stdout enforces.

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; see the Licensing section of CONTRIBUTING.md.

@buluoray
buluoray requested review from a team and KiroCrewCaptain as code owners November 3, 2026 18:47
@buluoray
buluoray requested a review from bolichen97 November 3, 2026 18:47
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 7467b9d9b1b67e22e693de69a340b3b3d5b1d44c 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 added the readiness: checking Automated validation is still running label Nov 3, 2026
@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns block this: the hold sits once in the claude-only stdout claim, nothing registers on_agent_turn yet, and Kiro read paths stay as on main.

Notes

  • The description says the hold keeps only frames _starts_agent_turn accepts and that "every other frame reaches the reader as on main". The code and the spec also hold the autonomous usage_update that closes the turn (_ends_agent_started_turn(msg) with a method). That behaviour is missing from the description's table.
  • A long request wait during a big turn still files frames past _buffer's 100-frame room in _mcp_notifications. The turn then starts on its first frame but has a gap in the middle. If Phase 2 shows that gap, holding past maxlen in a separate list, rather than capping the hold at _buffer's room, would be the cleaner fix.

[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 .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 3, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 7467b9d9b1b67e22e693de69a340b3b3d5b1d44c — 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. 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 ships

Inventory (8 items) — 7 justified

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

  1. A request or compaction wait in the hand-off window puts the turn's frames back at the front of the buffer, so the turn starts on its first chunk and is announced once — justified
  2. A permission request read in that window keeps its place among the chunks, and compaction waits no longer drop it — justified
  3. The turn's closing autonomous usage_update is held with its frames — undeclared (the description's table lists only activity kinds and requests)
  4. Held frames no longer extend _wait_for_response's activity deadline — justified
  5. Frames that don't fit beside the held ones in _buffer fall back to the reader's normal handling — justified
  6. A kill or reset drops the held frames — justified
  7. New class attribute _agent_turn_held — justified
  8. The acp-client spec describes the hold and drops the old filing sentence — justified

[FIRST-PRINCIPLES-REVIEWED] 7467b9d

Description read

[DESCRIPTION-READ] ba7ef751e0ca5c261de5645a2ec4a20e89abe603cbbe4b2c5f6a6a5ec0798ff9

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 3, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 7467b9d

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

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

@github-actions

github-actions Bot commented Nov 3, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 7467b9d

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

@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 3, 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 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_stdout starts 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 _buffer with extendleft(reversed(held)), so they keep their arrival order.
  • The bound _read_message holds only frames _starts_agent_turn accepts, and returns None so the reader still checks its own deadline. It stops holding at _buffer.maxlen, so putting the frames back pushes nothing out.
  • _cancel_idle_reader clears _agent_turn_held, and the self._agent_turn_held is held check 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.

@bolichen97
bolichen97 enabled auto-merge (squash) November 3, 2026 19:17
@buluoray
buluoray force-pushed the fix/agent-turn-handoff-hold-22262 branch from 85f575d to f295fdb Compare November 3, 2026 21:13
@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 readiness: checking Automated validation is still running labels Nov 3, 2026
@github-actions

ghost commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

Security Scope Review -- 🔴 could not complete (fails closed)

No scope verdict for f295fdb25cd80f1be4ace425ec3c38da5644ae09 (the candidate stage failed). This lane fails CLOSED: an unmeasured tightening must not read as "nothing newly refused". See the job logs, then re-run -- or record /ai-review override scope f295fdb25cd80f1be4ace425ec3c38da5644ae09 <class>: <reason> if a human has judged the scope by hand.

@buluoray buluoray added claimed An automated fix is in progress and removed claimed An automated fix is in progress labels Nov 3, 2026
bolichen97
bolichen97 previously approved these changes Nov 3, 2026

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

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.

@buluoray
buluoray force-pushed the fix/agent-turn-handoff-hold-22262 branch from f295fdb to 0af9574 Compare November 3, 2026 23:23
@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 readiness: checking Automated validation is still running labels Nov 3, 2026
wenlin and others added 2 commits November 3, 2026 23:59
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
@buluoray
buluoray force-pushed the fix/agent-turn-handoff-hold-22262 branch from 0af9574 to 7467b9d Compare November 4, 2026 00:00

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

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.

@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: action required A blocking check or review needs attention labels Nov 4, 2026
@bolichen97
bolichen97 merged commit f3e0095 into main Nov 4, 2026
@bolichen97
bolichen97 deleted the fix/agent-turn-handoff-hold-22262 branch November 4, 2026 00:43
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 4, 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.

Claude backend: a request or compaction wait during an agent-started turn's hand-off files the turn's first frame as a notification

3 participants