Skip to content

fix(acp): keep an agent-started turn readable through a request wait - #38313

Merged
KiroCrewCaptain merged 1 commit into
mainfrom
fix/agent-turn-hold-wait-takeover
Nov 17, 2026
Merged

KiroCrewCaptain merged 1 commit into
mainfrom
fix/agent-turn-hold-wait-takeover

Conversation

@iamwhatever

@iamwhatever iamwhatever commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

Supersedes #30797

Takeover of #30797 by @rinbn, which was approved but went stale against main. The commit keeps @rinbn as its author and carries a Co-authored-by: rinbn trailer; the design, code, tests and live runs below are theirs. Thank you, @rinbn.

What changed vs #30797

Rebased onto current main. Two conflicts, each resolved by keeping both sides:

One test needed adapting: test_a_kill_or_reset_wakes_a_stream_waiting_for_the_held_frames[_kill_process] now patches platform_compat.terminate_windows_asyncio_tree, because main's Windows kill path drains the real process tree and raised OSError: Cannot retain the original Windows runtime process handle on the test's mock process (New-test stability, windows-latest). The test's assertions are unchanged. #37922 (merged) touched stream_unsolicited()'s neighbourhood in client_turn.py for a different path (a turn whose prompt was never sent) and merged cleanly with this change.

Local gates on this head: the 9 related test files (1,647 tests) pass at -n 4; black, isort, flake8, mypy over src/kiro_crew/, check_harness_parity.py, check_black_formatting.py, check_comment_history.py, check_file_line_cap.py, docs-lint.sh, the flake-pattern ratchet and the repo semgrep rules are clean.


Original description from #30797 follows.

Problem / Motivation

Goal: On the claude backend, a reply that Claude Code sends on its own between dashboard turns still shows up as its own message when a request wait (such as a live config push) is running as it arrives, and a cycle of the agent's that goes quiet without a closing frame no longer holds the chat until the prompt timeout.

#30092 shows a turn Claude Code starts on its own as its own reply. Two gaps remain in the transport underneath it.

A request wait in the hand-off window drops the turn. When the idle reader hands a turn off, the turn's first frame waits in the client's buffer. A request wait can claim stdout before the turn reads that frame, for example a live effort or model push, or a compaction wait. #29269 makes that wait hold the turn's frames and put them back when it returns. While they are held, AcpProvider.agent_turn_pending() reads False. So the dashboard turn started for the agent ends before it opens, because its dispatch gate sees nothing pending, or stream_unsolicited() returns at once. When the frames go back, nothing reads them: the idle reader does not restart while a hand-off is pending. The reply waits for the user's next message and shows under it, which is #17566's symptom.

A silent agent-started cycle holds the slot. claude-agent-acp sends the closing usage_update only when an assistant message set the cycle's usage. Suppose a cycle sends a thought, a plan or a permission request and then nothing. No response is coming either, and the stale-turn gate arms only after text. So the read stays open until the prompt timeout (4 h by default), and the chat slot with it, so every message sent meanwhile queues behind it.

Why it matters

This affects anyone on the claude backend with agent-started turns on, which is the default. The first gap needs a request wait to overlap the moment the agent's turn arrives, which a settings change or a compaction can cause. When it happens, the reply is misattributed exactly as before #30092. The second gap is rare. When it hits, the chat stops answering for hours and shows no error.

Not a goal

  • Other backends. kiro and the other AcpClient backends keep main's behaviour (harness-parity H13): the changed reads run only on a client the claude adapter installed the idle reader on, and a user turn's stale-turn gate is unchanged.
  • A cycle that goes quiet with a tool call open. The tool-stall watchdog already ends that read, as on a user turn.
  • The "started by the agent" label and the agent turn's transcript group (a separate follow-up).
  • Channel sessions on the messaging driver, cron job sessions and sub-agents, which register no watch.

What changed (motivation → approach → change)

