Cursor SDK 1.0.31 adds live steering and reliable subagent results

Cursor released version 1.0.31 of the npm package @cursor/sdk and the PyPI package cursor-sdk. The update lets applications redirect an agent during an active turn, collect delayed subagent results, describe tool behavior to the model, and replace the main system prompt.

The new controls address several orchestration problems: correcting an instruction without cancelling active work, preserving results after a parent turn finishes, and giving models risk metadata before they select tools. Most capabilities target local TypeScript agents, while background subagent reporting also supports local Python agents.

Support splits by runtime

Steer the turn in flight

run.steer(text) injects a new instruction into the active agent turn without cancelling that turn or discarding its state. The method resolves with one of two delivery results:

• complete_delivered means the instruction reached the active turn.
• revert_to_followup means the application should queue the instruction as a normal follow-up turn.

Applications should branch on that result instead of assuming the instruction was delivered. Cloud runs always return revert_to_followup, allowing the same fallback path to handle unsupported steering.

When a foreground subagent is active, steering moves that subagent into the background so it can continue working while the parent agent processes the new instruction. A user can redirect the parent without waiting for a long-running subtask to finish.

Background work reports back

Background subagent output could previously disappear when the parent turn ended. Version 1.0.31 returns the completed subagent result to its parent as a follow-up turn on the same run.

run.stream() continues yielding events through those follow-up turns, and run.wait() resolves after they finish. Code that launches several parallel subtasks can therefore use one wait operation to cover the parent turn and the resulting subagent reports.

Integrations that treated the end of the initial parent turn as final completion should keep consuming the stream until the run closes. The broader lifecycle can produce additional turns and a longer wait than earlier SDK versions.

Tool hints need hard guardrails

Custom tools now accept an annotations field that forwards Model Context Protocol metadata to the model. Supported fields include:

• title for a human-readable tool name
• readOnlyHint for tools expected to avoid state changes
• destructiveHint for tools that may overwrite or delete data
• idempotentHint for operations designed to tolerate repeated calls
• openWorldHint for tools that may interact with external systems

The model can use these signals when choosing and calling tools, including reasoning about side effects and repeatability. The annotations remain advisory metadata; the SDK does not enforce the described behavior.

Applications should enforce authorization inside tool handlers, expose only approved tools, and block prohibited tools with disallowedTools, which arrived in version 1.0.27. Tool annotations should never serve as a security boundary.

Replace the main-loop prompt

The new systemPrompt option on Agent.create() replaces Cursor’s built-in system prompt for the main agent loop. Cursor continues loading rules, skills, and tool schemas, while subagents retain their own prompts.

Custom prompt access applies to local TypeScript agents and is enabled per account. Resumed agents require the option again on Agent.resume(), so applications should persist the prompt with the run configuration and restore it during resume flows.

Cursor tracks the full release history in the SDK changelog.