When to use agent mode vs ask mode

Agent mode versus ask mode is the choice between letting an AI coding agent write to your repository and keeping it read-only. Claude Code and Codex call the read-only stance plan mode, and Cursor has Plan Mode. The safe default is to stay read-only until a plan is approved, then grant writes for one bounded step whose tests decide whether it is accepted.

This page is for developers who pick a mode for every task and for tech leads who set the team default. You ask the agent a question about your Express payment handler: “why does processPayment sometimes charge twice?” A minute later it has changed the idempotency logic, touched three call sites and edited a migration, and you are reviewing a diff you never asked for on the most sensitive path in the codebase. The opposite mistake is quieter: you spend forty minutes in read-only questions, fill the context window, and start the implementation in a session that no longer remembers the constraints.

What mode discipline gives you on a real change

• A map of the read-only, write and unattended modes in Claude Code 2.1.283, Codex CLI 0.157.1 and Cursor, with the exact key, flag or setting for each.
• A two-phase loop: explore read-only and produce a plan, then execute one approved step and stop.
• Four copy-paste prompts: plan without editing, execute one step, verify the step with evidence, and scope an unattended batch job.
• A decision table that maps task type to mode and to the check that proves the result.
• The failure modes that make a mode lie to you, with the recovery for each.

Which modes do Claude Code, Codex and Cursor offer?

Every tool offers the same three stances under different names. “Ask mode” on this page means the read-only stance in general, whatever the tool calls it. Checked on 2026-09-26 against claude --help 2.1.283, codex --help 0.157.1 and the vendors’ own documentation; current models are listed on the models page. Cursor entries were last verified on 2026-08-28 (Plan Mode, Cloud Agents) or from @cursor/sdk 1.0.32.

Stance	Claude Code 2.1.283	Codex CLI 0.157.1	Cursor
Read-only: explore and plan	plan mode: Shift+Tab until ⏸ plan mode on, /plan <prompt> for one prompt, or claude --permission-mode plan	/plan in the TUI; the :read-only permission profile (beta) or the legacy --sandbox read-only	Plan Mode: “creates detailed implementation plans before writing any code”
Write, you approve	Manual (config value default) or acceptEdits (edits run, other commands still ask)	:workspace profile with -a on-request	Agent (the SDK’s agent mode), with approvals set on the Run modes page under Agent security
Write, a reviewer model approves	auto: a classifier (Claude Sonnet 5 by default) reviews each action	Auto-review: --approve-for-me	Auto-review for local tool calls (SDK option autoReview)
Unattended	claude -p with --permission-mode dontAsk and an exact --allowedTools list	codex exec with the :workspace profile	Cloud Agents, which “run in isolated VMs in the cloud”

Claude Code's starting mode now writes

From v2.1.283 (the latest channel), interactive terminal and VS Code sessions start in auto mode on every plan and provider, and Pro, Max and Team plans have started there since 2026-08-14. A question typed into a fresh session can therefore turn into edits that a classifier approves, not you. claude -p, Agent SDK sessions and sessions on a model auto mode does not support start in Manual. Press Shift+Tab into plan mode before you ask anything you do not want acted on.

The full control matrix, including OS sandboxes and network egress, lives on permissions, sandboxes and approval modes. This page covers the decision: which stance a task needs, and when to move between them.

How do you explore a codebase without letting the agent edit?

Start every non-trivial change read-only. The goal of this phase is one artifact: a numbered plan that names files, tests and risks, which you can reject before a line changes.

Claude Code

Press Shift+Tab until the status bar shows ⏸ plan mode on, or start there from your terminal:

claude --permission-mode plan

In plan mode Claude reads files and runs read-only commands (plus commands the auto-mode classifier approves, where auto mode is available), and edits stay blocked until you approve the plan. When the plan appears, Ctrl+G opens it in your editor so you can correct it before you approve. To make plan mode the default for a repository’s terminal sessions, set "defaultMode": "plan" under permissions in .claude/settings.json. The VS Code extension does not read project settings for its starting mode; set claudeCode.initialPermissionMode to plan in your VS Code user settings instead.

Codex

Start the TUI with the read-only profile, so the sandbox itself refuses writes, then type /plan to switch to Plan mode:

codex -a on-request -c 'default_permissions=":read-only"'

With codex-cli 0.157.1 on Linux, a touch inside this profile fails with Read-only file system while reads succeed; codex sandbox -c 'default_permissions=":read-only"' -- sh -c 'touch probe' reproduces the check. Permission profiles are beta; if you use the legacy --sandbox read-only instead, do not combine it with default_permissions, because OpenAI says the two systems do not compose.

Cursor

Switch the chat to Plan Mode before you ask. @-mention the entry points you care about (@src/routes/payments.ts) so retrieval starts from the right files. Your build’s mode picker may list more modes than Agent and Plan. Plan Mode is the documented read-only mode (the SDK exposes agent and plan), so check which of the others is read-only in your version before relying on it. The Cursor agent modes deep dive covers the IDE side.