Design record: docs/request-for-change/rfc-agent-started-turns.md (status partial).

  • The pending probe counts held frames. The new AcpClient.has_pending_agent_turn() is True while the turn's first frame is in _buffer, or in the list a claimed reader holds (_claiming_stdout). AcpProvider.agent_turn_pending() reads it, so in that window the dashboard's claim (_on_agent_turn) still starts the turn and its dispatch gate still opens it. _agent_turn_pending() keeps its buffer-only meaning for the idle reader and the claim.
  • The stream waits for the hold to end. A claim that starts holding creates _agent_turn_hold_end (an asyncio.Event) and sets it when it puts the frames back. _cancel_idle_reader (kill, reset) sets it too. stream_unsolicited() waits on it before its checks, so it never reads beside the holder. After a kill or reset it finds nothing pending and yields nothing.
  • An agent-started read arms the stale-turn gate from its first activity frame. In _read_turn, under request id -1, each frame from the first activity frame on sets _stale_eligible when no tool call is open. A silent cycle then ends on the existing gate: 90 s, deferred while the liveness oracle reads the backend as working, then a synthetic end_turn, the same end a stale user turn gets. An open tool call leaves the tool-stall watchdog in charge. A user turn never reaches this branch.
  • Where. acp/client_transport.py, acp/client_turn.py and acp/client_class.py hold the client half, and providers/acp_turns.py holds the provider probe. acp-client.md ("Idle reader and agent-started turns", "Stale-turn gate") is updated.

Backwards compatibility

Compatible: the new probe and event are internal to the claude client, and the only read that changes is the one under the agent-started request id, which only a claude session makes.

Removes nothing: the change adds a client method and an internal field and arms an existing gate earlier on one read path; nothing that main accepts is rejected, renamed or removed.

Tests

test/test_acp_client_agent_started_turns.py:

  • test_stream_unsolicited_waits_for_a_reader_that_holds_the_turns_frames, for each of the request wait, wait_for_compaction and _drain_post_compaction_metadata: the stream blocks while the frames are held, then reads every one of them in order, the first included.
  • test_a_turn_counts_as_pending_while_a_reader_holds_its_first_frame: has_pending_agent_turn() is True during and after the hold, and False once a prompt has read the frames.
  • test_a_kill_or_reset_wakes_a_stream_waiting_for_the_held_frames (reset, kill): the blocked stream ends empty and writes nothing.
  • test_an_agent_turn_that_goes_silent_before_any_text_ends_on_the_stale_turn_gate (a thought, a plan, an answered permission request): the read ends on the patched stale-turn timeout with a synthetic completion. On main it was still open when the 5 s wait expired, against a 30 s stand-in for the prompt timeout.
  • test_a_user_turn_that_goes_silent_after_thinking_is_not_ended_by_the_stale_turn_gate: a user turn is unchanged.

test/test_dashboard_agent_started_turn.py, test_a_request_wait_in_the_hand_off_window_does_not_leave_the_turn_empty: main's _run_chat(_agent_started=True) runs through the provider seam over a real AcpClient and StreamReader while a request wait holds the frames. The reply lands as an agent-started row. On main the turn ended with no row before the wait's answer arrived.

test/test_client_bindings.py pins the new member and field.

Proof: PROVEN test/test_acp_client_agent_started_turns.py::test_an_agent_turn_that_goes_silent_before_any_text_ends_on_the_stale_turn_gate[thought], test/test_acp_client_agent_started_turns.py::test_an_agent_turn_that_goes_silent_before_any_text_ends_on_the_stale_turn_gate[plan], test/test_acp_client_agent_started_turns.py::test_an_agent_turn_that_goes_silent_before_any_text_ends_on_the_stale_turn_gate[permission], test/test_client_bindings.py::test_the_member_set_is_the_frozen_inventory, test/test_client_bindings.py::test_each_member_keeps_its_kind_shape_and_owner[_agent_turn_hold_end] (head 700ba73)

Determinism: the 11 new cases passed 15 runs at -n 4 --dist loadgroup --max-worker-restart=2 and 10 runs at -n0. Timing constants are patched and every await is bounded by kiro_crew.testing.wait; there are no sleeps.

Local gates: the 21 test files that run_scoped_tests.related_targets picks for this diff, plus test_acp_client_stale_turn.py, are green at -n 4 (1,658 tests). black (touched files only), isort, flake8, check_harness_parity.py, check_black_formatting.py, check_subprocess_encoding.py, check_file_line_cap.py, check_comment_history.py, check_brand_name.py and docs-lint.sh are clean. mypy reports two errors in apps/routes_registry.py, which this PR does not touch: was_installed is used there but never bound, on main as well.

Manual verification

Live runs against claude-agent-acp 0.100.0 with no gateway and no browser. A driver built the dashboard state from the test helpers with a real SessionManager and the configured provider factory. It ran _run_chat for the user turns and left the agent-started turn to the watch. Each run used a fresh data home. Times are seconds after the first prompt.

