Cursor permissions.json autoRun schema: allow_instructions, block_instructions, local.customTools, and nested subagents

Cursor's June 4 SDK release looks, at first glance, like a quality-of-life bundle: custom tools, an auto-review classifier, a JSONL persistence store, nested subagents, and a fistful of reliability fixes. The practical operator question is narrower: how should a team configure .cursor/permissions.json so autoRun.allow_instructions and autoRun.block_instructions govern local.customTools safely without hiding cost, audit, or nested-subagent risk? Cursor SDK 0.1.6 collapses MCP plumbing, approval gating, and run observability into first-class SDK primitives, so the policy file now matters as much as the agent code.

What shipped in Cursor SDK 0.1.6

Five changes carry the most operator weight:

• Custom tools via built-in MCP. local.customTools now lets you hand the agent function definitions on Agent.create() or per send(). The SDK exposes them through a built-in MCP server called custom-user-tools, so the model calls your code through the same path and the same permission gate as any other MCP tool. The custom tools are also visible to every subagent of a parent agent.
• Auto-review with natural-language allow/block. Headless local agents previously ran tool calls without asking, because there was no human in the loop. local.autoReview now routes those calls through a classifier instead. You steer the classifier with autoRun.allow_instructions and autoRun.block_instructions in permissions.json — natural-language rules like "Read-only inspections of build artifacts under ./dist are fine" or "Always pause delete operations so I get a chance to review them." For searchers looking for the permissions.json autorun schema, the important shape is the pair of allow/block instruction lists that decide whether a proposed tool call can proceed without a person.
• JSONL and pluggable persistence. Agent and run metadata used to land in SQLite. You can now opt into JsonlLocalAgentStore (plain append-only file you can diff and commit) or implement the public LocalAgentStore interface for anything else — in-memory for ephemeral CI, Postgres for production parity.
• Nested subagents to any depth. Subagents can spawn their own subagents, each with its own prompt and model. There's no feature flag — a subagent session registers the executor it needs to call Task, so nesting works automatically.
• requestId correlation and reliability fixes. Every send() now carries a platform-generated requestId exposed on Run and RunResult and persisted across all three stores. Cloud agent sessions stream correctly on HTTP/1.1 transports. wait() no longer resolves before the terminal result is written. Local shell uses bundled rg so PATH doesn't get clobbered on Windows.

A minimal policy shape now has to be explicit enough for code review, not just for the classifier. The exact schema belongs to Cursor, but the operational intent should read like this:

{
  "autoRun": {
    "allow_instructions": [
      "Allow read-only inspections of repository files and build artifacts under ./dist.",
      "Allow local.customTools that only format, lint, or summarize files in this workspace."
    ],
    "block_instructions": [
      "Pause before deleting files, modifying git history, or changing credentials.",
      "Pause before any custom tool calls production systems, billing data, customer data, or external deploy APIs."
    ]
  }
}

The important part is not the JSON example; it is the boundary. allow_instructions should describe boring, reversible, local work. block_instructions should name the irreversible or externally visible work that must go through a human or a gateway-mediated MCP server.

There's also a small but loud line under "Models": scripts still pinning the retired composer-2 slug are silently routed to Composer 2.5. That is a vendor-managed model migration, not a deprecation window, and it lands on the same release as the new auto-review classifier — both are Composer 2.5 territory.

Why it matters for AI engineering teams

Until 0.1.6, productionizing a Cursor local agent meant duct-taping three things together: an external MCP server to expose internal tools, a thin wrapper around the agent to gate destructive calls, and either a custom store or careful SQLite handling so multi-process orchestration didn't lose state. Each one was a small project. Each one was also a different audit boundary.

This release moves all three inside the SDK:

