Skip to content

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

Open
rinbn wants to merge 1 commit into
kirodotdev:mainfrom
rinbn:fix/agent-turn-hold-wait-and-silence
Open

rinbn wants to merge 1 commit into
kirodotdev:mainfrom
rinbn:fix/agent-turn-hold-wait-and-silence

Conversation

@rinbn

@rinbn rinbn commented Nov 5, 2026

Copy link
Copy Markdown
Contributor

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

@rinbn
rinbn requested review from a team and KiroCrewCaptain as code owners November 5, 2026 22:23
@rinbn
rinbn requested a review from bolichen97 November 5, 2026 22:23
@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 Nov 5, 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.

The code change looks good to me. It adds no regex, and the behavior change is neutral on security. One CI blocker remains: Flake Pattern Ratchet is red on 700ba73. It reports:

test/test_acp_client_agent_started_turns.py: K19-short-literal-duration-arg 64 > 50

The new tests pass non-zero literals as duration-named arguments, for example timeout=5, timeout=30, client._dispatch_events(5, 0.5), and patch(..._STALE_TURN_TIMEOUT, 0.05) / patch(..._READ_TIMEOUT, 0.05). The Determinism contract (docs/system-specs/common/testing-conventions.md, "Production deadlines are not test boundaries") allows only these:

  • FALLBACK_TIMEOUT_SECS from kiro_crew.testing.wait (or another kiro_crew.testing name, such as the default_timeout() you already use at the end of the file) for the happy-path safety nets;
  • literal 0 for the expired path;
  • an autouse _floor_monkeypatch fixture for the patched production constants.

Where a short value is deliberate, add # flake-ok: <reason> on that line instead. Once the ratchet is green I'll approve.

@rinbn
rinbn force-pushed the fix/agent-turn-hold-wait-and-silence branch from 700ba73 to ee1dc5e Compare November 6, 2026 19:06
@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 6, 2026
@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

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

Design-Verdict: PASS

No design-level concerns: the fix is limited to the agent-started read path, uses the existing stale-turn gate and liveness oracle, and removes nothing.

Notes

  • stream_unsolicited() waits on _agent_turn_hold_end with no deadline of its own. That is safe only while every claimed reader keeps a bounded timeout and sets the event in finally. Keep that invariant in mind when you add a new _claiming_stdout site.

[DESIGN-REVIEWED] ee1dc5e

Description read

[DESCRIPTION-READ] d35b28db1b6c4172924ce85133c06f410fa7f8586cd701dd87002a1ca8649a98

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 6, 2026

Copy link
Copy Markdown
Contributor

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

Premise-level review of ee1dc5eae8b19efd787fee9783e924d14421f571 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. Each item fixes a defect the description reproduces, and a test that fails on base shows it. The stale-gate arming changes only the agent-started read path.

What this change ships

Inventory (6 items) — 6 justified

Intent: On the claude backend, a reply Claude Code starts on its own should still show as its own message when a request wait overlaps its arrival, and a silent agent cycle should stop holding the chat for hours. This is a FIX.

  1. An agent reply that arrives during a request wait (a config push or compaction) now shows as its own agent-started message, not under the user's next message — justified
  2. A dashboard turn opened during that wait waits for the held frames, and a kill or reset wakes it with nothing to read — justified
  3. A silent agent-started cycle (a thought, a plan or a permission request, then nothing) now ends after about 90 s on the stale-turn gate instead of the 4 h prompt timeout — justified
  4. New client method has_pending_agent_turn(), read by the provider's agent_turn_pending() probe (1 consumer, singular form) — justified
  5. New internal field _agent_turn_hold_end, an event set when the held frames go back or on kill/reset — justified
  6. acp-client.md sections "Idle reader and agent-started turns" and "Stale-turn gate" updated in the same commit — justified

[FIRST-PRINCIPLES-REVIEWED] ee1dc5e

Description read

[DESCRIPTION-READ] 3630a6642838f97126ecf1d63572468ae9679b52ac9e4388de37bd46881dab59

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 6, 2026

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] ee1dc5e

@github-actions

github-actions Bot commented Nov 6, 2026

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ee1dc5e

@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 head ee1dc5e. The flake ratchet findings are addressed: the safety nets use FALLBACK_TIMEOUT_SECS or the default wait, the expired path patches _STALE_TURN_TIMEOUT to 0 through a _floor_monkeypatch fixture, and the one short poll interval carries # flake-ok.

The red lanes come from the old base, not this change: Backend Tests (3.12, 2) fails the test_security_gate_liveness.py line budget, and Real Adapter Contract Tests fails the codex sandbox test that #31758 fixed on main. Both pass on PRs cut from current main. Could you rebase onto main? The push will dismiss this approval, and I will re-approve once it is green.

@bolichen97
bolichen97 enabled auto-merge (squash) November 8, 2026 19:53
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 kirodotdev#17566
auto-merge was automatically disabled November 9, 2026 17:54

Head branch was pushed to by a user without write access

@rinbn
rinbn force-pushed the fix/agent-turn-hold-wait-and-silence branch from ee1dc5e to 8ed8287 Compare November 9, 2026 17:54
@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
@iamwhatever

Copy link
Copy Markdown
Contributor

Thank you @rinbn for this fix and the careful tests and live runs. Since this branch had gone stale against main, it has been carried forward in #38313, rebased onto current main. That PR keeps your commit authorship and a Co-authored-by trailer, so the credit stays yours. The only changes are two conflict resolutions that keep main's newer shared-process (AcpSessionProvider) branch and backend-aware _starts_agent_turn call; your tests are unchanged. This PR is left open for the owner to decide on.

iamwhatever pushed a commit that referenced this pull request Nov 17, 2026
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>
KiroCrewCaptain pushed a commit that referenced this pull request Nov 17, 2026
…38313)

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>

This branch has not been deployed

No deployments
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 readiness: action required A blocking check or review needs attention

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants