feat(codex,claude): mid-turn steering — deliver queued messages at step boundaries, not only on full-turn completion

[swear01]

Summary

Today, when the operator sends a message while an agent turn is still running, HAPI queues it and only delivers it after the entire turn terminates (full agentic loop, possibly a dozen tool calls). Both native CLIs we wrap instead deliver such "steering" input at the next step boundary inside the running turn (after the current model output / next tool call), without a hard interrupt.

This issue proposes adding mid-turn steering (opt-in), and documents the per-flavor feasibility I verified. The two flavors are asymmetric, so they need different implementations:

• Codex — the app-server protocol has a first-class, non-interrupting turn/steer RPC. HAPI just doesn't call it. Clean to implement.
• Claude — there is no non-interrupting steer primitive in --input-format stream-json. I verified empirically that mid-turn stdin messages are ignored by the running turn. Steering would require interrupt + resubmit (a soft interrupt), which is a different UX.

Current HAPI behavior (both flavors deliver only at full-turn end)

Codex (cli/src/codex/codexRemoteLauncher.ts):

• turnInFlight is cleared only on a terminal event, and wakeLoop() is called only there — codexRemoteLauncher.ts:2159-2172.
• The main loop parks in waitForTurnOrRecovery (:1797) until the turn fully ends, then pulls the next queued message via session.queue.waitForMessagesAndGetAsString (:2955).
• The app-server client exposes startThread / resumeThread / startTurn / interruptTurn / compactThread / goal — no steer/inject (cli/src/codex/codexAppServerClient.ts).

Claude (cli/src/claude/claudeRemote.ts):

• scheduleNextMessage() (which pushes the next queued user message into the streaming-input iterable) is invoked only when message.type === 'result', i.e. at full-turn end — claudeRemote.ts:258-282.

What the native CLIs do

• Codex: while a turn runs, the queued message UI says "Messages to be submitted after next tool call" (Messages to be submitted after next tool call (press esc to interrupt and send immediately) not working on CLI openai/codex#17095); there is also an experimental "steer conversation" mode (Prompt consumed as steering input during compaction instead of being queued (experimental steer conversation enabled) openai/codex#9524).
• Claude Code (TUI): typed messages "flush at the next LLM pause, not at true end-of-turn, including pauses between tool calls" — note this is controversial; many users actually want an end-of-turn-only queue (Queue messages to send at true end-of-turn, not next LLM pause anthropics/claude-code#49373, #63190), with a separate real-time steering channel requested (#30492).

Findings

Codex — turn/steer exists (verified against codex 0.139.0 schema)

codex app-server generate-ts emits a dedicated steering request:

// ClientRequest: { "method": "turn/steer", params: TurnSteerParams }
type TurnSteerParams = {
  threadId: string,
  clientUserMessageId?: string | null,
  input: Array<UserInput>,   // same shape as turn/start: text | image | localImage | skill | mention
  expectedTurnId: string,    // precondition: must equal the active turn id, else the request fails
}
type TurnSteerResponse = { turnId: string }

Relevant constraints baked into the protocol:

• Not every turn is steerable: NonSteerableTurnKind = "review" | "compact". Steering one returns CodexErrorInfo::activeTurnNotSteerable { turnKind }.
• There is also a lower-level thread/inject_items (raw Responses API items) — not what we want for steering.

HAPI does not reference turn/steer or thread/inject_items anywhere.

Claude — no non-interrupting mid-turn primitive (verified empirically)

streamToStdin writes each pushed message to the child claude stdin immediately (cli/src/claude/sdk/utils.ts:188-192), so a naive "push the queued message as soon as it arrives instead of on result" change is trivial on the HAPI side. But it does not produce mid-turn steering.

I tested claude 2.1.175 directly in --input-format stream-json --output-format stream-json:

• Turn 1 prompt: run sleep 3 && echo AAA, then sleep 3 && echo BBB, as two steps.
• At ~2.0s (before the first tool_use), injected a second user message: "STOP now. Ignore everything before. Reply with exactly: ZEBRA".
• Result: the turn ran AAA → BBB → "All done." → result, never said ZEBRA, did not pivot at the AAA→BBB step boundary, and no follow-up turn for the injected message was produced within the session.

So the running turn ignores (effectively drops) mid-turn stdin input. HAPI's existing "hold in our own queue, push on result" is in fact the safe pattern for stream-json — you cannot steer Claude mid-turn just by pushing earlier. Achieving "deliver after the current output" for Claude would require the interrupt control request (already available: cli/src/claude/sdk/query.ts:171, subtype: 'interrupt') to halt at the next safe point, then resubmit the queued message — i.e. a soft interrupt, with the in-flight step discarded.

Proposed direction

Make this opt-in (per-session or setting), because "queue strictly until end of turn" is a legitimate preference that the current behavior already serves well.

• Codex: add steerTurn(params) to codexAppServerClient (turn/steer). In the launcher, when a queued message arrives while turnInFlight and we hold currentThreadId + currentTurnId, call turn/steer with expectedTurnId: currentTurnId instead of waiting. Fallbacks:
  • activeTurnNotSteerable (review/compact) → fall back to existing queue-until-end path.
  • expectedTurnId race (turn just ended) / unknown method on older codex → fall back to startTurn / current behavior. Gate on capability or codex version.
• Claude: implement via interrupt + resubmit behind the same opt-in. Must decide UX for the discarded in-flight step and how to present it. This is closer to a soft-interrupt than to Codex's true steering — set expectations accordingly.

Open questions

• Minimum codex version that ships turn/steer; best capability-detection (catch "method not found" vs. version check).
• For Claude, whether a soft-interrupt steer is desirable at all, or whether we just document the gap and keep queue-until-end as the only mode.
• Surfacing in the web UI: a "steer now" affordance distinct from plain queue, and distinct from the existing Stop/Abort.

---

Verification artifacts (Codex protocol dump via codex app-server generate-ts, Claude stream-json probe scripts) available on request.

[github-actions]

Thanks for the detailed write-up. Verified against the current tree: HAPI does not currently have a Codex turn/steer path, and Claude remote input is only pulled after Claude emits a result.

For Codex, the app-server client currently exposes thread/start, thread/resume, turn/start, turn/interrupt, compaction, goal, model, and collaboration-mode methods, but I did not find turn/steer or thread/inject_items in the client/types. The launcher tracks currentTurnId/turnInFlight, clears the active turn on terminal events, and normal turns are still started through turn/start. So the Codex part looks like a feasible feature addition, but it would need a new typed client method plus launcher logic for the active-turn case and fallbacks.

For Claude, the current implementation matches your safe-queue observation: claudeRemote pushes the next queued user message into the stream only when message.type === 'result'. HAPI's SDK wrapper does support an interrupt control request for stream-json, but there is no existing non-interrupting steering path in this repo.

One implementation note from the current code: normal queued Codex messages are not explicitly converted to a steer while a turn is active today; admin commands such as /clear and /compact already interrupt active Codex turns before proceeding. A steering mode should stay distinct from those hard/soft interruption flows.

Relevant code:

• cli/src/codex/codexAppServerClient.ts:179 - thread/start client method
• cli/src/codex/codexAppServerClient.ts:195 - turn/start client method
• cli/src/codex/codexAppServerClient.ts:203 - turn/interrupt client method
• cli/src/codex/appServerTypes.ts:157 - current TurnStartParams shape using UserInput[]
• cli/src/codex/appServerTypes.ts:179 - current TurnInterruptParams shape
• cli/src/codex/codexRemoteLauncher.ts:2038 - records active Codex turn id from task_started
• cli/src/codex/codexRemoteLauncher.ts:2159 - clears turnInFlight on terminal events and wakes the loop
• cli/src/codex/codexRemoteLauncher.ts:3083 - sends user input through appServerClient.startTurn(...)
• cli/src/claude/claudeRemote.ts:178 - scheduleNextMessage() pulls the next queued input
• cli/src/claude/claudeRemote.ts:257 - next Claude input is scheduled only after result
• cli/src/claude/sdk/query.ts:171 - stream-json interrupt control request exists
• cli/src/claude/sdk/utils.ts:183 - async input stream writes messages to Claude stdin

Need more info:

• Can you share the codex app-server generate-ts artifact or the exact turn/steer type block for the minimum Codex version you tested?
• Should the first implementation be Codex-only true steering, leaving Claude documented as queue-until-result until a separate soft-interrupt UX is designed?

---

HAPI Bot

[swear01]

Investigation update: Codex has a true steer primitive; Claude's is not reachable via the SDK

I dug into both runtimes against the actually-installed CLIs. Summary: Codex exposes a clean non-interrupting steer RPC; Claude's real-time steering exists only in the interactive TUI and is not exposed through the Agent SDK / stream-json interface HAPI drives. So this lands as Codex true steering now, Claude deferred.

Codex — turn/steer is a first-class protocol method ✅

Verified against codex-cli 0.139.0 via codex app-server generate-ts:

// ClientRequest: { "method": "turn/steer", params: TurnSteerParams }
type TurnSteerParams = {
  threadId: string,
  clientUserMessageId?: string | null,
  input: Array<UserInput>,   // same shape as turn/start
  expectedTurnId: string,    // precondition: must equal the active turn id
}
type TurnSteerResponse = { turnId: string }

• Non-steerable kinds are explicit in the protocol: NonSteerableTurnKind = "review" | "compact"; steering one returns CodexErrorInfo::activeTurnNotSteerable { turnKind }.
• HAPI's app-server client does not reference turn/steer today → feasible to add.

Claude — steering is TUI-only; the SDK/stream-json path can't reach it ❌

Claude Code's interactive TUI does have real-time steering (typed-during-execution messages tagged [steering], injected at the next tool boundary, non-destructive). But that path is not what HAPI uses. HAPI drives claude --print --input-format stream-json, and on that surface:

• Upstream confirms it's not in the SDK: anthropics/claude-agent-sdk-typescript#70 is an open feature request. Its own words: "once an agent begins executing a chain of tool calls, users cannot inject new messages until the run completes." The proposed (not-yet-shipped) API is session.send({ type: "user", message: {...} }).
• Empirical: writing a user message to stream-json stdin mid-turn is ignored — the active turn runs to completion (tested on claude 2.1.175; turn ran all steps, never picked up the injected message).
• Static: in the 2.1.175 binary, the steer tokens on the input side are unrelated (validationErrorSteer is a tool-validation field; useAISteeringComponent/steeringVarTable are bundled-lib symbols). No isSteering/steeringMessage field on the stream-json input schema.

The control protocol the binary does expose over stream-json is: interrupt, can_use_tool, set_permission_mode, set_model, set_max_thinking_tokens, mcp_message, hook_callback, initialize — none inject user content into a running turn. So the only programmatic proxy for Claude today is interrupt + resubmit (a soft interrupt; the interrupted turn's partial work stays in history).

Decision

• Implement Codex true steering via turn/steer (with activeTurnNotSteerable / expectedTurnId-race / version fallbacks back to queue-until-end).
• Defer Claude. When upstream ships session.send() (SDK [Windows] Remote Claude sessions spawned by daemon hang (no output) #70), wire Claude behind the same UI toggle. For now the web option is Codex-only.

Scope note discovered while wiring: session runtime config (e.g. collaboration mode) is synced web↔CLI via the hub's abbreviated-key path (collaborationMode travels as n), so steeringMode needs its own key mirrored through sessionCache/syncEngine/rpcGateway/handlers + a REST route, plus the CLI sessionBase keepalive runtime.