Skip to content

fix(acp): refuse steers into agent-started turns and ignore late answers - #25133

Merged
iamwhatever merged 1 commit into
kirodotdev:mainfrom
rinbn:fix/agent-turn-refuses-steers
Oct 28, 2026
Merged

iamwhatever merged 1 commit into
kirodotdev:mainfrom
rinbn:fix/agent-turn-refuses-steers

Conversation

@rinbn

@rinbn rinbn commented Oct 28, 2026

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: On the Claude Code backend, a turn the agent starts on its own takes no steer, and a steering answer that arrives during it no longer cuts it short.

stream_unsolicited() (#18285) reads a turn Claude Code started between prompts through the same _dispatch_events a prompt uses, under request id -1. That loop set _steering_turn_req to the id it reads, so steer() sent _session/steering into the agent-started turn, although RFC decision 3 says a user message sent during it queues behind it.

The turn also ended on any response it read. A steering answer whose steer had stopped waiting for it (its STEERING_ANSWER_WAIT_SECS wait spent, or its own turn over) was read as a plain response: the turn ended with a synthesized complete, and the rest of the agent's reply was handed off as a second agent-started turn. That happened whether the steer was sent into this turn or into the user turn before it.

Why it matters

Nothing registers on_agent_turn on main, so no agent-started turn is read and users see no change from this PR. The PR that wires agent-started turns into the dashboard makes both paths reachable. Without this fix, one background reply could show as two assistant messages with two notifications, or end with end_turn in the middle. A message typed during that turn would also be steered into it instead of queued, because the busy send button defaults to Steer.

Not a goal

What changed (motivation → approach → change)

Moment in an agent-started turn Before After
A Steer-mode send from the dashboard steer() writes _session/steering into the turn steer() returns False, and the dashboard queues the text as the next prompt
The answer to a steer that stopped waiting arrives mid-turn the turn ends with a synthesized complete; the rest of the reply becomes a second agent-started turn the answer passes as a stray response, as in a user turn; the turn ends on its origin usage_update
A user turn's steer unchanged unchanged

Symptom: one agent-started reply split in two, and steers sent where the RFC queues. Root cause: _dispatch_events treated the agent-started read as a prompt turn that takes steers, and _read_turn (the claude-only wrapper of _prompt_loop) could not tell a steering answer from a prompt's late response. Change:

  • _dispatch_events leaves _steering_turn_req unset when it reads request id -1, as it already does for a command turn. _steer_via_steering_request refuses a steer when no turn is named, so steer() returns False and every caller takes its queue path.
  • The client keeps steering request ids. _steer_via_steering_request adds the id to _unanswered_steering_ids() in its on_id callback, before the frame is written, and removes it in its finally once its own wait read the answer. _read_turn removes an id when it reads that id's answer and passes the frame on, and under -1 such a frame ends nothing. A steer still waiting never reaches this rule, because _prompt_loop hands it its answer first. The rule uses the id, not the time it was sent, so it covers a steer sent before the turn began and one sent during it alike. Request ids only grow on a client, so a kept id can never match a later request's answer. An id outlives its answer only if the process dies before answering.

Everything else #18285 set for the turn's end stays: the autonomous-origin usage_update, process death, the stale-turn gate, the timeout, a prompt's late tail, and a response to a request sent after the turn began staying at the front of _buffer.

docs/system-specs/modules/acp-client.md ("Idle reader and agent-started turns") states both rules. RFC §6, accepted on main, said a message sent during the turn "takes the existing queued path, because slot.running is set". That holds for Queue mode only. The busy send button defaults to Steer, and chat_send.py sends a Steer-mode send down the steer path whenever slot.turn_running, reaching the queue only when the steer is unavailable or refused. With this change the client refuses it, so decision 3's queue holds. §6 gains one sentence saying so.

Overlap with #25000. #25000 holds a claude steer while a tool call of the turn is open and sends it once none is. It keeps the aimed_at is None refusal in _steer_via_steering_request, and _send_held_steers drops a held steer once _steering_turn_req no longer names its turn, so after this change neither the direct nor the held path steers into an agent-started turn. #25000 moves the request-and-answer code into _send_steering_request. The three lines here that keep the id move with it, which covers held steers too. Both PRs edit the same lines of _dispatch_events and _steer_via_steering_request, so whichever lands second needs a mechanical rebase.

Open question. Option B, taking steers into an agent-started turn so the send button's Steer mode applies there as well, was not chosen. How claude-agent-acp handles _session/steering inside an autonomous cycle has not been probed: Phase 0 tested only a session/prompt sent during one. #22801 shows that a steer sent during a running tool can end a turn early. B can follow a probe, and the id rule here already keeps a late answer from ending the turn under either option.

Backwards compatibility

Compatible: nothing registers on_agent_turn, so no agent-started turn is read on main and neither new rule runs. A user turn's steer is sent, answered and reported as before. A Kiro or other non-claude client never reaches _read_turn or the claude steering path (harness-parity H13). The one shared line is the _steering_turn_req assignment in _dispatch_events, which differs only for request id -1, and only stream_unsolicited() reads under that id.

steer() now answers False during an agent-started read. Each caller that can reach a claude client already takes its queue path on False:

Reader: src/kiro_crew/dashboard/chat_delivery.py:steer_into_running_turn -- chat -- False returns STEER_UNAVAILABLE and chat_send.py queues the text; test_an_agent_started_turn_takes_no_steer_and_the_next_user_turn_does
Reader: src/kiro_crew/providers/acp_turns.py:steer -- subagent -- refuses claude before calling the client (steer_needs_loss_recovery), unchanged
Reader: src/kiro_crew/dashboard/chat_turn/deny_chokepoints.py:_steer_policy_notice -- chat -- gated on supports_refusal_steer, False for claude, unchanged
Reader: src/kiro_crew/dashboard/chat_turn/deny_chokepoints.py:_steer_repeat_loop_notice -- chat -- same gate, unchanged
Reader: src/kiro_crew/dashboard/steer_retract.py:_send_again -- chat -- a False leaves the steer pending for the turn's teardown to requeue, unchanged

Tests

test/test_acp_client_agent_started_turns.py, over the file's real asyncio.StreamReader with on_agent_turn registered:

  • test_an_agent_started_turn_takes_no_steer_and_the_next_user_turn_does: during an agent-started read steer() returns False and writes nothing; in the next user turn a steer is written, answered injected, returns True and is reported consumed at end_turn.
  • test_a_late_steering_answer_does_not_end_the_agent_started_turn (timeout, turn_end): a steer sent in a user turn stops waiting, once because its wait ran out (STEERING_ANSWER_WAIT_SECS patched to 0, no sleep) and once because its turn ended first. Its answer arrives in the middle of the next agent-started turn, which still yields the rest of the reply, ends once on its origin usage_update with end_turn, and hands off once. The kept id is gone afterwards.

The existing response-rule tests (test_the_tail_of_a_prompt_whose_turn_ended_early_ends_on_its_response, test_a_response_to_a_request_sent_during_the_turn_is_left_for_its_reader) and test/test_claude_steering_request.py pass unchanged. test/test_client_bindings.py adds _unanswered_steering_ids and its field to the frozen inventory.

Proof: PROVEN test/test_acp_client_agent_started_turns.py::test_an_agent_started_turn_takes_no_steer_and_the_next_user_turn_does, test/test_acp_client_agent_started_turns.py::test_a_late_steering_answer_does_not_end_the_agent_started_turn[timeout-injected], test/test_acp_client_agent_started_turns.py::test_a_late_steering_answer_does_not_end_the_agent_started_turn[turn_end-promptRequired], test/test_client_bindings.py::test_the_member_set_is_the_frozen_inventory (head ed9ba2d)

Determinism: test_acp_client_agent_started_turns.py passed 10 of 10 runs at -n0, and with test_claude_steering_request.py 5 of 5 at -n 4 --dist loadgroup --max-worker-restart=2. The new tests wait on observed state or the task they started (async_wait_until, await_until), never on a sleep.

Manual verification

N/A: nothing registers on_agent_turn on main, so no agent-started turn can be read live. The unit tests drive the read over a real StreamReader. Local gates: black, isort and flake8 on the changed files, mypy src/kiro_crew (3,678 files, no issues), scripts/check_harness_parity.py, scripts/docs-lint.sh, and the backend related set scripts/run_scoped_tests.py selects (12 files, 957 passed, 10 skipped).

Related Issues

Fixes #22264
Part of #17566

Sibling sweep

Swept: git grep -n "_steering_turn_req|METHOD_SESSION_STEERING|_ends_agent_started_turn" -- src/
Sibling: src/kiro_crew/acp/client_turn.py -- changed here
Sibling: src/kiro_crew/acp/client_turn_control.py -- changed here
Sibling: src/kiro_crew/acp/client_transport.py -- changed here
Sibling: src/kiro_crew/acp/session_handle_steering.py -- not affected -- the shared-runtime handle drains between-turn frames and reads no agent-started turn

Pattern harvest

Not generalizable: the defect is one read path that reused a prompt turn's steer and response rules for a turn with no prompt; the fix names that turn's rules where it reads.

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

Contributed under the project's Apache-2.0 license.

stream_unsolicited() reads a turn the agent started through
_dispatch_events, which set _steering_turn_req to that turn's request
id. steer() then sent _session/steering into a turn where RFC decision
3 says a user message queues. The turn also ended on any response it
read, so a steering answer that arrived after its steer stopped
waiting ended the turn with a synthesized complete, and the rest of
the reply was handed off as a second agent-started turn.

_dispatch_events now leaves _steering_turn_req unset for the
agent-started request id, so steer() returns False and the caller
queues the text. The client keeps the id of each steering request
from before it is written until its answer is read, and _read_turn
passes an answer with a kept id on as a stray response, so it ends no
turn whenever its steer was sent.
@rinbn
rinbn requested review from a team and KiroCrewCaptain as code owners October 28, 2026 04:07
@rinbn
rinbn requested a review from dodgeblaster October 28, 2026 04:07
@github-actions github-actions Bot added fork Pull request from a fork (external contributor) readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running and removed readiness: action required A blocking check or review needs attention labels Oct 28, 2026
@github-actions

Copy link
Copy Markdown
Contributor

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

Revision ed9ba2d11cc6dc68f6de19199ab38af46c58641c touches no user-facing surface (no changes under website/ or committed screenshots), so the UX review was skipped. Does not block merge.

@github-actions

Copy link
Copy Markdown
Contributor

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

Premise-level review of ed9ba2d11cc6dc68f6de19199ab38af46c58641c 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

Both items fix the cause in the agent-started read path, and accepted RFC decision 3 already covers the refusal. The path is dormant on main, so today the fix protects code that nothing calls yet.

Notes

  • Item 2 — inherited: "Nothing registers on_agent_turn on main, so … users see no change from this PR". If this PR ships nothing, nobody notices until the wiring PR lands. Subtraction: none needed here. The only thing that makes the item worth having is that the wiring PR lands; the item is reversible.

What this change ships

Inventory (4 items) — 3 justified

Intent: a background reply from Claude Code should stay one message, and a message typed during it should queue behind it rather than steer into it. FIX.

  1. A Steer-mode send during an agent-started turn now falls back to the queue — justified
  2. A late steering answer no longer splits an agent-started reply in two — inherited, no reader on main
  3. The client keeps the id of each steering request until its answer is read (_unanswered_steering_ids) — justified
  4. RFC §6 and the acp-client spec say a Steer-mode send falls back to the queue — justified

[FIRST-PRINCIPLES-REVIEWED] ed9ba2d

Description read

[DESCRIPTION-READ] d62268dea83a274c1494e6bc155b6b60d208d80604dcd5f8ca54d37e0a12acdd

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

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of ed9ba2d11cc6dc68f6de19199ab38af46c58641c 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 fix keys on the request id, so it covers a late answer whether the steer was sent before or during the turn. No agent-started turn is read on main, so the change is reversible.

Notes

  • An id stays in _unanswered_steering_id_set until its answer is read. It is cleared only by an answer that _read_turn reads (any claude turn) or by the steer's own finally. If fix(acp): send a claude steer once its running tool call finishes #25000 lands first, keep both clear-points when the code moves into _send_steering_request, or held steers will leak ids.

[DESIGN-REVIEWED] ed9ba2d

Description read

[DESCRIPTION-READ] 64c10d37be6d20718466f1187400adbb921202d340a3cb2eba56f1e833405770

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

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] ed9ba2d

@github-actions

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] ed9ba2d

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

@iamwhatever iamwhatever 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.

APPROVE at ed9ba2d.

The agent-started read no longer names a steering turn, so steer() returns False and callers queue; a late steering answer is recognised by its request id and passed on without ending the turn. Request ids never reset on a client (client_class.py#L411), so a kept id cannot collide. All lanes pass and CI is green.

AI findings judged non-blocking

  • Design: ids must keep both clear-points if #25000 lands first. guidance for a future rebase of another PR; this head clears ids in the steer's finally and in _read_turn. code
  • First Principles: item 2 is inherited: no reader on main until the wiring PR lands. no harm; the path is dormant and reversible. code
  • Description open question: option B (steers into agent-started turns) not chosen. an optional rejected alternative, not a promised follow-up; refusal matches RFC decision 3. code

— crew-pr-reviewer (r133)

@iamwhatever
iamwhatever merged commit eac6776 into kirodotdev:main Oct 28, 2026
105 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Oct 28, 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)

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Claude backend: a steer or a late steering answer can end an agent-started turn early

2 participants