Skip to content

feat(acp): steer claude turns through _session/steering - #14531

Closed
justin-robinson wants to merge 1 commit into
kirodotdev:mainfrom
justin-robinson:feat/claude-steer-session-steering
Closed

justin-robinson wants to merge 1 commit into
kirodotdev:mainfrom
justin-robinson:feat/claude-steer-session-steering

Conversation

@justin-robinson

@justin-robinson justin-robinson commented Sep 27, 2026 •

Copy link
Copy Markdown

Problem / Motivation

Goal: On a claude session, a steer sent while a turn is running reaches that turn, instead of silently waiting in the queue.

On the claude backend the busy composer offers Steer, but every mid-turn message is queued and runs as a separate turn after the current one ends. ACP_BACKENDS_STEER is {kiro, KAS}, so steer_into_running_turn returns STEER_UNAVAILABLE for claude and the message falls back to the queue. Nothing in the UI says the steer was downgraded.

Why it matters

A user correcting a claude turn mid-flight ("stop, you're editing the wrong file") has to wait for the wrong work to finish, or press Stop and resend, which throws away the in-flight work. That's exactly what Steer is meant to avoid.

Not a goal

What changed (motivation → approach → change)

Root cause. claude-agent-acp has no _session/steer. It does implement the ACP steering request _session/steering and advertises it as initialize._meta.steering.supported. That's the same request codex speaks, and #14115 built the model for it: ACP_BACKENDS_STEERING_REQUEST, supports_refusal_steer, steer_needs_loss_recovery, and at-least-once settlement. It wired that model only into AcpSessionHandle, but claude runs on the legacy AcpClient, so claude never reached it.

Approach. Put claude into #14115's model rather than beside it. This revision replaces the earlier one, which put claude in ACP_BACKENDS_STEER. That review round found it made messaging channels drop a steer the adapter didn't inject, opted claude into untested in-band deny notices, and broke the H6 table guarantee.

Change.

  • ACP_BACKENDS_STEERING_REQUEST = {codex, claude}. ACP_BACKENDS_STEER is unchanged ({kiro, kas}, still meaning _session/steer).
  • AcpClient, by table rather than by backend name:
    • supports_steer: True for ACP_BACKENDS_STEER ∪ ACP_BACKENDS_STEERING_REQUEST.
    • supports_refusal_steer: ACP_BACKENDS_STEER only, so claude's deny notices keep the refusal-recovery path.
    • steer_needs_loss_recovery: True for ACP_BACKENDS_STEERING_REQUEST. The provider wrapper then refuses, so channels, Side Chat and spawn_steer queue, as they do for codex. Only the dashboard composer steers, and it requeues whatever isn't reported consumed.
  • AcpClient.steer routes steering-request members to _steer_via_steering_request. It's fire-and-forget, because the turn's dispatch loop is this client's only stdout reader.
    • It sends only if the adapter advertised steering and a turn is running, within the handle's text and outstanding-count bounds.
    • It sends _meta.steering.idleBehavior: "promptRequired", so a steer that reaches the adapter after the turn ended is answered promptRequired and starts nothing.
    • It registers the request id before the write. A failed write keeps the registration, so the steer settles once: consumed if an injected answer is read, otherwise requeued by teardown.
  • _dispatch_events settles answers:
    • injected for the prompt being served marks the text proven.
    • Any other outcome, or an answer aimed at an older prompt, settles nothing.
    • Proven texts are reported as EVENT_STEER_CONSUMED only at a clean terminal (not cancelled, no refusal, stop reason exactly end_turn), the same allowlist as _release_proven_steers on the handle.
  • The shared steering constants and steering_outcome move from session_handle.py to acp/types.py, because session_handle imports client. The handle imports them from there.
  • Spec docs: harness-parity H6, harness-onboarding, messaging and injected-messages describe claude on AcpClient.

