Skip to content
Agentic Control Plane

The Cursor control model, explained

Cursor’s permissions.json has three optional top-level keys: terminalAllowlist, mcpAllowlist, and autoRun, whose allow_instructions and block_instructions arrays are plain-English sentences that steer the Auto-review classifier (full schema below). The file lives at ~/.cursor/permissions.json and <workspace>/.cursor/permissions.json. The two files’ arrays concatenate, and autoRun is read only in Auto-review mode.

Around that file sits a Run Mode (Auto-review, Allowlist, or Run Everything). Terminal commands need approval by default, but workspace file edits do not: they save to disk immediately.

Cursor’s controls changed more in 2026 than any other major harness’s. Yolo mode became Auto-Run, then Run Modes. Two modes were deleted in May. An LLM classifier became the recommended default a week later. The current model is coherent: an allowlist, a sandbox, and a classifier, stacked. But a lot of published advice describes versions that no longer exist. This page is the current reference for the 3.x era.

This page covers Cursor’s own controls. To wire ACP into Cursor, see the install guide.

The defaults, before any configuration

This surprises people: out of the box, terminal commands need approval but workspace file edits don’t. Edits save to disk immediately, and version control is your undo.

  • Reads and searches are free.
  • MCP tool calls prompt one by one unless allowlisted.
  • The agent can’t make arbitrary network requests (a few providers are permitted).
  • Three protections always prompt, whatever the mode: browser actions, file deletion, and writes outside the workspace.
  • Under the sandbox, a short list of paths is deny-write: .git/config, .git/hooks, .vscode, .cursorignore. The harness protects its own steering files.

Run Modes: the three-layer stack

Since 3.6 (May 2026), the permission posture is a Run Mode:

  1. Auto-review (recommended default). Allowlisted calls run. Other shell commands run sandboxed where possible. Whatever is left goes to an LLM classifier (a small Cursor-managed model) that returns allow, try-something-different, or ask-the-human. It covers shell, MCP, and fetch.
  2. Allowlist: listed actions run, everything else prompts. No classifier; the sandbox is optional.
  3. Run Everything: everything auto-runs, with no sandbox, no classifier, no prompts. The escape hatch as a mode.

Two modes were removed in 3.5: “Ask Every Time” (now an Allowlist with an empty list) and “Run in Sandbox” (folded into Allowlist). Old advice often refers to both.

The configuration is new, for better and worse. permissions.json (in ~/.cursor/ and per project, with a team dashboard layer above both) takes allow_instructions and block_instructions as natural-language sentences, not command patterns. The full schema, with examples, is below. It is flexible and easy to read, and it is probabilistic at the point where most systems are deterministic. Cursor’s docs say so directly: “The allowlist is best-effort, not a security boundary. Determined agents or prompt injection might bypass it.”

History backs that up. Three published CVEs bypassed the allowlist: command substitution (CVE-2025-54131), environment-variable poisoning and shell built-ins (CVE-2026-22708), and web-content prompt injection chained into auto-execution (CVE-2026-31854). All are patched. The lesson is the class of bug, and every string-matching permission system teaches it.

One more line to remember: .cursor/rules files steer the model’s behavior. They are not enforcement. Rules are prompts; Run Modes, permissions.json, sandbox.json, and hooks are the controls.

permissions.json reference: autoRun, allow_instructions, block_instructions

This is the file behind Run Modes. Everything here is checked against Cursor’s own permissions.json reference and the Run Modes docs as of 2026-11-07. The file has changed before and will again, so confirm a detail upstream before you rely on it.

Where it lives

~/.cursor/permissions.json              # per-user — applies in every workspace
<workspace>/.cursor/permissions.json    # per-repo — commit it so the team gets the same rules

Both files are optional. They load at startup and are re-read when they change. JSONC comments are accepted, unrecognized keys are ignored, and non-string entries inside an array are silently dropped. Team admins can set the same lists in the dashboard, and when they do, both files are ignored. The Cursor CLI has its own permissions system; this file is the editor’s.

