> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cortex.foundation/llms.txt
> Use this file to discover all available pages before exploring further.

# Ask, Plan, Agent

> Ask reads and explains, Plan proposes, Agent edits and runs. The mode locks the tools a turn is built with and applies to the next turn.

Every turn in Cortex Code runs in one of three interaction modes. **Ask** answers questions and reads the repository. **Plan** returns a plan you can review. **Agent** edits files, runs commands and opens a pull request. You pick the mode in the composer before you start a session, and again on every follow-up, so a single session can tighten to Ask to understand something and widen to Agent to carry it out.

This page explains what each mode may reach, why the choice is worth trusting, when the change takes effect, and what none of the three modes can do. If you are looking for a first session end to end, start with the [Code quickstart](/code/quickstart).

## What each mode may do

| Mode      | Its own description in the app                                              | Edits files | Runs commands | What it produces                                   |
| --------- | --------------------------------------------------------------------------- | ----------- | ------------- | -------------------------------------------------- |
| **Ask**   | **Questions and exploration. Nothing is edited until you switch to Agent.** | No          | No            | Answers, file reads, searches                      |
| **Plan**  | **A mermaid plan you can review. No edits until you switch to Agent.**      | No          | No            | A reviewable plan on the **Plan** tab              |
| **Agent** | **Full catalog: read, edit, run, and open a pull request.**                 | Yes         | Yes           | Edits, command output, a branch and a pull request |

All three modes can read a file, list files by pattern, search the repository by regular expression, read the task list and read artifacts. Only **Agent** can write a file, edit a file, run a command, write the task list, or dispatch the background search worker.

## The lock is on the tools, not on the model

The three modes are worth trusting because of where the decision is made. In Ask and Plan the mutating tools, writing, editing, running a shell command, writing the task list and dispatching the background worker, are simply **absent** from the catalog the turn is built with. The model is not asked to behave: there is no instruction it could misread or talk itself out of, because the tool is not there to call. If one is called anyway, the call is refused a second time when it is dispatched.

Plan gets one extra tool the others do not: the plan writer. That is the only thing that fills the **Plan** tab.

<Warning>
  Because the catalog is chosen when the turn is built, **a mode change takes effect on the next turn, not on the turn already running.** Switching to Agent while a turn is in flight does not retroactively let that turn edit anything, and switching to Ask does not claw back an edit the running turn has already proposed. If you need a running turn to stop, press **Stop** in the composer's send disc, then send the next turn in the mode you want.
</Warning>

## Choose a mode, and change it per turn

<Steps>
  <Step title="Pick the mode for the first turn">
    On Code Home, the controls row under the prompt carries **Ask**, **Plan** and **Agent**. The mode is stored on the session, and a new session defaults to **Agent**.
  </Step>

  <Step title="Send the task">
    Press **Start session**. The turn is built with the catalog that mode allows, and nothing widens it afterwards.
  </Step>

  <Step title="Change it on a follow-up">
    The follow-up composer inside the session carries the same mode menu, so the mode can change on every turn. Pick a mode and send the follow-up: the new mode applies to that turn. A follow-up that does not pick one keeps the session's current mode.
  </Step>
</Steps>

A useful rhythm: **Plan** to agree on the approach, **Agent** to carry it out, **Ask** when something has gone sideways and you want to understand the repository before you let anything else change.

## What a Plan turn gives you

A Plan turn reads the repository and returns a structured proposal: titled steps, the files it expects to touch, the risks it sees, and a rendered diagram. The product's own word for the diagram is mermaid, which is why the mode's description mentions it.

The **Plan** tab in the output pane appears **only when the session has a plan**. Nothing changes in the repository while you read it. Ask for adjustments as many times as you like, in Plan, and send an **Agent** turn when the approach is right. The cheap moment to redirect a change is before any file moves.

## Ask and Plan in the Changes pane

The **Changes** pane is where file writes wait for a human decision. In Ask or Plan there is nothing there to decide, and the pane says so outright:

> **Ask and Plan do not change files, so there is nothing to review here.**

That is the mode reporting itself, not a failure. See [Changes and diffs](/code/changes).

## Security is not a fourth mode

Under the three modes there is a fourth row labelled **Security**, with the hint **Open Security mode for this repository**. It is a link, not a mode: it leaves the composer for Cortex Security, which reads a pull request and posts a review instead of writing code. A session's interaction stays Ask, Plan or Agent. See [Pull-request review](/code/security).

## What no mode can reach

<Note>
  The mode is chosen **per session and per turn only**. There is no workspace setting that pins a read-only default, and [Code settings](/code/settings) does not offer one. If you want a session to stay in Ask, keep choosing Ask on each turn.
</Note>

A Code session does not receive the tools a Chat turn has: no web search, no web page extraction, no hosted snippet sandbox, no skills and no clock. When a task needs to run your repository's own Python, an Agent turn runs it as a shell command inside the attached runtime, like any other command.

A Code session is also built with no tool servers, connectors or plugins of its own, so widening the mode to Agent does not open a path to an external service. See [Code integrations](/code/integrations) for what is configured at the workspace level and what a session reports.

## Related

* [Code sessions](/code/sessions) for the transcript, follow-ups and the session board.
* [How Code works](/code/how-it-works) for the turn loop the mode is built into.
* [Permissions and approvals](/code/approvals) for the two gates an Agent turn meets.
* [Changes and diffs](/code/changes) for reading and approving what an Agent turn proposes.
* [Modes and permissions in the CLI](/cli/modes-and-permissions) for the same choice in a terminal.
* [Code troubleshooting](/code/troubleshooting) when a turn will not edit anything.