Run User turn ends Agent's own turn Follow-up answer
main 9f5c866, switch on, sleep 15; echo probe-done in the background 11.0 s its reply "…printed probe-done." lands at 29.3 s as its own row with meta.origin, with its own chat_done holds only its own text
main, switch off 11.8 s none in 60 s "The command finished … printed probe-done.No, the only background task…": the late result is glued to the front
main, switch on, the cycle runs touch after the background command 11.2 s a permission card opens at 27.3 s with no user turn running; approved; the reply lands at 29.6 s as its own row holds only its own text
this branch, switch on, background command 13.0 s reply at 29.2 s as its own row, with its own chat_done holds only its own text
this branch, switch on, touch permission 17.0 s card at 29.7 s with no user turn running; approved; reply at 32.3 s as its own row holds only its own text

The request-wait race and the silent cycle were not reproduced live: both need the adapter to act at a chosen moment, so the tests above drive them.

A background subagent's permission request could not be placed between turns with this adapter version. When asked to start a background subagent, the adapter kept the user's prompt open until the subagent finished, so its ask and its report arrived inside that user turn. A Workflow agent was not tried.

Related Issues

Part of #17566

Builds on #30092 (agent-started turns on the dashboard) and #29269 (a request wait keeps the turn's frames).

Sibling sweep

Swept: git grep -n "_agent_turn_pending()" -- src/ for readers that ask whether a hand-off is pending, and git grep -n "_stale_eligible = " -- src/kiro_crew/acp/ for the stale-turn arming sites.
Sibling: src/kiro_crew/providers/acp_turns.py -- changed here
Sibling: src/kiro_crew/acp/client_turn.py -- changed here
Sibling: src/kiro_crew/acp/client_transport.py -- not affected -- the claim and the idle reader's restart check need the buffer-only meaning: a held frame is already being kept for the turn
Sibling: src/kiro_crew/acp/session_handle_turn.py -- not affected -- the shared-runtime handle never reads an agent-started turn, only a direct claude client does

Pattern harvest

Not generalizable: both defects come from the agent-started read having no response to wait for, which no other read path in the client shares.

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

@iamwhatever
iamwhatever requested review from a team and KiroCrewCaptain as code owners November 17, 2026 08:18
@github-actions github-actions Bot added the readiness: checking Automated validation is still running label Nov 17, 2026
@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

UX Review (Opus 5.5) — ⏭️ skipped

Revision 6f96241c73b95308c70ff72c2d22559c8c05f006 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 17, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Opus 5.5) — ✅ PASS

Premise-level review of 6f96241c73b95308c70ff72c2d22559c8c05f006 — 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

This is a fix for two named transport defects. It changes no default, and each item it adds has exactly one caller.

What this change ships

Inventory (5 items) — 5 justified

Intent: On the claude backend, a reply the agent sends on its own should show as its own message even when a request wait overlaps it, and a cycle that goes silent should not hold the chat for hours. This is a FIX.

  1. A dashboard turn started while a request wait holds the agent turn's frames now opens instead of ending empty — justified
  2. The agent-started read waits until the holding reader puts the frames back, then reads them in order — justified
  3. A kill or reset wakes that waiting read, which then ends empty — justified
  4. An agent-started cycle that goes quiet after a thought, plan or permission request ends after about 90 s of silence instead of holding the chat until the prompt timeout (4 h by default) — justified
  5. The acp-client spec is updated to describe the new probe, the wait and when the stale-turn gate arms — justified

[FIRST-PRINCIPLES-REVIEWED] 6f96241

Description read

[DESCRIPTION-READ] 340ab274c2d2590e344d5d04994474925840f736440f0aa29573ae42ac94d5fb

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns: the provider probe counts the held frames, the stream waits on the hold's end event, and only the agent-started read path arms the existing stale-turn gate earlier.

Notes

  • On the agent-started read, the gate now arms from the first activity frame. If a permission request arrives with no tool call open and the user leaves it unanswered, the oracle-gated 90 s reap could end that turn. A test pinning that case would show it keeps the read open.

[DESIGN-REVIEWED] 6f96241

Description read

[DESCRIPTION-READ] 2f702f6c886b4a48daf6867853ff5e0b140aefa99e282d9b221697902e01f333

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 6f96241

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

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

@github-actions

