Repository navigation
feat(session-control): let a peer steer Claude Code and Codex turns - #23772
Conversation
UX Review (Opus 5.5, fork) — ⏭️ skippedRevision |
Opus 5.5 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. Notes:
[OPUS-REVIEWED] 50fae23 |
Design Review (Opus 5.5, fork) — ✅ PASSDesign-level review of Design-Verdict: PASS Nothing blocks: the key is opt-in and off by default, the teardown requeue it relies on already exists, and the two existing discard notices still produce the same text. Notes
[DESIGN-REVIEWED] 50fae23 Description read[DESCRIPTION-READ] 269ae979ab845cffedd1add4104ec55fca4f9b0a8413e2855cf9c1859788a8f9 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 |
First Principles Review (Opus 5.5, fork) — ✅ PASSPremise-level review of First-Principles-Verdict: PASS Nothing blocks: the key is off by default, the refusal it lifts is backed by recorded history, and the requeue path it depends on already exists. One rider is wider than the Goal. Notes
What this change shipsInventory (5 items) — 4 justifiedIntent: let a conductor correct a Claude Code or Codex worker partway through a turn, instead of queueing the correction behind the work it is meant to fix. ADDITION.
[FIRST-PRINCIPLES-REVIEWED] 50fae23 Description read[DESCRIPTION-READ] 6b574a795e382daa8ed6c99c926f70884f027dce46394ffdbbc8a21bb1bddefd That sha256 names the PR description this verdict read. Recompute it with |
GPT 6.1 Review (fork) — ✅ no blocking findingsReviewed Review detailsNo findings. |
3e32766 to
58f840e
Compare
|
Rebased onto What conflicted and how each was resolved:
Tests: |
58f840e to
5fee593
Compare
|
Thanks for this PR. On head 5fee593 the only real red is Backend Tests (3.12, 5), with Coverage Gate failing after it. The shard fails on three cases of Main has since changed this test's setup in #29623, merged after these runs. A rerun would test the same old merge base, so could you update the branch onto main (rebase, keeping one or two commits for PR Hygiene)? CI will then run against the current base. |
5fee593 to
1e2e4be
Compare
1e2e4be to
db11a67
Compare
A session_send or session_broadcast steer into a running Claude Code, Codex, Goose, Pi or OpenCode turn always came back queued: steer_into_running_turn refused every steer not typed into the session's own composer on a harness whose steer_needs_loss_recovery is true. kirodotdev#14115 added that refusal while a codex steer still counted as consumed on its injected answer, so a later denied approval lost it. The same PR then moved consumption to the turn's clean end, and since then the teardown requeue covers a dropped steer for every caller that registers one, the peer path included. agent.peer_steer_loss_recovery, off by default, lifts the refusal. With the key on, a peer's or an automation's steer registers as the composer's does: it counts as delivered when its turn ends cleanly, and the teardown otherwise requeues it as a queue card that runs as the next turn, so it can run twice. With the key off nothing changes. The guard reads the key from the config watcher's snapshot, so the steer path reads no file on the event loop and gains no await before the steer registers; with no snapshot yet the refusal stands. The session-control spec describes the key.
…stop drops it With agent.peer_steer_loss_recovery on, a peer's steer into a Claude Code or Codex turn answers steered and stays pending, because these harnesses count a steer as consumed only when the turn ends cleanly. While it is pending it holds its admission, so a soft stop that requeues it still stamps its sender on the queue entry, a drain that drops that entry tells the sender, and the steering_consumed settle releases the admission once the turn reads it. A second Stop that hard-killed the turn before its teardown dropped the pending steer without a word to its sender. While the key is on, the hard stop now tells the sender of each pending peer steer that answered steered or requeued, with a new SEND_DISCARD_HARD_STOP_STEER notice: the steer may not have run, since the turn may already have read it, and it will not be queued to run later. That covers a steer the key admitted and a peer's kiro-cli or KAS steer the turn has not read yet. A steer still in its RPC is skipped, because it then answers unavailable and its sender queues it. The hard stop reads the key from the config watcher's snapshot, as the admission does, and with the key off it drops every pending steer without a notice, as before. The key's help text and the session-control spec say so.
db11a67 to
50fae23
Compare
iamwhatever
left a comment
There was a problem hiding this comment.
Approving at 50fae23.
The new key agent.peer_steer_loss_recovery defaults to off, and with it off the refusal in steer_into_running_turn and the hard stop behave exactly as on main. With it on, a peer steer registers its admission like the composer's, so the existing teardown requeue and the drain's re-check still apply. The new hard-stop notice skips steers still in their RPC and goes through the same sender resolution as the other discard notices. All AI lanes reviewed this head, all 93 checks are success or skipped, and the branch is on a current base, which covers the earlier rebase request.
AI findings judged non-blocking
- Opus (fork) note,
harness-parity.mdH6 andmessaging.mdstill say only the composer steers these harnesses: still true with the key at its default, andsession-control.mddocuments the key. A one-line spec update would still help (H6). - Design note, the kiro-cli/KAS hard-stop notice depends on this key: with the key off nothing changes from main, and with it on the notice is informational only (turn_stop.py#L587).
- First Principles item 3, same notice called an oversized rider: opt-in, informational, and no delivery or authorization change. The author explained the choice in the 2026-10-31 comment (turn_stop.py#L587-L599).
— crew-pr-reviewer (r148)
Problem / Motivation
Goal: With
agent.peer_steer_loss_recoveryon, another session's steer reaches a running Claude Code, Codex, Goose, Pi or OpenCode turn, the way it already reaches a kiro-cli or KAS turn.Today a
session_sendwithsteer: true, or asession_broadcastinsteermode, into a running turn on one of those harnesses always comes back queued.steer_into_running_turnanswersunavailableto every caller except the session's own composer when the client'ssteer_needs_loss_recoveryis true, so the message waits for the turn to end.Why it matters
A conductor that sees a worker go the wrong way can only queue its correction behind the work it wants to correct, or stop the worker. Crews that run their workers on Claude Code or Codex lose the mid-turn correction that crews on kiro-cli already have.
Not a goal
main.spawn_steeruse: those keep queueing on these harnesses.What changed (motivation → approach → change)
With the
agent.peer_steer_loss_recoverykey on, another session's steer cuts into a running Claude Code, Codex, Goose, Pi or OpenCode turn instead of waiting for it to end. The key is off by default.#14115 added the refusal while a codex steer still counted as consumed on its
injectedanswer, so a later denied approval lost it, and only the composer's human could notice and resend. Later in the same PR, consumption moved to the turn's clean end. Since then the teardown requeue (_requeue_unconsumed_steers) puts a dropped steer back for every caller that registers one, and the peer path registers one through the same function. The refusal stayed, and its comment still described the loss that was gone.The key lifts that refusal. With it on, a steer whose
user_originis false registers as the composer's does: it counts as delivered when its turn ends cleanly, and otherwise the teardown requeues it at the head of the queue with its send's admission, so a drain that drops it still tells the sender, and without the composer's LINKED-drop exemption. The refusal's comment states the cost that remains, a possible second run.The refusal in
dashboard/chat_delivery.pyreads the key from the config watcher's snapshot (config/live.py), not from disk: it runs on the event loop, and nothing may suspend between the send's gate and the steer's registration. With no snapshot yet the refusal stands, and the key is read only for a non-composer steer into one of these harnesses.A second Stop that hard-kills the turn drops its pending steers. While the key is on,
chat_api/turn_stop.pytells the sender of each pending peer steer with its own notice (SEND_DISCARD_HARD_STOP_STEER, worded insession_control_parts/delivery_containment.py): the steer may not have run, and it will not be queued to run later. That covers a steer the key admitted and, opted in with the key, a peer's kiro-cli or KAS steer its turn has not read yet. The hard stop reads the key from the same snapshot. With the key off it drops pending steers without a notice, as onmain.config/sections_agent.pydeclares the key and its help text names the notice,config/loader_builders.pyreads it,config-baseline.jsonlists it, anddocs/system-specs/modules/session-control.mddescribes the key and the notice.Backwards compatibility
Compatible: the key defaults to
false, and with it offsteer_into_running_turnrefuses exactly the steers it refuses onmain, and a hard stop drops pending steers without a notice, as onmain.Removes nothing: the diff adds one config key, reads it in one existing condition, and adds one sender notice.
Tests
test/test_steer_requeue.py::TestPeerSteerOnCodex::test_the_key_lets_a_peer_steer_codex_once_the_config_watcher_holds_itwrites the key into the test home'sconfig.jsonand steers a loss-recovery client withuser_origin=False. While the config watcher holds no snapshot the steer is refused; once the watcher is primed from that file the steer is delivered and stays in_pending_steers, where the teardown requeue finds it. Red onmain(unavailable), red when the loader stops reading the key, and red when the guard falls back to a disk load.test_a_requeued_peer_steer_still_tells_its_sender_when_the_drain_drops_it: with the key on, a peer's steer into a loss-recovery client is delivered, a channel mirror is added, and the teardown requeues the steer before its turn ends cleanly. The queue entry still names the sender, and when the drain drops it the sender's transcript gets the drop notice. Red when the steered tail drops a pending steer's admission (assert '' == 'chat-1').test_a_consumed_peer_steer_leaves_no_admission_behind: the same steer, consumed when its turn ends cleanly, leaves_steer_admissionsempty. Red when the consumed settle does not release it.test_a_hard_stop_tells_the_sender_of_a_pending_peer_steer: one peer steer has answered steered and another is still in its RPC when two Stop presses hard-kill the turn. Only the first one's sender gets a notice, worded for a steer, and the held one answers unavailable. Red when the hard stop sends no notice (assert 0 == 1), when it also notifies the steer still in its RPC, and when the notice reuses the queue wording or says the steer never ran.test_a_hard_stop_tells_a_kiro_cli_peer_steer_sender_only_with_the_key_on, for the key on and off: a kiro-cli peer steer pending at the same hard stop gets the notice with the key on and none with it off. Red when the notice ignores the key, and when it is limited to the harnesses the key admits.test_a_peer_steer_into_codex_is_refused_before_the_rpc, unchanged, pins the default-off refusal, andtest_queue_discard_sender_notice.py, unchanged, pins the queue entries' hard-stop wording.Proof: PROVEN test/test_steer_requeue.py::TestPeerSteerOnCodex::test_the_key_lets_a_peer_steer_codex_once_the_config_watcher_holds_it, test/test_steer_requeue.py::TestPeerSteerOnCodex::test_a_requeued_peer_steer_still_tells_its_sender_when_the_drain_drops_it, test/test_steer_requeue.py::TestPeerSteerOnCodex::test_a_consumed_peer_steer_leaves_no_admission_behind, test/test_steer_requeue.py::TestPeerSteerOnCodex::test_a_hard_stop_tells_the_sender_of_a_pending_peer_steer, test/test_steer_requeue.py::TestPeerSteerOnCodex::test_a_hard_stop_tells_a_kiro_cli_peer_steer_sender_only_with_the_key_on[True-1] (head ea814c9ba695)
Determinism, over the eight
TestPeerSteerOnCodexnode ids:scripts/run_scoped_tests.py --surface backend: the 6641 related backend tests in 167 files pass.Manual verification
Isolated test-mode gateways on this branch, each with its own data home and port, with claude-agent-acp 0.94.0, codex-acp 1.12.0 and kiro-cli 2.37.0. A peer session sent
POST /api/session-control/sendwithsteer: true, the requestsession_sendmakes; a WebSocket client recorded the target's frames.sleep 45ran:steered: true, and the steer row reachedconsumedwhen that turn ended, in all four runs; the reply followed the steer in two of them.steered: true, consumed in the same turn, and the reply followed it. (mainholds a Claude Code steer while a tool call is open, so this run uses no tools.)requeued, onequeue_pushand itsqueue_popfollowed, and the steer ran once as the next turn, its row carrying the sender's stamp.SEND_DISCARD_HARD_STOP_STEERnotice.steered: false, queued the steer and ran it after the turn ended. The Kiro CLI session took the steer, and two Stop presses dropped it with no notice, as onmain.Related Issues
Closes #23765
Checklist
feat|fix|docs|style|refactor|perf|test|chore|ci|build|revert: ...)