Skip to content

feat(session-control): let a peer steer Claude Code and Codex turns - #23772

Merged
iamwhatever merged 2 commits into
kirodotdev:mainfrom
ash663:feat/peer-steer-loss-recovery
Nov 6, 2026
Merged

iamwhatever merged 2 commits into
kirodotdev:mainfrom
ash663:feat/peer-steer-loss-recovery

Conversation

@ash663

@ash663 ash663 commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Problem / Motivation

Goal: With agent.peer_steer_loss_recovery on, 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_send with steer: true, or a session_broadcast in steer mode, into a running turn on one of those harnesses always comes back queued. steer_into_running_turn answers unavailable to every caller except the session's own composer when the client's steer_needs_loss_recovery is 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

  • Changing the default: with the key off, the refusal stands as it is on main.
  • Steering through the provider wrapper that the messaging channels, Side Chat and spawn_steer use: those keep queueing on these harnesses.
  • Exactly-once delivery: a steer these harnesses drop is requeued and can run twice, as a composer steer already can.

What changed (motivation → approach → change)

With the agent.peer_steer_loss_recovery key 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 injected answer, 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_origin is 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.py reads 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.py tells the sender of each pending peer steer with its own notice (SEND_DISCARD_HARD_STOP_STEER, worded in session_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 on main.

config/sections_agent.py declares the key and its help text names the notice, config/loader_builders.py reads it, config-baseline.json lists it, and docs/system-specs/modules/session-control.md describes the key and the notice.

Backwards compatibility

Compatible: the key defaults to false, and with it off steer_into_running_turn refuses exactly the steers it refuses on main, and a hard stop drops pending steers without a notice, as on main.

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_it writes the key into the test home's config.json and steers a loss-recovery client with user_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 on main (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_admissions empty. 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, and test_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 TestPeerSteerOnCodex node ids:

for i in $(seq 20); do python -m pytest -n0 -p no:cacheprovider -q @ids.txt || break; done
n0 passes: 20/20

for i in $(seq 10); do python -m pytest -n 4 --dist loadgroup --max-worker-restart=2 -p no:cacheprovider -q @ids.txt test/test_steer_requeue_entry_meta.py test/test_queue_drop_sender_notice.py test/test_queue_discard_sender_notice.py test/test_config_baseline.py || break; done
n4 passes: 10/10   (85 passed per run)

shuffled, seed=9445, every test in test/test_steer_requeue.py:
50 passed

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/send with steer: true, the request session_send makes; a WebSocket client recorded the target's frames.

  • Key on, Codex, steer sent while sleep 45 ran: steered: true, and the steer row reached consumed when that turn ended, in all four runs; the reply followed the steer in two of them.
  • Key on, Claude Code, steer sent while a tool-free reply streamed: steered: true, consumed in the same turn, and the reply followed it. (main holds a Claude Code steer while a tool call is open, so this run uses no tools.)
  • Key on, steer then Stop, on both harnesses: the row turned requeued, one queue_push and its queue_pop followed, and the steer ran once as the next turn, its row carrying the sender's stamp.
  • Key on, steer then two Stop presses at once, on Codex, Claude Code and a Kiro CLI session (served on kiro-cli's KAS engine): the turn was hard-stopped and the sender's transcript got the SEND_DISCARD_HARD_STOP_STEER notice.
  • Key off: Claude Code and Codex answered 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 on main.

Related Issues

Closes #23765

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

@ash663
ash663 requested review from a team and KiroCrewCaptain as code owners October 24, 2026 15:49
@ash663
ash663 requested a review from iamwhatever October 24, 2026 15:49
@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 24, 2026
@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

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

Revision 50fae2333fcc3f206d1bc74d80bcabc74a715e9f 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 Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Opus 5.5 Review (fork) — ✅ no blocking findings

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

Review details

No findings.

Notes:

  • docs/system-specs/modules/harness-parity.md H6 still says "only [the composer] steers codex", and messaging.md still says those harnesses' steers are "spoken only for the dashboard composer". With agent.peer_steer_loss_recovery on, a peer or automation steer into a dashboard slot now reaches codex, claude, goose, pi and opencode too. Both specs need a sentence naming the key.

[OPUS-REVIEWED] 50fae23

@github-actions

github-actions Bot commented Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

Design Review (Opus 5.5, fork) — ✅ PASS

Design-level review of 50fae2333fcc3f206d1bc74d80bcabc74a715e9f 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 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

  • The hard-stop steer notice is tied to peer_steer_loss_recovery, so a pending kiro-cli or KAS peer steer only gets a notice when that key is on, even though it is a different harness. If that notice is wanted on its own, it should not depend on this key; that belongs in a follow-up PR.

[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 .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 Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

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

Premise-level review of 50fae2333fcc3f206d1bc74d80bcabc74a715e9f 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: 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

  • Item 3 — oversized: the hard-stop notice also covers "a peer's kiro-cli or KAS steer its turn has not read yet". On main those steers are already admitted without any key, and a hard stop already drops them silently, so this is an existing kiro-cli/KAS gap. The Goal is about Claude Code, Codex, Goose, Pi and OpenCode, and this rider ties that separate fix to a key named for loss-recovery admission. Subtraction: in turn_stop.py, notify only for steers that went into a client whose steer_needs_loss_recovery is true. Drop the kiro-cli/KAS case and the [True-1] / [False-0] parametrization that pins it. Clears when: the mechanism is removed, or a human amends the Goal.

What this change ships

Inventory (5 items) — 4 justified

Intent: 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.

  1. New opt-in key agent.peer_steer_loss_recovery (default off) lets another session's steer cut into a running Claude Code, Codex, Goose, Pi or OpenCode turn — justified
  2. With the key on, a hard stop tells the sender that a pending peer steer on those harnesses may not have run — justified
  3. With the key on, the same hard-stop notice also reaches senders of kiro-cli/KAS peer steers — oversized
  4. The refusal's comment and the class docstring are rewritten (the old pin's reason is answered by the fix(codex): steer a running turn over codex-acp's _session/steering #14115 history in the description) — justified
  5. The discard notice wording moves into the reason table; existing notices read the same — justified

[FIRST-PRINCIPLES-REVIEWED] 50fae23

Description read

[DESCRIPTION-READ] 6b574a795e382daa8ed6c99c926f70884f027dce46394ffdbbc8a21bb1bddefd

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 Oct 24, 2026 •

Copy link
Copy Markdown
Contributor

GPT 6.1 Review (fork) — ✅ no blocking findings

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

Review details

No findings.
[GPT-REVIEWED] 50fae23

@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running readiness: passed Eligible automated validation passed for the current revision merge conflict Branch has merge conflicts with its base — author must resolve before merge and removed readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention labels Oct 24, 2026
@ash663
ash663 force-pushed the feat/peer-steer-loss-recovery branch from 3e32766 to 58f840e Compare October 31, 2026 19:44
@github-actions github-actions Bot added readiness: action required A blocking check or review needs attention and removed readiness: passed Eligible automated validation passed for the current revision labels Oct 31, 2026
@ash663

ash663 commented Oct 31, 2026

Copy link
Copy Markdown
Contributor Author

Rebased onto main at d8e604c, still two commits.

What conflicted and how each was resolved:

  • config-baseline.json and config/loader_builders.py: agent.session_manager_chain landed beside the new key. Kept both; the baseline is regenerated with scripts/generate_config_baseline.py.
  • dashboard/chat_delivery.py, the refusal: main added the no-prompt-in-flight check right after it. Kept the key check, then main's check.
  • dashboard/chat_delivery.py, the steered tail, and session_control_parts/session_messaging.py: fix(monitor): preserve member directive self-arm provenance #20169 holds every pending steer's admission until the settle or the requeue releases it, which is what the second commit did for a steer the key admitted. Took main's side and dropped those hunks, along with the settle line in chat_turn/steer_queue.py, which main already has.
  • chat_api/turn_stop.py, the hard-stop notice: with every pending steer holding its admission, the old check would also have notified a kiro-cli or KAS peer sender with the key off. The notice now fires only while agent.peer_steer_loss_recovery is on, read from the config snapshot, so with the key off a hard stop behaves as on main; with it on, a kiro-cli or KAS peer sender gets the notice too. The key's help text, the spec and the second commit's message say so, and test_a_hard_stop_tells_a_kiro_cli_peer_steer_sender_only_with_the_key_on pins both sides.

Tests: test/test_steer_requeue.py and 16 neighbouring files (768 passed); the related backend set from scripts/run_scoped_tests.py --surface backend (6641 passed); black, isort, flake8, mypy, docs-lint, the repository's script gates, the semgrep rules (0 findings) and the flake-pattern ratchet. prove.py: PROVEN. Determinism: 20/20 at -n0, 10/10 at -n 4, one shuffled order. On isolated test gateways, key on: Claude Code and Codex each took a peer steer mid-turn, a steer then Stop ran once as the next turn with its sender stamp, and two Stop presses sent the sender the steer notice, on a Kiro CLI session too. Key off: Claude Code and Codex queued the steer as before, and two Stop presses on a Kiro CLI session sent no notice.

@github-actions github-actions Bot removed the merge conflict Branch has merge conflicts with its base — author must resolve before merge label Oct 31, 2026
@iamwhatever
iamwhatever force-pushed the feat/peer-steer-loss-recovery branch from 58f840e to 5fee593 Compare November 4, 2026 02:24
@github-actions github-actions Bot added readiness: checking Automated validation is still running readiness: action required A blocking check or review needs attention and removed readiness: action required A blocking check or review needs attention readiness: checking Automated validation is still running labels Nov 4, 2026
@bolichen97

Copy link
Copy Markdown
Contributor

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 test/test_decisions_end_to_end.py::test_jev_response_reaches_the_assembled_message (assert 0 == 1). This diff does not touch that area, and the same three cases fail the same way on other open PRs run on the same day, so it is not caused by this change. That job has already been re-run several times on the same base.

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.

@ash663
ash663 force-pushed the feat/peer-steer-loss-recovery branch from 5fee593 to 1e2e4be Compare November 4, 2026 23:37
@iamwhatever
iamwhatever force-pushed the feat/peer-steer-loss-recovery branch from 1e2e4be to db11a67 Compare November 5, 2026 22:54
@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 5, 2026
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.
@iamwhatever
iamwhatever force-pushed the feat/peer-steer-loss-recovery branch from db11a67 to 50fae23 Compare November 6, 2026 04:07
@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 6, 2026
@iamwhatever iamwhatever self-assigned this Nov 6, 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.

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.md H6 and messaging.md still say only the composer steers these harnesses: still true with the key at its default, and session-control.md documents 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)

@iamwhatever
iamwhatever merged commit c0e9c2e into kirodotdev:main Nov 6, 2026
94 checks passed
@github-actions github-actions Bot removed the readiness: passed Eligible automated validation passed for the current revision label Nov 6, 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.

Let a peer's steer reach a Claude Code or Codex turn (opt-in)

3 participants