The schema

Three top-level keys, all optional. The top level is camelCase; the two keys inside autoRun are snake_case.

Key Type What it does
terminalAllowlist string[] Terminal commands that run without approval. Prefix match, case-sensitive: git matches git status but not gitk; git status is narrower; npm:install* uses the colon to split the command from an args glob.
mcpAllowlist string[] MCP tools that run without approval, written server:tool. Case-insensitive; * wildcards either half (github:*, *:list_issues, *:*) and globs work inside names (my-server:list_*). An entry with no colon is skipped.
autoRun object Natural-language steering for the Auto-review classifier. Read only in Auto-review mode; no effect in Allowlist or Run Everything.
autoRun.allow_instructions string[] Sentences describing call shapes the classifier should lean toward allowing.
autoRun.block_instructions string[] Sentences describing call shapes it should lean toward blocking: an approval prompt surfaces, or the agent picks another path.

The key is autoRun, not autorun. A misspelled key isn’t an error; it’s a key that does nothing.

Examples

Deterministic allowlists. A defined key replaces the matching list in Cursor Settings entirely:

{
  "mcpAllowlist": [
    "github:*",
    "linear:*",
    "notion:search"
  ],
  "terminalAllowlist": [
    "git",
    "npm",
    "cargo build",
    "cargo test"
  ]
}

Steering the Auto-review classifier. Each entry is a plain sentence, written the way you’d brief a teammate:

{
  "autoRun": {
    "allow_instructions": [
      "Read-only inspections of build artifacts under ./dist are fine."
    ],
    "block_instructions": [
      "Every AWS CLI command should go through approval first.",
      "Every command that modifies Kubernetes resources should go through approval first."
    ]
  }
}

Per-user plus per-repo. The arrays inside every field concatenate, so a repo layers its own guardrails on top of your defaults:

// ~/.cursor/permissions.json
{
  "terminalAllowlist": ["git", "npm", "pnpm"],
  "autoRun": {
    "block_instructions": ["Anything that touches my SSH config or shell rc files."]
  }
}

// <workspace>/.cursor/permissions.json
{
  "terminalAllowlist": ["cargo build", "cargo test"],
  "autoRun": {
    "block_instructions": ["Never run database migrations against the production schema in this repo."]
  }
}

// effective
{
  "terminalAllowlist": ["git", "npm", "pnpm", "cargo build", "cargo test"],
  "autoRun": {
    "block_instructions": [
      "Anything that touches my SSH config or shell rc files.",
      "Never run database migrations against the production schema in this repo."
    ]
  }
}

Precedence

team admin (dashboard)  >  permissions.json (per-user ∪ per-repo)  >  Cursor Settings UI
  • Dashboard wins outright. When a team configuration applies, neither file nor the Settings list can add entries.
  • Between the two files, arrays concatenate. Per-user and per-repo entries combine rather than replace each other.
  • Against Settings, a defined key replaces. The matching section of Cursor Settings turns read-only and the add button disappears.
  • A missing file, an unparseable file, or an absent key falls back to Settings. A key that is present but resolves to an empty array does not: the effective allowlist is empty.
  • The three areas are independent. Define only mcpAllowlist and the terminal list and autoRun stay under Settings control.
  • A Run Mode has to be on. Before 3.5, the deprecated Ask Every Time mode ignored allowlists.

What it enforces and what it steers

The two allowlists are deterministic pattern matches. autoRun is a hint to a model. Cursor’s reference says so directly. A call matching allow_instructions “still goes through the safety check,” a call matching block_instructions “can still be approved when Cursor insists,” and the instruction is to “treat both as steering, not enforcement.” The page’s own notes header reads “Not a security boundary.”

So permissions.json is the right place for a convenience and the wrong place for a rule that has to hold. A rule that has to hold goes in the sandbox, a deny, or a failClosed: true hook on beforeShellExecution or beforeMCPExecution. The hooks section and our Cursor hooks reference cover that deterministic seam. It is what runtime authorization means: a per-call check the caller can’t talk its way past.

