Stopping a Turn
Use session.stop() to abort current execution and clear input not yet absorbed by a Turn
session.stop() stops the currently running Turn and cancels queued input that has not yet been absorbed by that Turn.
const turn = await session.prompt({ query: "Run a long task" });
const stop_result = await session.stop(turn.id);
console.log(stop_result);
const result = await turn.finished;Target a recovered Turn
session.stop() is the host operation for stopping the current call. A targeted action captures the visible canonical message when clicked and sends both identities:
const { active_turn_id } = await session.status();
const page = await session.messages();
const message = [...page.items].reverse().find(item => item.role === "agent" && item.turn_id === active_turn_id);
if (active_turn_id && message) {
await session.stop(active_turn_id, { message_id: message.message_id, revision: message.revision });
}After Retry resumes the same Turn, a targeted Stop without a message checkpoint, with another message, or with a revision at or before the recovery checkpoint is rejected with turn_changed. Keep the checkpoint captured for that action; do not refresh it automatically after rejection. HTTP sends expected_turn_id and expected_message; RPC uses the same fields. Completion waits for resource cleanup. Old settled handles and callbacks retain their original result.
Return value
type AgentSessionStopResult = {
stopped: boolean;
turn_id?: string;
cancelled_queued_prompts: number;
reason: "stopped" | "idle";
};| Field | Meaning |
|---|---|
stopped | Whether an active Turn was stopped or queued input was cleared |
turn_id | The active Turn that was stopped; present only for an active Turn |
cancelled_queued_prompts | Number of inputs not yet assigned to a Turn |
reason | stopped, or idle when there was nothing to stop |
Input queue semantics
When users submit input consecutively, some input may already be merged into the current Turn as steering and some may still await the next Turn. Stop uses this boundary:
Input already absorbed by the current Turn -> stops with that Turn
Input still queued and not absorbed -> is cancelled and never starts automaticallySo a Stop button does not immediately start another execution because text remains in the queue. If a product must preserve a draft, keep it in UI draft state before calling stop() rather than relying on the SDK queue.
Background work and late results
Stopping Chat's current reply does not cancel a background Work Main it has already started. The Main's result can still be queued for asynchronous handling in the original Chat; this does not resume the stopped Chat Turn. To stop background work, explicitly call session({ action: "stop", args: { session_id: main_id } }). It cascades to that Main's Children while preserving history. Once the Main's original execution stops, late Child results or Shell completion notifications cannot wake it again.
Stopping takes effect at execution checkpoints, without a guarantee of immediately forcing model requests or synchronous tools to end.
Final state
A stopped Turn still settles turn.finished:
const result = await turn.finished;
console.log(result.success); // false
console.log(result.error); // usually Turn stoppedThe subscription also receives variant: "turn", type: "finish", status: "stopped". Never leave code awaiting finished suspended because a stop occurred.
Calling stop() on an idle Session does not throw. It returns stopped: false and reason: "idle", making a UI stop action idempotent.