The prompt is the same in every tool. It forces the plan to carry the information the next phase needs, including the command that will prove each step:

Copy-paste prompt: map and plan a change without editing anything

Read-only phase. Do not edit files or run commands that change state.

1. Map every call site of `processPayment` under src/, the modules that
   import it, and where the Stripe idempotency key is (or is not) set.
2. Explain in five sentences or fewer why a retry could charge twice.
3. Propose a plan as a numbered list. For each step give: the files it
   touches, the behaviour it changes, the existing tests that cover it,
   the new test that will fail before the step and pass after it, and the
   exact command that runs those tests.
4. List what you could not determine from the code (business rules,
   config, external behaviour) as open questions.

Output the plan only.

Review the plan, not the code. Reject it if a step has no test, touches a file outside the change, or answers an open question by guessing. Time-box this phase: when the plan stops getting better, move on, because every further question spends context the implementation needs. The context windows guide explains when to start a fresh session with the plan as the only input.

How do you hand one approved step to the agent?

Grant write access for one step at a time and make the agent stop afterwards. The stop is what keeps an approved plan from turning into an unreviewed rewrite.

Claude Code

Approve the plan with Yes, manually approve edits for payment, auth, migration or infrastructure code, so each edit prompts. For routine code choose Yes, and use auto mode. Pre-approve the test command with an allow rule such as Bash(npm test *) in /permissions, so the prompts you do see are the ones that matter. If a step goes wrong, /rewind (or Esc twice on an empty prompt) restores the code and conversation to a checkpoint.

Codex

Leave the TUI and restart it with the workspace profile. Edits and commands inside the workspace run; crossing the sandbox boundary asks you first:

codex -a on-request -c 'default_permissions=":workspace"'

/permissions inside the TUI switches the same setting without restarting. The workspace profile can write anything in the working tree, including a .env file or deployment manifest, so keep secrets out of the repository you point it at.

Cursor

Switch to Agent and paste the step prompt below. Before you run it, check your approval settings on the Run modes page under Agent security. Mode names on the Run modes page change between builds; read them from your own Settings.

Copy-paste prompt: execute exactly one step, then stop

Execute step 1 of the approved plan and nothing else.

- Write the new failing test first and run it; paste the failure.
- Make the change: derive an idempotency key from the order ID and pass it
  as `idempotencyKey` to the Stripe `paymentIntents.create` call in
  `processPayment`. Update only the call sites listed in the plan.
- Run `npm test -- payments` and paste the summary line.
- If you need to touch a file the plan does not list, stop and ask.

Then stop. Report the files changed, the test output, and anything you
assumed. Do not start step 2 until I say so.

How do you check a step without reading every line?

Mode discipline decides what the agent may do. It does not decide whether the result is right. That job belongs to checks that run without you, so a human reads code only where the risk requires it.

1. The test named in the plan fails before the step and passes after it. The agent pastes both outputs. A step whose new test never failed has proved nothing; the TDD guide covers how to stop an agent from weakening a test to make it pass.
2. The repository’s own gates pass: type check, lint and the full test suite, run by CI rather than reported by the agent.
3. A second pass attacks the diff. Run the review prompt below in a fresh read-only session or with a separate reviewer agent, so the author’s context does not excuse its own gaps. Reviewing agent PRs sets this up as a standing gate.
4. The step leaves an evidence summary: files changed, commands run, outputs and open assumptions. A reviewer reads that summary, not the diff; the evidence bundle defines the format.
5. A human reads the code only for escalation classes: money movement, auth, data migrations, infrastructure and anything the reviewer flagged. The evidence-over-diffs page lists the classes and who signs off.

Copy-paste prompt: attack the diff before it is accepted

You are reviewing, not writing. Do not edit files.

Review the current uncommitted diff as a hostile senior reviewer on a
payment path. List, with file and line:
1. Error paths and retries the change does not handle.
2. Concurrency cases: two requests with the same order ID at once.
3. Any place the code guesses a business rule instead of reading it.
4. Tests that pass without exercising the new behaviour.

For each finding, propose the failing test that would expose it.
End with PASS only if you found nothing in 1–4.

Any finding becomes the next plan step, with its failing test first. The loop stays the same: read-only to decide, write to execute one step, read-only again to check.

When is it safe to let the agent run unattended?

Run unattended only when three things hold: the task is mechanical, a command decides whether each change is correct, and the blast radius is limited to a branch or a disposable environment. Lint fixes, formatting, a codemod-style rename and test boilerplate qualify. API design, error-handling strategy, performance work and anything in an escalation class do not, because “correct” there needs judgement a command cannot supply.

Claude Code

Run headless with dontAsk, which denies every action that would otherwise prompt, so the allowlist is the whole policy. Run it on its own branch or worktree:

claude -p "Fix every ESLint error in src/components/. Run npm run lint after each file." \
  --permission-mode dontAsk \
  --allowedTools "Read" "Edit" "Bash(npm run lint *)"

--dangerously-skip-permissions bypasses all checks, and the CLI’s own help recommends it “only for sandboxes with no internet access”. Use it only inside a disposable, network-restricted container or VM that holds no production credentials.