• Custom tools = MCP without standing up an MCP server. Before, "let the agent run our internal lint config" meant a stdio MCP server, a process supervisor, and a permission entry. Now it's a function definition. The MCP layer is still there — it's just embedded — which means the same allow-list, the same tool naming conventions, and the same audit surface as remote MCP tools.
• Auto-review = governance you can read. Natural-language rules in permissions.json are reviewable, diff-able, and code-review-able by people who don't write Cursor SDK code. A security or platform team can own block_instructions without owning the agent script. The trade-off is real: a classifier is doing the call, and "classifier said yes" is a different audit story than "human said yes."
• JSONL + requestId = an observability contract. Append-only JSONL is grep-able, diff-able, and shippable to log pipelines. requestId makes it possible to tie a single send() call to backend logs, analytics, and support threads across the in-memory, SQLite, and JSONL stores. For teams that have been hand-rolling correlation IDs into agent runs, this is a meaningful contract upgrade.
• Nested subagents = a routing-tree question. "Reviewer delegates to test-writer delegates further" is exactly the multi-level orchestration pattern that has been quietly inflating token costs in coding-agent fleets. Each level can pick its own model, which means there is now a real routing policy decision per layer of nesting, not just per top-level agent.

The permissions.json and routing-operator angle

If you operate an AI gateway, an internal coding-agent fleet, or both, the SDK release pushes a few decisions you can't postpone much longer.

1. Decide which custom tools are SDK-local vs. gateway-mediated. The built-in custom-user-tools MCP server runs inside the agent process. That's fine for tools that touch local files. It's not fine for tools that hit production systems — those should still flow through your gateway so you keep central authentication, rate limiting, and audit. Use local.customTools for repo-local capabilities; keep production system calls behind a remote MCP server that your gateway sees.
2. Treat permissions.json as policy-as-code. autoRun.allow_instructions and autoRun.block_instructions are natural-language and easy to underestimate. Check them into the same repo as the agent, code-review them like config, and consider a CI check that fails when block instructions are deleted. If your platform team owns sandbox policy elsewhere (Claude Code's availableModels, Codex's sandbox profiles), align the wording so an engineer sees the same intent regardless of tool.
3. Add a CI guard for the risky lines. A useful first check is simple: fail when autoRun.block_instructions disappears, when a broad allow rule mentions deploys or customer data, or when a new local.customTools definition has no owner label. This will not prove the classifier is safe, but it prevents the most common drift: a helpful engineer loosens policy so a demo stops pausing.
4. Pin a store strategy per environment. SQLite is the default; JSONL is the audit-friendly one; custom stores let you land state in Postgres or an existing event log. The right call depends on whether you need cross-process visibility (Postgres), cheap durable logs (JSONL), or fast local resume (SQLite). Pick deliberately — don't let it default per-machine.
5. Make requestId your correlation primitive. Wire Run.requestId into every log line, billing event, and support escalation around Cursor SDK agents. If you already issue gateway request IDs for non-SDK traffic, decide which one is canonical and how they map. The cheapest time to do this is now, before scripts and dashboards have grown their own correlation conventions.
6. Audit nested-subagent depth. "Any depth" is the wrong default for most teams. Add a wrapper around Agent.create() that enforces a maximum nesting level, attributes per-level token spend separately, and refuses to spawn at a level your routing policy doesn't have a model assignment for. Otherwise the cheapest model in your fleet ends up doing the most work, and the most expensive one ends up reviewing it five levels deep.
7. Notice the Composer 2 → Composer 2.5 silent route. Any inventory pass should flag SDK clients still requesting composer-2. They're getting Composer 2.5 today by vendor courtesy, not by contract. Roll those pins forward in your client code so a future routing rule change doesn't surprise you.

The broader signal: coding-agent vendors are pulling MCP, approval policy, and observability into their SDKs. That's good for individual developers and a quiet pressure on AI gateways to do more than route — to be the place where tool inventories, approval policies, and run correlation come together across Cursor, Claude Code, Codex, and whatever ships next.

permissions.json audit checklist for TheRouter users

If you already route Cursor traffic through TheRouter, the immediate audit is straightforward: list every local.customTools definition in your repo, map each one to either "local-only" or "must traverse the gateway," and move the production-touching ones behind a remote MCP server the gateway can see. Then open .cursor/permissions.json and verify that autoRun.allow_instructions only covers reversible local work while autoRun.block_instructions names deletes, credential changes, production systems, billing data, customer data, deploy APIs, and broad external side effects. The longer-term move is to treat permissions.json, availableModels, and your gateway's allow-list as one logical policy expressed in three places — and to wire requestId into your billing and incident pipelines so a single SDK send() is traceable end-to-end. As nested subagents become normal, the routing layer's value is increasingly in attributing cost and enforcing depth, not just picking the right model for the top of the tree.