Cursor SDK can steer an agent mid-run

run.steer(text) lets a local TypeScript agent accept new input during a turn. If a foreground subagent is working, Cursor moves it to the background so it can continue while the parent handles the steering message. Cloud runs return revert_to_followup, so callers must send a normal follow-up instead.

Key facts

• Cursor announced the SDK steering feature at 16:08 UTC on 2026-10-05.
• The SDK changelog lists steering, background subagent returns, custom-tool annotations, and systemPrompt under version 1.0.31 dated 2026-09-03.
• run.steer(text) returns complete_delivered when the message reaches the active turn and revert_to_followup when the caller should send it as a normal follow-up.
• Background subagent results return to the parent as follow-up turns on the same run. run.stream() continues through those turns and run.wait() resolves after them.
• Background subagent return turns work for local TypeScript and Python agents. Steering and systemPrompt are limited to local TypeScript agents.
• Custom tools can carry MCP annotations such as readOnlyHint and destructiveHint. The SDK passes them to the model as descriptive hints and does not enforce them.
• The npm package reached @cursor/sdk@1.0.36 at 16:38:15 UTC on 2026-10-05. The PyPI package reached cursor-sdk 1.0.36 at 16:29:10 UTC on the same date.

How Cursor SDK steering works

Call run.steer() on the handle returned by agent.send(). The two outcomes tell the caller whether it still owns the message. complete_delivered means the caller can drop its copy. revert_to_followup means the turn ended or the runtime cannot inject the message, so the caller should queue a new turn with agent.send().

const run = await agent.send("Refactor the migration and run its tests");

const outcome = await run.steer("Stop the tests and fix schema syntax first");

if (outcome === "revert_to_followup") {
  await agent.send("Fix schema syntax first");
}

The public type in @cursor/sdk@1.0.36 is a two-value union:

type SteerAckOutcome = "complete_delivered" | "revert_to_followup";

The result is a delivery decision, not a statement that the agent completed the new task. The caller still needs to observe the run and handle its final result.

When a foreground subagent is running, steering changes that subagent to a background task. The subagent keeps working while the parent processes the new input. That lets an orchestrator change the parent's priority without discarding the subagent's work.

The documented support boundary is local TypeScript. A cloud run returns revert_to_followup, so a cloud orchestrator must wait for the active turn and then call agent.send().

How Cursor SDK returns background subagent results

The 1.0.31 changelog says a background subagent's result returns to its parent as a follow-up turn on the same run. The result is no longer dropped when the parent turn ends.

The run lifecycle is:

1. The parent starts a background subagent.
2. The parent turn may finish while that subagent continues.
3. The subagent result returns to the parent as a follow-up turn.
4. run.stream() continues yielding through the return turn, and run.wait() resolves after the background work finishes.

This return behavior is available for local agents in both TypeScript and Python. It is separate from live steering. Python can receive background-subagent results, but the changelog does not list Python as a steering runtime.

Cursor SDK systemPrompt and custom-tool annotations

Cursor SDK systemPrompt

Passing systemPrompt to Agent.create() replaces Cursor's built-in system prompt for the main agent loop. Rules, skills, and tool schemas still load, and subagents keep their own prompts. Cursor enables access per account. The option applies to local TypeScript agents, and callers must pass it again when they call Agent.resume().

Cursor SDK custom-tool annotations

An entry in local.customTools can include annotations with these fields:

interface SDKToolAnnotations {
  title?: string;
  readOnlyHint?: boolean;
  destructiveHint?: boolean;
  idempotentHint?: boolean;
  openWorldHint?: boolean;
}

These values describe a tool to the model. They do not block a destructive call or enforce idempotency in the SDK. The changelog lists custom-tool annotations for TypeScript only.

Cursor SDK release timeline

The feature documentation and package registry therefore use different version signals. The changelog heading is 1.0.31, while the npm and PyPI registries show 1.0.36 as the package published on 2026-10-05.

Sources

• Cursor on X, announcement thread: https://x.com/cursor_ai/status/2107141004482793827 (read 2026-10-06)
• Cursor SDK changelog: https://cursor.com/docs/sdk/changelog (read 2026-10-06)
• npm registry metadata for @cursor/sdk: https://registry.npmjs.org/@cursor/sdk (read 2026-10-06)
• PyPI registry metadata for cursor-sdk: https://pypi.org/pypi/cursor-sdk/json (read 2026-10-06)
• Cursor Community Forum, cloud steering request: https://forum.cursor.com/t/cloud-agents-api-sdk-mid-run-steer-parity-with-cursor-com-agents-ui/171670 (read 2026-10-06)

Last verified: 2026-10-06.