The problem: handing over a whole task without losing control of it
Imagine writing to Cursor's Agent "add pagination to the orders list" and finding, a few minutes later, many files
changed, a new dependency in package.json and a test that used to pass and has now been rewritten. The
work may even be good, but you cannot tell, because you had not said what it was supposed to touch or how you would
verify that it was finished. The Agent is the tool that makes the editor work "with one command": the difference between a
useful result and an afternoon of review lies almost entirely in three decisions you make before, during and after
its work. Before, how you describe the task. During, which actions it can take without asking your permission. After,
how you check that it did only what you had asked.
Here I explain all three on the official documentation read on 2026-11-13, with two tools that I wrote and ran: a perimeter check on the changes and a permissions file. Cursor was not installed on the machine I am writing on: what happens inside the editor is described by the documentation and I did not try it. If you do not know tools and modes yet, first read the opening guide and the one on project rules, which I take as known here.
What the Agent is, according to the documentation
According to the documentation, an agent is made of three components: the instructions, that is the system prompt plus your rules, the tools to search and edit code and run commands, and the model you choose for the task. Cursor optimises instructions and tools for every supported model. The point that matters to anyone working is that the agent does not guess the content of files: it searches for them and reads them, applies the changes, runs the commands in the terminal and reads the result, can ask you questions while it keeps working and, in the cases that call for it, uses a browser to try out an application. The same page states that there is no limit on the number of tool calls in a task: a vague task can therefore run for a long time, which is one more reason to define it well.
For tasks that require a lot of searching, the Agent can start subagents, each with its own context window. The exploration one searches the code with a faster model and runs many searches in parallel, returning only the conclusions to the main agent; the browser one filters out the noise of screenshots. The stated advantage is context: voluminous searches do not fill the main conversation. You can explicitly ask it to use them, for example "use a subagent to find all the places where we validate input". Background agents and long plans are the subject of the fourth article.
Before starting: a clean tree and a verifiable task
An Agent change lands on disk immediately, except for configuration files, which ask for consent.
If before starting you have uncommitted changes of your own, in the diff you can no longer tell your work from the agent's.
The first move is therefore a clean working tree, and the second is knowing what you expect to
find afterwards. The tool that follows automates both: with the before command it refuses to
continue if there are modified files, with the after command it lists the changed files and flags those outside
a perimeter that you declare with patterns. It uses git status --porcelain, the format that Git
defines as stable across versions and suited to scripts, and glob.translate for the patterns.
"""Perimeter check before and after a task handed to an agent.
before: exits with 1 if the working tree is not clean.
after: lists the changed files and flags those outside the allowed paths.
"""
import glob
import re
import subprocess
import sys
def git(*args):
return subprocess.run(["git", *args], capture_output=True, text=True, check=True).stdout
def changed():
lines = git("status", "--porcelain", "--untracked-files=all").splitlines()
return [(r[:2].strip() or "?", r[3:]) for r in lines]
def allowed(path, patterns):
return any(re.fullmatch(glob.translate(m, recursive=True), path) for m in patterns)
def main(argv):
command, patterns = argv[0], argv[1:]
entries = changed()
if command == "before":
if entries:
print(f"tree NOT clean: {len(entries)} modified files, commit or put them aside before starting")
return 1
print("tree clean: every difference you will see afterwards will be the agent's")
return 0
outside = [(s, p) for s, p in entries if not allowed(p, patterns)]
for status, path in entries:
tag = "OUTSIDE" if (status, path) in outside else "ok "
print(f"{tag} {status:2} {path}")
print(f"{len(entries)} files changed, {len(outside)} outside the perimeter")
return 2 if outside else 0
if __name__ == "__main__":
sys.exit(main(sys.argv[1:]))
In the changed() function the --untracked-files=all option is there to see new files
one by one too: without it, Git would show a new folder as a single entry and a file created by the agent in an
unexpected folder would go unnoticed. The allowed() function compares the path with the
patterns; exit code 2 of after is meant to distinguish "there are files outside the perimeter" from a
program error.
To try it without involving an agent I simulated the changes myself: a temporary repository with a service, a
component and a package.json, then three changes by hand, two inside the orders folder and one
that touches package.json, exactly the kind of overstepping described at the beginning. The
scenario.sh script builds the repository, runs the checks and deletes it.
#!/bin/bash
set -u
D=$(mktemp -d)
cd "$D" || exit 1
git init -q .
git config user.email test@example.invalid; git config user.name test
mkdir -p src/app/orders
echo "export class OrdersService {}" > src/app/orders/orders.service.ts
echo "export class OrdersComponent {}" > src/app/orders/orders.component.ts
echo '{"name":"shop"}' > package.json
git add . && git commit -q -m base
P=$HOME/demo/perimeter.py
echo "--- before, clean tree"; python3 -I $P before; echo "exit $?"
echo "// page" >> src/app/orders/orders.service.ts
echo "export const PAGE = 20;" > src/app/orders/orders.pagination.ts
echo '{"name":"shop","dependencies":{"x":"1"}}' > package.json
echo "--- after, perimeter src/app/orders/**"; python3 -I $P after 'src/app/orders/**'; echo "exit $?"
echo "--- before, dirty tree"; python3 -I $P before; echo "exit $?"
rm -rf "$D"
The output shows the three situations: a clean tree, changes inside the perimeter with one file outside, and the refusal to
start again with a dirty tree. The two lines that matter are the one for package.json marked
OUTSIDE and the exit 2: in a real task that line tells you the agent changed the dependencies,
and at that point it is you who decides whether to keep them. The codes are the program's, not Cursor's.
# Output of scenario.sh (Python 3.14.4, git 2.53.0, two identical runs)
# --- before, clean tree
# tree clean: every difference you will see afterwards will be the agent's
# exit 0
# --- after, perimeter src/app/orders/**
# OUTSIDE M package.json
# ok M src/app/orders/orders.service.ts
# ok ?? src/app/orders/orders.pagination.ts
# 3 files changed, 1 outside the perimeter
# exit 2
# --- before, dirty tree
# tree NOT clean: 3 modified files, commit or put them aside before starting
# exit 1
The perimeter, on the other hand, holds only if you have communicated it to the agent. The prompt that follows is an example for an Angular project: it states the expected result, the constraints (where it may write, what it must not touch) and how to verify. It is a template to adapt and was not run, because it requires Cursor and a project.
In the src/app/orders folder add pagination to the orders list.
Expected result:
- the OrdersService service accepts a page and a page size and passes them
as query parameters to the GET /api/orders endpoint;
- the component shows twenty orders at a time and two buttons, Next and Back;
- Back is disabled on the first page.
Constraints:
- change only the files inside src/app/orders;
- do not add dependencies to package.json;
- follow the project rules.
Verification: write or update the tests for the service and the component, then run
"npm test" and report the result to me. If a test fails do not change it to make it
pass: tell me why it fails.
Three choices make the prompt verifiable. The result is expressed with behaviours you can observe (twenty
orders at a time, a disabled button), not with adjectives. The constraints match the perimeter you check
afterwards with the script: src/app/orders/** and no dependencies. The last sentence blocks the most
common shortcut, changing a test to make it pass. There is no need to attach every file with the at sign: the documentation
suggests @ mentions when you already know which files matter, and letting the Agent search in the other
cases. If the task changes subject, open a new chat: the context ring next to the text field shows
how much of the window is already taken, and a long conversation gets summarised.
During: what it can run on its own
Run Modes decide when the agent must stop and ask you for confirmation for shell commands, MCP tools and network requests. In the desktop application you choose them from Settings, Agents, Approvals & Execution. There are three, and the difference between one and another is how much trust you give in advance.
- Auto-review: actions on the allowed list start immediately; other shell commands run in the sandbox when possible; whatever cannot use it is examined by a classifier.
- Allowlist: only the listed actions start without asking, deterministic behaviour, no classifier.
- Run Everything: every call starts on its own, with no checks and no sandbox.
The documentation names Auto-review as the safest setting for most people, and right afterwards warns that it is not a security boundary: the classifier can be wrong in both directions. The Run Everything mode corresponds to what many older guides call YOLO; the equivalence is mine, the documentation does not use that name. If the project contains secrets or you work on a machine with access to real systems, the reasonable choice is Allowlist with a few trusted commands, such as tests and the build, or Auto-review with rules of your own. The security page also says that, by default, terminal commands require approval: check in Settings which mode is active on your installation, because the Run Modes page does not say which one is the starting one.
With Auto-review you can add instructions in plain language in a permissions.json file, in
~/.cursor/ for all your projects or in .cursor/ for the current one; if both exist,
Cursor merges them, and a team configuration in the dashboard, if present, takes precedence over both. The file
that follows asks that commands that rewrite Git history and those that delete outside dist/
always go through approval.
{
"autoRun": {
"allow_instructions": [],
"block_instructions": [
"Every command that changes git history (rebase, reset, push) must go through approval.",
"Every command that deletes files outside the dist/ folder must go through approval."
]
}
}
The keys are those of the documentation: allow_instructions describes what Auto-review should
tend to let through, block_instructions what it should tend to block, so that the agent
picks another route or asks you. They are sentences, not formal rules: "tend" is the documentation's verb, so
they do not replace a backup nor an account without write permissions on the production server. I validated the file
as JSON and checked the two keys; the behaviour inside Cursor was not tried.
Underneath there is the sandbox, one more layer for shell commands: in the default mode it works with read and
write access in the project, blocks the network until you open it with sandbox.json and protects paths such as
.git/config and .git/hooks. A command that needs more access leaves the sandbox
and Cursor flags it to you by asking for approval. A warning from the ignore file page: the
.cursorignore file hides files from the agent, but does not govern terminal tools or MCP servers.
After: checking what changed
Changes appear in the diff view while the agent works, and you do not have to wait for the end: the Stop button, or Cmd/Ctrl+Shift+Backspace according to the "Reviewing and testing code" guide, stops it midway. If the route is wrong, the guide advises undoing the changes and refining the plan before rerunning it, instead of correcting it with follow-up messages. To go back there are checkpoints: with "Restore Checkpoint" you bring the files back to the state of that point, but they are local, separate from Git, they do not remove the messages from the conversation, and they serve to undo the agent's changes, while the permanent history is kept by Git.
For the actual review Cursor offers two routes: after a task the Review button, then "Find Issues",
starts a dedicated line-by-line review; for all local changes, the Agent Review command in the Source
Control tab compares them with the main branch. You can also attach @Branch to a message in Ask
mode and ask "review the changes in this branch". The guide recalls that generated code can look correct,
compile and pass the tests you wrote, and still be wrong on edge cases or duplicate logic that already exists:
the criterion for deciding what to merge remains the one you would apply to hand-written code.
One last precaution concerns commits. An agent produces many changes together, and a single commit of hundreds of
lines is hard for a colleague to review. Cursor's guide suggests working freely and then asking
the agent to rewrite the history into small, descriptive commits, with a final check that the overall
diff is identical to the original; it also reports a skill (rework-commits) that you can
adapt. Before using it look at the commands it runs: it contains a git reset, and it is one of those that
is worth sending through approval.
When it is not worth handing it the task
It is not the right tool when you cannot describe the result (use Ask or Plan first to understand the problem), when the outcome can only be judged by eye across many files, and when the code touches secrets or production systems that you do not even want to expose to the context. For one-line changes, Tab completion is faster and leaves less to review. A general criterion stands: the more verifiable the result is with a command, the more delegable the task is.
Frequently asked questions
How do I stop the Agent from running dangerous commands?
Choose the right mode in Settings, Agents, Approvals & Execution, preferring Allowlist or Auto-review to Run Everything, and add blocking instructions in permissions.json. The documentation admits that none of these is an absolute security boundary.
How do I undo what the Agent changed?
With "Restore Checkpoint" on an earlier message you bring the files back to that state, but checkpoints are local and separate from Git. If you work on a clean tree, git restore or a previous commit remain the permanent safety net.
Can I write another message while the Agent is working?
Yes. Pressing Enter puts the message in a queue and it starts at the end of the task; with Cmd/Ctrl+Enter it is sent immediately, without going through the queue. For a side question, side chats avoid interrupting the main conversation.
What you can do now
You can describe a task with a result, constraints and verification, you can decide which commands the Agent may run on its own and which not, and you can check afterwards that the changes stayed within the perimeter you had indicated, with a clean tree as the starting point. The next step is to let the Agent stop and plan before writing, in Plan Mode, and, to automate what happens around the agent, in hooks. If the Agent has to talk to a database or an API, there is MCP; if the task is a bug, there is debugging. For a whole project, from configuration to checks, there is the workflow on an Angular application.
Sources
- Cursor, documentation: Agent - agent components, tools, no limit on calls, checkpoints, message queue, consulted on 2026-11-13
- Cursor, documentation: Run Modes - Auto-review, Allowlist, Run Everything, permissions.json, sandbox, consulted on 2026-11-13
- Cursor, documentation: Agent Security - default approvals for files, terminal and MCP, consulted on 2026-11-13
- Cursor, documentation: Subagents - Explore and Browser subagents, separate context, consulted on 2026-11-13
- Cursor Learn: Reviewing and testing code - stopping the agent, Agent Review, semantic commits, the rework-commits skill, consulted on 2026-11-13
- Cursor, documentation: Agent mode - Agent, Ask, Plan and Debug modes and restoring checkpoints, consulted on 2026-11-13
- Cursor, documentation: Prompting agents - @ mentions, the context ring, consulted on 2026-11-13
- Cursor, documentation: Ignore file - limits of .cursorignore on terminal and MCP, consulted on 2026-11-13
- Git: git-status - the --porcelain format, stable for scripts, and the --untracked-files option, consulted on 2026-11-13
- Python: glob module - glob.translate, consulted on 2026-11-13
The perimeter tool was run with Python 3.14.4 and Git 2.53.0 in a temporary repository outside the project, twice with identical output; I simulated the scenario's changes by hand, without any agent. The permissions file was validated as JSON. The prompt and the behaviour of Cursor, of Run Modes and of checkpoints were not tried: Cursor was not installed.

Commenti
Caricamento commenti...
Sign in to comment