Cursor

This page is for an agent connecting a team's Cursor to Zaun. Cursor is covered through its hooks, which can stop a prompt, a shell command, an MCP call or another tool before it runs, and also record what the agent did. If you are the person, you deploy one system hooks file per machine, or team hooks from the Cursor dashboard, and decide whether a hook failure should block.

Deploy the hooks file#

The console generates the hooks file and the forwarder for your project. Write the file to Cursor's system hooks location:

On Cursor Enterprise, the same hooks can instead be distributed from the Cursor web dashboard. Either way the hook commands run the forwarder on each machine, so install the forwarder and its configuration file on every machine too.

Block with hooks#

Cursor hooks run commands, so the forwarder ships with the hooks file. It sends each check to Zaun and answers Cursor in its own form for each event: continue: false stops a prompt, and permission: deny stops a tool, shell command or MCP call.

{
  "version": 1,
  "hooks": {
    "beforeSubmitPrompt": [{"command": "python3 <MANAGED_DIR>/zaun_hook.py", "failClosed": false}],
    "preToolUse": [{"command": "python3 <MANAGED_DIR>/zaun_hook.py", "failClosed": false}],
    "beforeShellExecution": [{"command": "python3 <MANAGED_DIR>/zaun_hook.py", "failClosed": false}],
    "beforeMCPExecution": [{"command": "python3 <MANAGED_DIR>/zaun_hook.py", "failClosed": false}]
  }
}

• <MANAGED_DIR> is the administrator-owned directory that holds the forwarder and its configuration file. The configuration file carries the endpoint and the key. On Windows the generated command uses the Windows path and launcher.
• The commands shown run the forwarder as a Python 3 script. Use the commands in the console's generated file, which match the forwarder it ships. When the forwarder is the Python script, every machine needs Python 3; without it the hook fails, and with failClosed: false the action goes ahead.
• beforeSubmitPrompt checks the prompt, preToolUse checks tool calls, beforeShellExecution checks shell commands, and beforeMCPExecution checks MCP tool calls, each before it runs.
• Hooks apply the same verdict as the API. Today a tool call is blocked by input checks such as the test string; a threat Hex v1.3 finds only in the agent's own tool calls normally raises an alert instead. See what blocks today.
• The prompt hook does not run in the headless cursor-agent CLI. The tool hooks do.

When Zaun cannot be reached

The generated hooks set failClosed: false: if the forwarder fails or times out, the action goes ahead. This is deliberate. These hooks run on nearly every agent action, so with failClosed: true any failure of the hook process, such as a missing Python after an OS update or an unreadable configuration file, would stop every agent on the fleet at once, for a reason unrelated to security. If the person wants fail closed anyway, set failClosed: true on the hooks that matter most, such as beforeShellExecution, and test the failure first.

The proof to show#

On a machine with the hooks file in place:

1. Type the test string ZAUN-TEST-VIOLATION-7f3a9c from Try it into Cursor's agent. The prompt is stopped with Zaun's reason.
2. Ask the agent to create a file whose content is ZAUN-TEST-VIOLATION- followed directly by 7f3a9c. The prompt does not contain the whole string, so it passes; the file write carries it and is denied.

Both appear on Violations.