Codex

codex exec has no -a flag in 0.157.1 and needs none: it already runs with approval: never.

codex exec -c 'default_permissions=":workspace"' \
  "Fix every ESLint error in src/components/. Run npm run lint after each file."

With never, an action that needs to cross the sandbox boundary fails instead of prompting, and the failure goes back to the model. --dangerously-bypass-approvals-and-sandbox is, in the CLI’s words, “intended solely for running in environments that are externally sandboxed”: use it only inside a disposable, network-restricted container or VM that holds no production credentials.

Cursor

Hand the job to a Cloud Agent, which runs in an isolated VM with a full development environment, so your local checkout stays untouched until you review the branch it produces. Headless runs from CI use the Cursor CLI’s print mode (-p, --print).

Nobody watches an unattended run, so its scope has to be written into the prompt:

Copy-paste prompt: scope an unattended batch job

Fix every ESLint error reported by `npm run lint` in src/components/.

Rules:
- Make the smallest change that clears each error. No refactoring.
- Modify files only under src/components/. Do not touch tests, config,
  package.json or lockfiles, and do not install dependencies.
- After each file, run `npm run lint -- src/components/` and continue only
  if the error count went down.
- If an error needs a behaviour change to fix, skip it and list it.

Finish with: files changed, errors before and after, and skipped errors
with the reason for each.

The check on an unattended run is the same gate as in the previous section: CI runs lint, types and tests on the branch, and the summary tells a reviewer what was skipped. The permissions and sandboxing guide covers the sandbox and network settings an unattended run needs.

Which mode fits which task?

Task	Mode	What proves the result
Understand unfamiliar code, onboard, investigate a bug	Read-only	Every claim cites a file and line you can open; a failing test reproduces the bug
Plan a change of more than one file	Read-only, then write per step	Each plan step names its test and command
Implement a planned step in routine code	Write, reviewer model or acceptEdits	The step’s test fails then passes; CI gates pass
Change payments, auth, migrations or infrastructure	Write, you approve each edit	The above plus a human read of the escalation class
Lint, formatting, mechanical renames, test boilerplate	Unattended on a branch	The lint or type command reaches zero; CI passes
Unsure	Read-only first	A plan you can reject costs nothing to throw away

For tech leads, the adoptable default is the last row: repositories start sessions in plan mode, and the move to write is a deliberate step the developer takes after a plan exists. For Claude Code, commit "defaultMode": "plan" in .claude/settings.json (terminal sessions) and ask VS Code users to set claudeCode.initialPermissionMode; for Codex, set default_permissions = ":read-only" in ~/.codex/config.toml or put -c 'default_permissions=":read-only"' in the team’s launch alias.

What goes wrong when you pick the wrong mode?

• Plan mode edits files anyway. In an interactive Claude Code session started with --dangerously-skip-permissions or --allow-dangerously-skip-permissions, plan mode’s blocks are not enforced: Claude is told to plan, but an edit it attempts runs. Recovery: /rewind to the last checkpoint, and never start a planning session with a bypass flag.
• A question in a fresh session turns into edits. The Claude Code starting mode is auto on v2.1.283, not Manual. Recovery: /rewind, then set "defaultMode": "plan" in the repository’s .claude/settings.json so terminal sessions start read-only, and claudeCode.initialPermissionMode for the VS Code extension, which ignores the project value.
• The agent jumps from analysis to refactor. A prompt such as “analyze the auth module, then refactor it” invites the agent to skip the analysis. Recovery: split it into the read-only prompt and the one-step prompt above, in separate turns.
• The approved plan grows mid-step. A vague step invites scope creep. Recovery: reject the edits outside the plan’s file list, rewind, and restate the step with its file list and a stop condition.
• You stay read-only too long. A long exploration fills the context window, and the implementation starts from a compacted, lossy summary. Recovery: save the plan to a file, start a fresh session, and give it the plan as the first message.
• The agent seems to ignore implementation requests. It is usually still in a read-only mode. Recovery: check the mode indicator (⏸ plan mode on in Claude Code) or the Codex profile before you rewrite the prompt.
• Codex rejects your flags. codex exec -a never fails with “unexpected argument”, -a on-failure fails with “invalid value”, and a permission profile combined with --sandbox does not compose. Recovery: drop the flag and run codex exec …, which already runs with approval: never, and pick profiles or the legacy flag, not both.
• An unattended run touched something sensitive. The Codex workspace profile and a broad Claude Code allowlist can both reach files such as .env. Recovery: revert the branch, move secrets out of the working tree, and narrow the allowlist or profile before the next run.

Where to go next with mode choice

Permissions, sandboxes and approval modes The full control matrix: approval layers, OS sandboxes and network egress per tool.

The build stage Where plan-then-execute sits in the lifecycle, from approved spec to merged change.

Human in the loop Which gates need a person and which can run on evidence.

Grill Me and Grill With Docs Read-only taken further: the agent interviews you until the plan has no open questions.