Cursor SDK: Custom Tools, JSONL Stores, and Nested Subagents
CursorCursor's June 4 SDK update significantly expands what developers can build with programmatic agents. The TypeScript and Python SDKs now support custom tool definitions that agents invoke through the built-in MCP server, flexible storage backends including JSONL files and custom implementations, and deeply nested subagents that can spawn additional subagents to unlimited depth. Auto-review controls are also extended to SDK-driven runs, giving developers the same approval-gating workflow available in the Cursor desktop app.
Sources & Mentions
2 external resources covering this update
Custom Tools
Cursor SDK agents can now be extended with developer-defined tools. By passing function definitions through local.customTools on Agent.create() or per send() call, the SDK exposes them to the agent through a built-in MCP server called custom-user-tools. Custom code is called through the same routing and permission gates as any other MCP tool, with no need to stand up a separate stdio or remote HTTP MCP server.
Custom tools are inherited by all subagents of the parent agent. A tool defined once at the top level is available throughout the entire run tree, reducing the overhead of replicating tool configurations across nested agents.
JSONL Stores and Custom Storage Backends
The SDK previously stored agent state in SQLite by default. The June 4 update adds JSONL stores as a first-class option. JSONL files are plain, append-only, and human-readable, making them well suited for version control and debugging. Both SqliteLocalAgentStore and JsonlLocalAgentStore are exported directly from the package.
Developers who need more control can implement the public LocalAgentStore interface and pass a custom backend. Common use cases include in-memory stores for ephemeral CI runs or Postgres-backed persistence for applications that keep agent state alongside the rest of their data.
Nested Subagents
Subagents can now spawn their own subagents to unlimited depth, with each level maintaining its own prompt and model configuration. A reviewer subagent can delegate to a test-writer, which can delegate further, creating arbitrarily deep agent trees for complex workflows. This works automatically: subagent sessions register the executor needed to call Task without any additional configuration.
Auto-Review for SDK Runs
The local.autoReview setting routes tool calls through Cursor's auto-review classifier instead of running them automatically. Developers configure behavior through permissions.json with allow_instructions and block_instructions fields, giving the classifier guidance on which operations should proceed or pause for approval. This brings the same human-in-the-loop gating available in the Cursor desktop app to SDK-driven agent pipelines.
Python SDK and Reliability Improvements
The Python SDK ships as version 0.1.6, adding workspace-scoped list_runs and clearer error messaging with analytics tracking. Additional reliability improvements across both SDKs include run correlation via platform-generated requestId, improved wait() behavior for local runs, HTTP/1.1 streaming support for cloud agents, lighter imports that defer local agent stack loading, self-contained TypeScript type definitions, and bundled ripgrep for shell runs.