Skip to content

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

Closed
rinbn wants to merge 1 commit into
kirodotdev:mainfrom
rinbn:fix/agent-turn-handoff-start-frame
Closed

rinbn wants to merge 1 commit into
kirodotdev:mainfrom
rinbn:fix/agent-turn-handoff-start-frame

Conversation

@rinbn

@rinbn rinbn commented Oct 28, 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 f5c41ed)

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.

Related Issues

Fixes #22262

Part of #17566

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.

@rinbn
rinbn requested review from a team and KiroCrewCaptain as code owners October 28, 2026 04:14
@rinbn
rinbn requested a review from dodgeblaster October 28, 2026 04:14
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention labels Oct 28, 2026
@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5, fork) — ✅ PASS

Premise-level review of 2d2f3211e0248be905f56c5b24e11210c5dce605 via the fork AI-review pipeline — 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 works at the stdout claim that all three readers share, the defect has a linked issue (#22262), and the replaced pin is named with that issue against it.

What this change ships

Inventory (7 items) — 6 justified

Intent: when Claude Code starts a turn on its own, keep that turn's first words and first tool call when a request or compaction wait reads stdout first. FIX.

  1. A request wait, compaction wait or metadata drain in the hand-off window holds the turn's frames and puts them back at the front of _buffer — justified
  2. A permission request in that window keeps its place among the turn's chunks — justified
  3. wait_for_compaction and _drain_post_compaction_metadata now keep an agent request they used to drop — rides along (declared; it follows from the shared hold list in item 2)
  4. A held frame no longer extends _wait_for_response's activity-based deadline — justified
  5. A frame that would not fit in _buffer gets the reader's normal handling, so nothing is pushed out — justified
  6. A kill or reset drops the held frames — justified
  7. The test_a_request_wait_that_reads_the_first_frame_ends_the_hand_off pin is replaced by the new keep-the-frames test, and the spec sentence about filing the start frame is replaced — justified

[FIRST-PRINCIPLES-REVIEWED] 2d2f321

Description read

[DESCRIPTION-READ] 67fac9f6e18fe6951624b751fe6bd662c9158399674c8d49c1cf81b5dc8965e6

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 Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5, fork) — ⏭️ skipped

Revision 2d2f3211e0248be905f56c5b24e11210c5dce605 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 Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 2d2f3211e0248be905f56c5b24e11210c5dce605 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS does not.

Design-Verdict: PASS

Nothing blocks: the hold sits in the one stdout claim every claude reader already goes through, so all readers inherit it. Nothing registers on_agent_turn yet, so the change can't reach users.

Notes

[DESIGN-REVIEWED] 2d2f321

Description read

[DESCRIPTION-READ] e8deee03073d5ed5a088ac6a65b6c82e69338ce242ed8b68e1b9e1fce540abc2

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 Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

Reviewed 2d2f3211e0248be905f56c5b24e11210c5dce605 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings. Nothing in src/ ever assigns AcpClient.on_agent_turn; it stays at its None default (client_class.py:121). With it unset, _maybe_start_idle_reader returns before it starts the idle reader. So _agent_turn_start is never set, no hand-off is ever pending, _agent_turn_held is never created, and none of the new hold, room-check or put-back paths can run in practice.

[OPUS-REVIEWED] 2d2f321

@github-actions

github-actions Bot commented Oct 28, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

Reviewed 2d2f3211e0248be905f56c5b24e11210c5dce605 via the fork AI-review pipeline; updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 2d2f321

@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 Oct 28, 2026
@iamwhatever

Copy link
Copy Markdown
Contributor

HOLD (missing review lane) at f5c41ed.

The code looks sound to me: the hold lives in the claude-only stdout claim, puts frames back in order, respects _buffer's room and is dropped on reset (client_transport.py#L519-L526). Opus, GPT and Design pass, and CI is green.

Blocker: the First Principles (fork) lane did not produce a verdict for this head (an earlier job step failed before the model call). Re-running that lane on this head and getting a PASS would clear this.

Non-blocking note: the Design lane's point that held frames no longer extend _wait_for_response's activity deadline (L846) matters only once Phase 2 registers on_agent_turn; that PR should pin it.

— crew-pr-reviewer (r133)

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 28, 2026
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 kirodotdev#22262
@rinbn
rinbn force-pushed the fix/agent-turn-handoff-start-frame branch from f5c41ed to 2d2f321 Compare October 28, 2026 18:54
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention 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 Oct 28, 2026
@rinbn

rinbn commented Oct 30, 2026

Copy link
Copy Markdown
Contributor Author

@iamwhatever, on r133:

Blocker: the First Principles (fork) lane did not produce a verdict for this head (an earlier job step failed before the model call). Re-running that lane on this head and getting a PASS would clear this.

The branch is rebased onto main (2808e9478c) at 2d2f3211e0. The only conflict was the kiro_crew.acp.types import list in test/test_acp_client_agent_started_turns.py: #25133 added METHOD_SESSION_STEERING and this PR adds EVENT_THINKING_CHUNK, and both stay. The code is otherwise unchanged from f5c41eddff. First Principles now reports PASS on 2d2f3211e0 (comment).

The CI and Code Review runs on this head were cancelled mid-run. Automated Rule Check and PR Hygiene stopped in actions/checkout, and Backend Lint & Type Check stopped during flake8, so Coverage Gate failed closed. I can't re-run workflows on the upstream repo. Could you re-run CI and Code Review?

Locally on this head: test_acp_client_agent_started_turns.py, test_client_bindings.py and test_claude_steering_request.py (551 passed), the 26 test_acp_client*.py files (1008 passed), flake8, isort, black and mypy on the changed files, and check_harness_parity.py.

@buluoray

buluoray commented Nov 3, 2026

Copy link
Copy Markdown
Contributor

🤖 Kiro Crew Auto-Pipeline [operator: buluoray#ce473fca]: there has been no activity here for a while, so a maintainer is picking this up so that it does not stall. The work continues in a new pull request that keeps your commits and credits you. Thank you for starting it.

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Nov 4, 2026
@rinbn

rinbn commented Nov 6, 2026

Copy link
Copy Markdown
Contributor Author

Superseded by #29269, which merged this patch.

@rinbn rinbn closed this Nov 6, 2026
@github-actions github-actions Bot removed the readiness: action required A blocking check or review needs attention label Nov 6, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

fork Pull request from a fork (external contributor) merge conflict Branch has merge conflicts with its base — author must resolve before merge

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