Use the least powerful mode that finishes the task. Read-only suits exploring unfamiliar code, plan mode suits proposing a change for a human to approve, and edit mode suits contained changes in a sandbox. Command execution and network access deserve their own gates whichever mode you pick.
What the modes mean
Tools name these differently, so judge by capability:
- Read-only. The agent can read files and answer questions. It cannot change anything.
- Plan. The agent reads, then produces a proposed set of steps or a diff for a person to approve before anything happens.
- Edit. The agent changes files in the working directory, sometimes with confirmation per change.
- Act. The agent edits and also runs commands, installs packages, or calls external services.
The last category is where the risk concentrates. The OWASP Top 10 for LLM Applications describes Excessive Agency (LLM06) as an agent holding more functionality, permission, or autonomy than needed, and the modes are a practical dial for each.
Matching mode to task
| Task | Suggested mode | Why |
|---|---|---|
| Understanding an unfamiliar repository | Read-only | No need to change anything |
| Reviewing a pull request | Read-only | Output is comments, not edits |
| Designing a refactor | Plan | Human approves the approach first |
| Fixing a small bug with a test | Edit in a sandbox | Contained, easy to review as a diff |
| Upgrading dependencies | Plan, then edit with checks | Needs review of what changes |
| Running a build or migration | Act, sandboxed, with approvals | Needs commands, so contain it |
| Anything touching production config | Do not use an agent unattended | Impact is too high |
Escalation, not default
Treat higher modes as something a developer steps up into for a reason. Start every session read-only or plan. Escalate when the plan looks right. After the task, drop back down. Tools that remember the last mode can leave people in act mode all week, so check how yours behaves.
Pair each mode with a control
- Read-only. Still limit what files are readable. See what files an agent should never read.
- Plan. Keep the plan. A saved plan is an audit record.
- Edit. Work on a branch or copy, and review the diff.
- Act. Sandbox, scoped credentials, approval for installs and new hosts, and logging.
Why plan mode helps reviewers
A reviewer who sees a plan first can catch a wrong approach before there is a large diff to read. It also exposes scope: if the plan touches pipeline files for a typo fix, that is a signal. Many teams find that plan first reduces both risk and rework.
Set defaults centrally
If your tool allows it, set the default mode by environment. Laptops might default to plan, CI jobs to a fixed action list, shared servers to read-only. Document the exceptions. Our post on enforcing team settings for a coding agent covers keeping settings from drifting.
Test the mode itself
Do not assume read-only means read-only. In a throwaway repository, ask a read-only agent to change a file and to run a command. Both should fail. Repeat after upgrades.
Safeguard can help at the dependency and pipeline end of this: SBOM and dependency scanning, reachability analysis, policies and gates on pull requests, and agent identity. You can try a free scan at gold.safeguard.sh/scan.
A worked example: one feature, three modes
A developer wants to add rate limiting to an API. She uses three modes in sequence.
| Phase | Mode | What the agent does | What the developer does |
|---|---|---|---|
| Explore | Read-only | Summarizes the request handling code and lists where limits could fit | Reads the summary, corrects a wrong assumption |
| Design | Plan | Proposes four steps: add middleware, add config, add tests, update docs | Rejects the docs step, asks for a smaller middleware change |
| Build | Edit in sandbox | Makes the changes on a branch and runs tests | Reviews the diff, notices a changed test, asks why |
| Finish | Back to read-only | Answers questions about edge cases | Opens the pull request herself |
At no point did the agent run commands that reached outside the sandbox, and each step ended with a person making a decision. The wrong assumption was caught in phase one, before any code existed, which saved review time later.
Mode switching rules
- Start in the lowest mode that does the job.
- Step up only after the previous mode's output looks right.
- Step back down when the task changes.
- Never carry act mode over a weekend or into an unrelated task.
- If the tool remembers modes between sessions, check what it remembered before you begin.
What each mode still needs
| Mode | Residual risk | Control |
|---|---|---|
| Read-only | Reads sensitive files, ingests hostile text | File scope limits, treat input as untrusted |
| Plan | A convincing but wrong plan | Reviewer reads the plan against the real code |
| Edit | Bad edits, weakened tests | Branch, diff review, required checks |
| Act | Commands, installs, network | Sandbox, allowlist, approvals, logs |
Central defaults by environment
| Environment | Default mode | Who can change it |
|---|---|---|
| Developer laptop | Plan | Developer, within policy |
| Shared server | Read-only | Platform team |
| Continuous integration | Fixed action list | Pipeline owner |
| Restricted repositories | Off | Security |
Common errors
- Assuming a mode named read-only blocks everything. Test it.
- Leaving a long running session in act mode after the task changed.
- Treating a plan as approval for everything the agent later does, when the agent may deviate.
- Not saving the plan, which loses a useful record of what was agreed.
A quick habit
At the start of each session, say out loud which mode you are in and why. It sounds silly, but it prevents the drift to maximum autonomy that happens when people are busy.
Try it yourself
Click through it at your own pace, or open it full screen.
Click through and notice where checks run after the edit phase, whatever mode produced the change.
Quick check
Is plan mode safe?
It is safer because nothing changes until a person approves, but the agent still reads files and may fetch content, so the read side needs limits too.
Who decides when to escalate?
The developer, within limits that policy sets per environment.
Can plan mode be bypassed?
Depending on the tool, a user can switch modes. That is why central defaults, logs, and server side branch protection still matter.
Sources
Last reviewed: 19 October 2026.