The sandbox

The sandbox is real OS-level enforcement: Seatbelt on macOS, Landlock plus seccomp on Linux (kernel 6.2+), and on Windows the Linux sandbox inside WSL2. There is no native Windows boundary. The bounds are workspace read/write, network blocked by default, /tmp writable, and the steering-file deny-writes above.

sandbox.json (user and project, project wins, admin layer above) extends readable and writable paths and network domains. The default network mode adds the common package registries. Commands that can’t be sandboxed (outside-workspace writes, privileged operations, network needs) go to the classifier or the human instead of running unconfined.

The hooks

Cursor has a rich event set: preToolUse/postToolUse, beforeShellExecution/afterShellExecution, beforeMCPExecution, beforeReadFile/afterFileEdit, subagent and session lifecycle, and prompt-submit. There are four config layers (enterprise MDM, team cloud, project, user). All matching hooks run, and the higher layer wins conflicts.

Output can return permission: allow | deny | ask, with one documented catch. ask is fully honored only for beforeShellExecution and beforeMCPExecution. On preToolUse it is accepted by the schema but not enforced. Exit code 2 blocks, as in Claude Code, which is the hook-contract convergence again.

The default to design around: failClosed defaults to false. A crashed or slow hook fails open unless you set it, hook by hook. If a hook is your enforcement, set it, and know what you’ve chosen for when the hook’s backend is unreachable.

The record

An older version of this page said Cursor’s audit log was enterprise-only. That was wrong: no native per-tool-call audit log exists on any tier. The enterprise dashboard is usage and spend analytics. The docs’ own suggestion is to build an audit trail with hooks. So in the default mode, where a classifier makes allow decisions, the decisions with the least explanation also have the least record.

Cloud agents and the empty chair

Cursor’s cloud agents (formerly background agents) are the clearest empty-chair case in the ecosystem. They don’t use Run Modes and auto-run everything, inside an isolated VM with egress allowlists, and deliver a branch and draft PR. That design is defensible: the VM contains the blast radius and PR review contains the output. But there is no per-action policy and no per-action record. The control is the box and the review.

The CLI carries the same posture into scripts. -p (print mode) gets “access to all tools, including write and shell,” and --force (alias: --yolo) auto-allows anything not explicitly denied. The empty-chair test is the checklist to run before either.

Where the native model ends

Cursor’s stack (allowlist, then sandbox, then classifier) is a reasonable answer to approval fatigue, and the sandbox work is solid. What it leaves out:

  • Probabilistic at the boundary. Natural-language instructions and a classifier verdict are judgment, not rules, and Cursor says so. Anything that must hold needs the sandbox, a deny, or a fail-closed hook.
  • No record at all. Among the big three, Cursor alone has no native per-action audit log. The classifier’s allows vanish into the session.
  • Config sprawl. permissions.json, sandbox.json, hooks.json and rules are four files with different semantics (two enforcing, one advisory, one mixed), per user, per project, per machine.
  • The unattended tier skips policy. Cloud agents trade per-action control for VM walls.

What we’d do: keep the sandbox and the classifier for what they do well, which is fatigue and containment. Put deterministic policy and the missing record on the hook seam. Our integration carries the same workspace rules to Cursor as to the other harnesses we cover, and writes the per-action ledger Cursor doesn’t have.

Two settings are yours to make:

  • Fail mode. We install the Cursor hook without failClosed, so it fails open, and the hook itself fails open unless you put closed in ~/.acp/failmode. Set failClosed: true on the hook if you want a gateway outage to block calls.
  • Asks. Cursor does not enforce ask on preToolUse, so on Cursor an ACP ask may not reach you as a prompt. Treat it as allow or deny, and rely on the console for approvals.

Frequently asked questions

permissions.json autorun allow_instructions block_instructions: is the key autorun or autoRun?