Alternative considered. A concurrent second session/prompt (claude-agent-acp's promptQueueing). Rejected: that creates a second adapter turn with its own PromptResponse, which this client's single-turn read loop doesn't own.

Backwards compatibility

Compatible:

  • kiro and KAS are unchanged, and so are codex's handle path and semantics.
  • On claude, a dashboard message that used to queue is now steered, and requeued exactly as before if it isn't reported consumed.
  • Channel, Side Chat and spawn_steer messages on claude still queue.
  • An adapter that doesn't advertise steering keeps today's queue behaviour.

With a pre-empting steer, claude-agent-acp releases before the fixes in #958 and #1166 could end a turn before the steered work finished. On 0.63.0 we saw -32603 [ede_diagnostic] result_type=user ... stop_reason=null. The runs below are on 0.81.2.

Tests

  • test/test_acp_claude_steering.py (new, 36 tests):
    • the request shape (bare-text prompt, idleBehavior, no delivery key);
    • the advertisement parser, the initialize handshake recording it, and the gates on advertisement and active turn;
    • the text and outstanding-count bounds;
    • a failed write keeping its registration, which an injected answer then settles;
    • consumed only at a clean end_turn, one echo per steer;
    • nothing consumed on cancelled, refusal, max_tokens, empty-reason or error terminals, or on a cancel flag with an end_turn terminal;
    • promptRequired, startedNewTurn, failed, non-object and error answers settling nothing;
    • a proof not outliving its turn, a late answer for an older prompt being dropped, and older entries being forgotten;
    • the provider wrapper refusing on claude (supports_steer False, nothing written).
  • Updated for the new set: test_harness_parity.py (test_steer_is_opt_in, plus a new per-backend test_client_steer_capabilities_match_the_steer_tables), test_acp_capability_sets_leaf.py, test_acp_client_more_coverage.py, and test_codex_steering_request.py (membership pin, constants now in acp/types.py).
  • 18 break-and-fail mutations of the new code, each caught by at least one test.
  • test/test_acp_*.py, test/*steer*.py, parity, codex-steering, backend-cards, deny-notice, approval and channel-activation suites: 5705 passed. The 52 failures in test_acp_runtime.py (KAS readiness / worker identity) are identical by name on unmodified main in this environment, so they're unrelated.
  • black, flake8, isort, mypy src/kiro_crew/ (clean), the comment-history gate and docs-lint.sh.

Manual verification

All on unmodified claude-agent-acp 0.81.2:

  • Handshake: initialize carries _meta.steering.supported: true.
  • Steer at the first tool call of a multi-command turn: answered injected, the commands stopped, the reply followed the steer, and the turn ended end_turn.
  • Steer during a long text-only answer (the case that failed on 0.63.0): answered injected, the answer was cut off and replaced by the steered reply, and the turn ended end_turn with no error.
  • Dashboard: a message sent to a running claude chat was steered into that turn (steer card shown) instead of queued.

These runs used the earlier form of this change on a 0.8.0.3 install, which predates #14115. It sent the same request, but reported the steer consumed as soon as the injected answer arrived rather than at the clean terminal. The two scripted runs drove AcpClient directly.

Not verified live: a steer injected while a claude permission request is pending. The adapter delivers it at priority later; supports_refusal_steer stays False, so no deny-notice path depends on it.

Related Issues

Checklist

  • At most two commits (one is the norm), with a Conventional Commits title
  • 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

@justin-robinson
justin-robinson requested a review from a team as a code owner September 27, 2026 21:11
@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 Sep 27, 2026
@justin-robinson

Copy link
Copy Markdown
Author

Intent: On a claude session, a steer sent while a turn is running reaches that turn (over claude-agent-acp's _session/steering) instead of silently waiting in the queue.
Not a goal: changing kiro-cli/KAS steering, codex steering (#14115), or working around settlement bugs in older claude-agent-acp releases.

@justin-robinson
justin-robinson force-pushed the feat/claude-steer-session-steering branch from 4da3b2a to 78b11d3 Compare September 27, 2026 21:50
@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

First Principles Review (Fable 5, fork) — ✅ PASS

Premise-level review of 682fbe00e93299786453e9681535fed6e67cc773 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/CONCERNS are advisory.

First-Principles-Verdict: PASS

The description's own admission: live runs used the earlier revision (consume-on-injected, pre-#14115 install) — confirm the shipped clean-terminal settlement once on live 0.81.2.

What this change ships

Inventory (9 items) — 7 justified

Intent: a mid-turn message on a claude dashboard session reaches the running turn instead of silently queueing — an ADDITION (new backend capability), grounded in a measured adapter behavior and the existing #14115 model.

  1. A composer message sent mid-turn on claude now steers the running turn — justified
  2. A claude steer is confirmed only when its turn ends cleanly; otherwise the text requeues and runs as its own turn — justified
  3. Channel, Side Chat and spawn_steer messages on claude still queue (provider wrapper refuses) — justified
  4. claude's backend card now shows mid-turn steer supported (LINE_MID_TURN_STEER union) — undeclared: automatic consequence of set membership the description never mentions; harm-free
  5. An adapter not advertising initialize._meta.steering.supported keeps today's queue behavior — justified
  6. A steer that misses its turn is answered promptRequired and starts nothing — justified
  7. Steering constants and steering_outcome moved to acp/types.py — justified
  8. _dispatch_events split into wrapper + _dispatch_events_loop — rides along: internal restructure, harm-free
  9. Specs (H6, harness-onboarding, messaging, injected-messages) updated in the same commit — justified

Counts run: client.steer on the client path has 1 real consumer (steer_into_running_turn, chat_delivery.py:477, with pending-entry requeue); EVENT_STEER_CONSUMED has 3 existing driver-agnostic readers (chat_runner.py:16416, llm_helpers.py:2491, messaging/driver.py:657). The rewritten membership pins (test_only_codex_takes_the_steering_request, supports_steer False for claude, the "Always False" docstring) are mutation pins updated with the measurement they demanded, declared in the description.

[FIRST-PRINCIPLES-REVIEWED] 682fbe0

Description read

[DESCRIPTION-READ] 7fbb53d1325e139bae7cfa67a2e5b7179481abc212f41a5de10ed9f9efeb1aab

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 Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Fable 5, fork) — 🟡 CONCERNS

Design-level review of 682fbe00e93299786453e9681535fed6e67cc773 via the fork AI-review pipeline — updated in place on each push. A BLOCK verdict blocks PR readiness; PASS/CONCERNS are advisory.

Design-Verdict: CONCERNS

A startedNewTurn answer is warn-only on AcpClient, leaving an adapter-owned turn running that no dispatch loop reads — the handle cancels the same turn.

Watch

  • _settle_steering_answer handles startedNewTurn with only logger.warning(...answered startedNewTurn despite promptRequired), while AcpSessionHandle runs _cancel_unowned_turn for the identical answer. If an adapter regression violates the negotiated idleBehavior, the unowned turn's session/update frames sit on stdout and interleave into the next prompt's stream, and the unconsumed steer also requeues, so the text runs twice around a corrupted turn.
    Clears when: the client sends session/cancel on a startedNewTurn answer (mirroring the handle), or a recorded 0.81.2 run shows the adapter never emits it under promptRequired.
  • The description says the live runs "used the earlier form of this change," which reported consumption at the injected answer, not at the clean terminal — so this revision's requeue-on-unclean-terminal path (the at-least-once double-run a user actually sees) has only mocked coverage.
    Clears when: one live run on claude-agent-acp 0.81.2 of steer → cancel shows the steered text requeued and run exactly once as its own turn.

[DESIGN-REVIEWED] 682fbe0

Description read

[DESCRIPTION-READ] 59b3513fc4fc1a135453a6eb7538e500cbc530834bf694cbe9cc799fd0e3525e

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 Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

GPT 5.6 Review (fork) — 🔴 changes requested (blocking)

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

1 of 1 blocking finding(s) are security-class and were withheld from adjudication, so the blocking verdict stands.

BLOCKING -- src/kiro_crew/acp/client.py:10054 -- malformed response IDs crash active turns
and msg.id in getattr(self, "_steering_requests", {})
ACP frame with id: [] -> _process_message -> unhashable dictionary lookup -> active turn crashes.
Anchor: residual/crash-data-loss-corruption
Fix: Require an integer request ID before dictionary membership.
[BLOCK-MERGE] 682fbe0
[GPT-REVIEWED] 682fbe0

Adjudication (Opus 5) — is blocking on each finding proportionate?

F1 — harm rung: MEDIUM–HIGH crash/data-loss class (the in-flight turn dies; _prompt_loop's finally at src/kiro_crew/acp/client.py:10355-10357 releases _turn_lock and _turn_done, so the client is not wedged, but the turn's output is lost and the exception surfaces to the caller).
Conditions confirmed: id is taken verbatim from the frame with no shape validation (src/kiro_crew/acp/types.py:596-602, id: Any); a list/dict id falls past is_response_for (types.py:613, self.id == req_id is False) into the new membership test (patch lines 182-187, msg.method is None and msg.id is not None and msg.id in …), where CPython hashes the key before the lookup and raises TypeError even against an empty dict; the raise propagates out of _process_message at client.py:10344 inside _prompt_loop with no handler between it and the turn.
Real fix cost is one isinstance guard — the repo already spells exactly this for the same field on the permission path (src/kiro_crew/acp/_dispatch.py:1432-1437), so no new state, ordering contract or mechanism is introduced. Rarity does not carry a FLAG either: the frame writer is a foreign adapter process, and this codebase repeatedly pins peer-supplied unhashable JSON as a live class it must not crash on (test/test_kas_hooks_acp.py:612 for a peer-decided method, test/test_tips_edition_pool.py:640 for an unhashable id), which is the opposite of an input the system's own writer cannot produce.

[ADJUDICATION] 682fbe00e93299786453e9681535fed6e67cc773 total=0 uphold=0 downgrade=0
[GPT-ADJUDICATED] 682fbe00e93299786453e9681535fed6e67cc773

[ADJUDICATION-FENCED] 682fbe00e93299786453e9681535fed6e67cc773 fenced=1 flagged=0
UPHOLD-FENCED F1 src/kiro_crew/acp/client.py:10054 -- A response-shaped frame with a JSON array/object `id` reaches the unguarded dict membership test and kills the active turn, and the repo's own guard for that exact field on the permission path plus its standing pins on peer-supplied unhashable JSON show this is a live wire shape rather than an extreme condition combination.
[GPT-ADJUDICATED-FENCED] 682fbe00e93299786453e9681535fed6e67cc773

@github-actions

github-actions Bot commented Sep 27, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

[OPUS-REVIEWED] 682fbe0

@github-actions github-actions Bot added the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 29, 2026
@justin-robinson
justin-robinson force-pushed the feat/claude-steer-session-steering branch from 78b11d3 to 682fbe0 Compare September 30, 2026 15:07
@justin-robinson

Copy link
Copy Markdown
Author

Reworked onto #14115 (head 682fbe00e)

#14115 merged the model this needed, so claude now joins it instead of running beside it. The description is rewritten from What changed down; the frozen sections are untouched. How each finding on 78b11d3ed is answered:

Prior finding Answer
opus — claude in ACP_BACKENDS_STEER makes every messaging channel ack a mid-turn message as folded, then drop it; only the dashboard requeues Fixed. claude is in ACP_BACKENDS_STEERING_REQUEST, so steer_needs_loss_recovery is True and the provider wrapper refuses: channels, Side Chat and spawn_steer queue, exactly as for codex. Only the dashboard composer steers.
opus — harness-parity.md H6 still guarantees membership implies one verb Fixed. H6, harness-onboarding.md, messaging.md and injected-messages.md now describe claude on AcpClient over the steering request; ACP_BACKENDS_STEER still means _session/steer. Both properties read the tables, not == ACP_BACKEND_CLAUDE.
gpt — ambiguous drain failure can duplicate a claude steer Fixed. A failed write keeps the registration and returns True, so the pending entry settles once: consumed if an injected answer is read before a clean terminal, otherwise requeued. The log names AcpProcessDied when that is the cause.
design — provider behavior on the adapter users run is an unverified premise Fixed. Verified on unmodified claude-agent-acp 0.81.2: the advertisement in initialize, a steer at a tool call, a steer during a text-only answer, and a dashboard steer. Results and their caveats are under Manual verification.
design — gate the claude route on initialize._meta.steering.supported Fixed. The route sends only when the adapter advertised it; otherwise the caller queues. The parser and the handshake wiring are both tested.
first-principles — deny paths ride along on membership Fixed. supports_refusal_steer is ACP_BACKENDS_STEER only, so claude's deny notices keep the refusal-recovery path. Nothing depends on the unverified pending-permission case.
first-principles — delivery: "next" is unverified on a released adapter Fixed by deletion. The key is gone; only idleBehavior: "promptRequired" is sent.

Two things worth a reviewer's attention, both mine rather than a lane's:

  • A follow-up review of the first rework found that stream_events clears _turn_done before the prompt frame is written, so has_active_turn() was already True while the served prompt still named the previous one. A steer in that window could be injected into the new turn, dropped as stale, and requeued, running twice. A steering request is now admitted only while a dispatch loop is serving a prompt, and is aimed at that prompt.
  • Adding that lifetime to _dispatch_events would have re-indented ~400 lines of it. The body moved unchanged into _dispatch_events_loop and _dispatch_events is a thin wrapper, which is why five source-inspecting tests now name the inner generator. The diff is byte-identical with and without -w.

Delivery is at-least-once by construction, as on the handle: the docstrings say so, and the requeue's visible duplicate is preferred to a silent loss.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Sep 30, 2026
@justin-robinson

Copy link
Copy Markdown
Author

Backend Tests (3.12, 2) on 682fbe00e is the known flake in #14742, not this change:

  • Both failures are test/test_remote_crew_chaining.py::TestTheHopOwnershipInvariantHolds (test_it_holds_after_the_recovery_gives_up, test_it_holds_after_a_teardown), each reporting a lent ephemeral port with no owner — the same invariant, the same shard, and the same fork-PR shape Flaky: test_it_holds_after_the_recovery_gives_up reports a hop-ownership violation on a shared runner #14742 records.
  • This diff touches no remote-crew chaining code (acp/client.py, acp/session_handle.py, acp/types.py, agent_sdk/backends.py, backend_cards.py, four spec docs, and tests).
  • The class passes locally on this branch, 5/5, including inside the whole shard under -n 8.
  • Shard 2 is green on other open PRs, so this is not a repo-wide red.

A targeted rerun --failed needs admin rights on this repository, so I can't trigger it from a fork. Could a maintainer rerun that job, or leave it for the next push to re-run? I'd rather not push a no-op commit just to re-trigger CI.

claude-agent-acp has no _session/steer, so a mid-turn steer on the claude
backend was refused and queued as a new turn. The adapter speaks the ACP
steering request instead and advertises it as
initialize._meta.steering.supported.

- ACP_BACKENDS_STEERING_REQUEST gains claude; ACP_BACKENDS_STEER stays
  the _session/steer set, so claude's deny notices keep the
  refusal-recovery path (supports_refusal_steer False).
- AcpClient answers supports_steer and steer_needs_loss_recovery from
  the tables, so only the dashboard composer steers claude; channels,
  Side Chat and spawn_steer queue, as for codex.
- AcpClient.steer sends _session/steering fire-and-forget with
  idleBehavior=promptRequired, only when the adapter advertised it and
  within the handle's bounds. A failed write keeps its registration, so
  the pending entry settles exactly once.
- The turn's dispatch loop settles the answer by request id and reports
  EVENT_STEER_CONSUMED only for an injected answer read before a clean
  end_turn terminal; any other ending leaves the steer for the turn-end
  requeue. Answers aimed at an earlier prompt are dropped.
- The steering method, outcomes, bounds and outcome parser move to
  acp/types.py so the session handle and AcpClient share them.
@justin-robinson
justin-robinson force-pushed the feat/claude-steer-session-steering branch from 682fbe0 to 323835f Compare September 30, 2026 16:10
@justin-robinson

Copy link
Copy Markdown
Author
  • span=0dfda262228b — fixed

Reproduced before fixing: a response-shaped frame with id of [], {} or ['x'] raised TypeError: unhashable type out of _process_message, killing the in-flight turn. The finding is correct and the defect is this PR's.

Fixed in 323835f74 by requiring an integer request id before the membership test, matching the guard the repo already spells for the same field on the permission path in acp/_dispatch.py. The sibling pop(msg.id) in _settle_steering_answer is reached only through that branch, so it is covered by the same guard.

Re-probed after the fix: [], {}, ['x'], a string id and None all classify as skip without raising, while a registered integer id still classifies as steering_response. Tests cover the list and dict shapes, and breaking the guard fails them.

@justin-robinson

Copy link
Copy Markdown
Author
  • span=6bfafce56d18 — fixed

Fixed in 323835f74 rather than argued: the client now sends session/cancel on a startedNewTurn answer, so the two drivers behave the same when an adapter violates the negotiated idleBehavior.

It is written as _cancel_unowned_steering_turn, deliberately not through cancel_session, which would mark the serving turn cancelled. It fires only for an answer aimed at the prompt its loop serves — the handle's "do not cancel once a newer prompt of ours is running" hazard is therefore excluded by construction rather than re-checked — and it is best-effort: a failed write is logged, never raised into the dispatch loop.

Tests cover the cancel being sent, nothing being settled, and a failing cancel write not raising.

@justin-robinson

Copy link
Copy Markdown
Author
  • span=91bfa9213c09 — fixed

The objection was right: the earlier runs used the form that reported consumption at the injected answer, so the requeue-on-unclean-terminal path had only mocked coverage. Recorded the run you asked for instead of rebutting.

Live on stock claude-agent-acp 0.81.2, driving THIS revision's client (repo src shadowing the installed core, verified by the presence of _cancel_unowned_steering_turn): steer injected at the first tool call of a multi-command turn, then session/cancel one second later.

Result: COMPLETE stop_reason='cancelled', and no EVENT_STEER_CONSUMED was emitted — so nothing settles the caller's pending entry and _requeue_unconsumed_steers queues the text, which then runs once as its own turn. The two clean-terminal runs were re-recorded on the same code and adapter for comparison: both answered injected and reported consumed at end_turn.

What remains test-only is the dashboard half of that requeue (chat_runner), since this harness drives AcpClient directly.

@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 Sep 30, 2026
@github-actions github-actions Bot removed the readiness: checking Automated validation is still running label Sep 30, 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.

1 participant