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";
};
FieldMeaning
stoppedWhether an active Turn was stopped or queued input was cleared
turn_idThe active Turn that was stopped; present only for an active Turn
cancelled_queued_promptsNumber of inputs not yet assigned to a Turn
reasonstopped, 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 automatically

So 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 stopped

The 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.