autoRun, camelCase, at the top level of permissions.json. The two arrays inside it are snake_case: allow_instructions and block_instructions. Cursor ignores unknown keys, so a lowercase autorun is not an error; it is a key that does nothing.

Do allow_instructions and block_instructions work outside auto-review?

No. Cursor’s permissions reference says autoRun instructions are only consulted in Auto-review mode and have no effect in Allowlist or Run Everything. Even in Auto-review they steer the classifier: a call matching allow_instructions still goes through the safety check, and Cursor says to treat both as steering, not enforcement.

cursor permissions.json: where does it live and how do the files merge?

At ~/.cursor/permissions.json (per user) and <workspace>/.cursor/permissions.json (per repo). Both are optional and accept JSONC comments. When both exist, the arrays inside every field concatenate; a defined key replaces the matching list in Cursor Settings; a team admin dashboard configuration overrides both files.

What is the schema of Cursor's permissions.json?

Three optional top-level keys. terminalAllowlist is a string array of command prefixes that run without approval (git, npm:install*). mcpAllowlist is a string array of server:tool patterns, with * as a wildcard on either side. autoRun is an object with allow_instructions and block_instructions, each a string array of plain-English sentences that steer the Auto-review classifier. The key is autoRun (camelCase); the two inside it are snake_case. It lives at ~/.cursor/permissions.json (per user) and <workspace>/.cursor/permissions.json (per repo); both load and their arrays concatenate. The two allowlists are deterministic pattern matches; autoRun only applies in Auto-review mode and Cursor’s docs say to treat it as steering, not enforcement.

How do permissions work in Cursor's agent?

Through Run Modes (Cursor 3.6+). Auto-review, the recommended default, runs allowlisted calls, sandboxes other shell commands where possible, and sends the rest to an LLM classifier that decides allow, try-different, or ask. Allowlist runs listed actions and prompts for the rest. Run Everything auto-runs with no sandbox, classifier, or prompts. Whatever the mode, some actions always prompt: browser actions, file deletion, and writes outside the workspace. By default terminal commands need approval, but workspace file edits do not; they save to disk immediately.

Are Cursor rules (.cursor/rules) a security control?

No, and Cursor says so: rules steer the prompt, they don’t constrain execution. Enforcement lives in Run Modes, permissions.json, sandbox.json, and hooks. Cursor’s docs also say the allowlist is best-effort rather than a security boundary, and three published CVEs bear that out: allowlists were bypassed via command substitution, environment-variable poisoning, and prompt injection chained with allowlist defeat.

Does Cursor keep an audit log of what the agent did?

No native per-tool-call audit log exists on any tier. The enterprise dashboard covers usage and spend analytics, not action audit. The documented path to an audit trail is to build one with hooks, which is the seam a control layer fills.

What happens to approvals in Cursor's cloud agents?

Cloud agents don’t use Run Modes at all. They auto-run everything, bounded by VM isolation and network egress allowlists, and deliver output as a branch and draft PR. Nobody is there to ask, so everything is approved inside a VM: the blast radius is contained, but there is no per-action policy and no per-action record.

How do I turn on Cursor yolo mode?

Yolo mode is now the Run Everything Run Mode: everything auto-runs with no sandbox, no classifier and no prompts. Since Cursor 3.6 (May 2026) the permission posture is a Run Mode, and Auto-review is the recommended default.

Which Cursor agent actions always ask for approval?

Browser actions, file deletion, and writes outside the workspace prompt in every Run Mode. Under the sandbox a short list of paths is also deny-write: .git/config, .git/hooks, .vscode and .cursorignore.

Running Cursor? One command adds a hook. Each tool call it sees is recorded, and a force-push, destructive SQL or curl | sh is blocked until you approve it on the console or from the email.

macOS · Linux · WSL
curl -fsSL https://agenticcontrolplane.com/install.sh | bash
Windows · PowerShell
irm https://agenticcontrolplane.com/install.ps1 | iex

What the installer writes  ·  Cursor guide  ·  free up to 5 agents