github-actions Bot commented Nov 17, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review — ✅ no blocking findings

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

This comment is updated in place on each push.

Review details

No findings.
[GPT-REVIEWED] 6f96241

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

On the claude backend, a request wait that runs while a turn the agent
started waits to be read (a live config push, a compaction wait) holds
that turn's frames until it returns. The provider's pending probe read
False meanwhile, so the dashboard turn started for the agent ended
before it opened, or stream_unsolicited() returned at once. The frames
went back to the buffer with no reader left, and the reply waited for
the user's next message again.

has_pending_agent_turn() counts the held first frame, and the provider's
agent_turn_pending() reads it. stream_unsolicited() waits until the
holding reader has put the frames back, or a kill or reset has dropped
them, before it checks.

An agent-started cycle that goes quiet after a thought, a plan or an
answered permission request, with no closing usage_update, held the
read and its chat slot until the prompt timeout: the stale-turn gate
armed only after text. Under the agent-started request id it now arms
from the turn's first activity frame. An open tool call still leaves the
tool-stall watchdog in charge, and user turns are unchanged.

Refs #17566

Ported onto main from #30797; the provider probe keeps main's
AcpSessionProvider branch, and _read_turn keeps main's backend-aware
_starts_agent_turn(msg, self.backend).

Co-authored-by: rinbn <34065934+rinbn@users.noreply.github.com>
@iamwhatever
iamwhatever force-pushed the fix/agent-turn-hold-wait-takeover branch from 64788e4 to 6f96241 Compare November 17, 2026 08:45
@github-actions github-actions Bot added readiness: passed Eligible automated validation passed for the current revision and removed readiness: checking Automated validation is still running labels Nov 17, 2026
@KiroCrewCaptain
KiroCrewCaptain enabled auto-merge (squash) November 17, 2026 10:27

@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 6f96241 the review checked four things:

  • The _agent_turn_hold_end Event is set in the finally of _claiming_stdout and in _cancel_idle_reader, so a kill, reset or cancel cannot leave stream_unsolicited waiting.
  • has_pending_agent_turn() lets the dashboard gate see the held start frame. The idle reader and the claim keep the buffer-only _agent_turn_pending().
  • The new stale-gate arming runs only on the agent-started read id, so user turns and the Kiro path do not change.
  • Each new test fails with its fix reverted, and every one waits on a signal, not a sleep.

Well done: the takeover matches #30797 except for the two documented conflict resolutions, and the stale-gate change reuses the existing possibly_open idiom and the 90 s oracle reap instead of adding a new timer.

  • Optional: the Proof: PROVEN line names head 700ba73, which is not this head. Re-running prove.py on 6f96241 would also list the hand-off tests.
  • Optional: after a permission ask is answered more than 90 s later, _read_turn re-arms _stale_eligible and the idle clock does not subtract the park time. One fix is to refresh last_data_ts when the dispatcher resumes from a permission or elicitation park.
  • Optional: no test covers a cycle that opens a tool call and then goes silent under _stale_gate_expired, so nothing pins the not possibly_open guard on the new arming line. Once this merges, #30797 can be closed as replaced.

@KiroCrewCaptain
KiroCrewCaptain merged commit 70b3be5 into main Nov 17, 2026
104 of 110 checks passed
@KiroCrewCaptain
KiroCrewCaptain deleted the fix/agent-turn-hold-wait-takeover branch November 17, 2026 10:28
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 17, 2026
KiroCrewCaptain pushed a commit that referenced this pull request Nov 19, 2026
…8853)

On a claude chat served by the shared runtime, a request wait (a live
model or effort change) that starts while a turn the agent began waits
to be read takes that turn's frames into its own buffer until its answer
arrives. The dashboard turn opened for the agent then found an empty
queue and ended at once, which freed the chat: a message sent before the
wait returned started a prompt, the wait put the frames back while that
prompt read, and the agent's reply showed at the front of the
follow-up's answer.

The wait now marks when it holds the agent turn's first frame, and
stream_unsolicited() waits until the wait has put it back before it
reads, as the per-chat client does since #38313. The turn then reads the
reply as its own message, and a message sent meanwhile queues behind it.

Closes #37904
iamwhatever pushed a commit to rinbn/KiroCrew that referenced this pull request Nov 19, 2026
kirodotdev#38313's request-wait test predates turn_start; the reply is that turn's
only row, so it carries the opener origin.
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