> ## 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.

# Modes and permissions

> The four composer modes, the approval prompt, the sandbox, the permission table, and the reasoning-effort options

Every CLI session runs under three separate controls. A **mode** decides which tools the agent is offered at all. An **approval policy** decides when you are asked before a tool acts. A **sandbox** decides what a tool may touch once it does run. Reasoning **effort**, set beside the model, decides how hard the model thinks about the request.

This page covers the four composer modes and how to switch them, what the approval prompt looks like and what each option commits you to, the sandbox and the prompt you get when it blocks something, the per-capability permission table in `config.toml`, the model and effort lists, and which control to reach for in a given situation.

## The four modes

`Shift+Tab` cycles Agent, Plan and Ask. The mode chip on the top border of the composer always names the current one, verbatim:

| Mode  | Chip                        | The agent may                             | Use it for                                   |
| ----- | --------------------------- | ----------------------------------------- | -------------------------------------------- |
| Agent | `Agent`                     | Read, write, and run commands             | The change you have already decided on       |
| Plan  | `Plan · no edits`           | Read and propose, nothing else            | Working out what to do before anything moves |
| Ask   | `Ask · read-only`           | Read and explain                          | Understanding code                           |
| Bash  | `Bash · runs in your shell` | Nothing. You are the one running commands | A quick command without leaving the session  |

Bash mode is not part of the cycle: type `!` at the start of the composer to enter it, and `Esc` to leave. While you are in it the composer sigil changes from `>` to `!`, and what you type runs in your shell rather than going to the agent.

Plan and Ask are **locks, not suggestions**. The mutating tools are withheld by the agent harness, so the agent cannot write a file or run a mutating command even if it decides it should. Plan mode has a page of its own: [Plan and Spec modes](/cli/plan-mode). The same three modes exist in the web app as Ask, Plan and Agent, see [Ask, Plan, Agent](/code/interactions).

## Approve or refuse a command

When the agent wants to do something consequential in Agent mode, the prompt appears inline in the timeline and the composer waits:

```
● Cortex wants to run
  1 Yes, run once
  2 Yes, always allow npm install in this project
  3 Edit command
  4 No — tell Cortex what to do instead
```

`↑` and `↓` move the selection, `Enter` confirms, `1` to `9` pick a numbered option directly, `e` edits the command before it runs, and `Esc` cancels.

Option 2 is the one to read carefully. It is templated on the **kind** of command, not on the exact string, so choosing *always allow ... in this project* remembers that family of command for this project rather than every command everywhere.

## When the sandbox blocks something

The sandbox is the second gate, and it applies whether or not you were asked for approval: it decides what an operation is physically allowed to touch. When it blocks one, the timeline says so and offers three ways forward: **Keep blocked**, **Allow once**, or **Allow for this session**.

Approval and sandboxing are independent. A command can be approved by you and still be refused by the sandbox, which is the point: approval is about intent, the sandbox is about reach.

## Set the policy for a session

From the composer:

* `/approval` takes one of `ask`, `session`, `always` or `never`.
* `/sandbox` turns sandboxed execution on or off.
* `/auto` turns auto-approval on or off.

The same policy is also offered as three named presets in the session's autonomy picker:

| Preset          | What it means                                                       |
| --------------- | ------------------------------------------------------------------- |
| **Smart**       | Auto-approve safe reads, ask before edits and commands. The default |
| **Read-only**   | Never edit files, never run commands                                |
| **Full access** | Only ask when something leaves the sandbox                          |

## From the command line

Two flags carry the same controls into any invocation, interactive or not. They have short forms, `-a` and `-s`:

```bash theme={null}
cortex --ask-for-approval on-request
cortex --sandbox workspace-write
```

| `--ask-for-approval` | When you are asked                                       |
| -------------------- | -------------------------------------------------------- |
| `untrusted`          | Ask for anything not already trusted                     |
| `on-failure`         | Let it run, ask when something fails                     |
| `on-request`         | The agent asks when it judges it should. **The default** |
| `never`              | Never ask                                                |

| `--sandbox`          | What a tool may touch                             |
| -------------------- | ------------------------------------------------- |
| `read-only`          | No writes at all                                  |
| `workspace-write`    | Writes confined to the workspace. **The default** |
| `danger-full-access` | Everything                                        |

`--full-auto` means run without asking, but still inside the sandbox. `--add-dir` adds another directory that should be writable for one run. `trusted_directories` in `config.toml` looks like the persistent version of the same idea, but nothing in this build reads it.

<Warning>
  `--dangerously-bypass-approvals-and-sandbox`, aliased `yolo`, turns off both gates at once: nothing asks and nothing is confined. Use it only in a throwaway environment you are willing to lose.
</Warning>

## One idea, four vocabularies

The same underlying control is named differently depending on where you meet it. This table is the map, not an equivalence:

| Where you are  | What it is called                                                                                                           |
| -------------- | --------------------------------------------------------------------------------------------------------------------------- |
| The composer   | Mode chips, the approval prompt, the three session presets                                                                  |
| `config.toml`  | `approval_policy` and `sandbox_mode`                                                                                        |
| Slash commands | `/approval`, `/sandbox`, `/auto`                                                                                            |
| Headless runs  | `--auto`, with levels `read-only` (the default), `low`, `medium` and `high`. `cortex exec` runs `read-only` and `high` only |

<Note>
  `--auto read-only` asks unless the action is trusted, and holds the sandbox read-only. `--auto high` never asks, and allows workspace writes with network access. `low` and `medium` sit between them in the flag's value set, but `cortex exec` refuses both before submitting a turn, so there is no third and fourth behaviour to plan around. [Headless and one-shot runs](/cli/headless) has the refusal message.
</Note>

## The permission table

`config.toml` can set policy per capability, and each value is `allow`, `ask` or `deny`. This is the control to reach for when you want one command family refused everywhere, regardless of mode:

```toml theme={null}
[permission]
edit = "ask"
webfetch = "allow"
doom_loop = "ask"
external_directory = "deny"

[permission.bash]
"git *" = "allow"
"rm *" = "deny"

[permission.skill]
"deploy" = "ask"

[permission.mcp]
"my-server" = "allow"
```

A `deny` here wins over the mode and over any approval you give at the prompt. `[permission.bash]` matches shell commands by glob, `[permission.skill]` names a [skill](/cli/skills), and `[permission.mcp]` names a [connected server](/cli/mcp).

`[sandbox_workspace_write]` refines what `workspace-write` allows, with four keys: `writable_roots` for extra directories, `network_access` for outbound network, and `exclude_tmpdir_env_var` and `exclude_slash_tmp` to keep temporary directories out of the writable set. See [Configuration](/cli/configuration), and [Permission policy](/cli/policy) for the rules an organization can set centrally.

## Model and effort

`/models` lists the models under their product names and `Tab` moves from that list to the reasoning-effort options for the selected model.

| Model             | Role                                                   |
| ----------------- | ------------------------------------------------------ |
| **Cortex Mini 1** | Fast default for everyday coding                       |
| **Cortex 1**      | Deeper reasoning for hard changes                      |
| **Cortex Max 1**  | Longest context; bills by token instead of per request |

The three effort options carry their own one-line descriptions on screen:

* **Low Effort**: `Fastest responses for quick edits and questions`
* **Medium Effort**: `Balanced reasoning for everyday coding · default`
* **High Effort**: `Deepest reasoning — best for hard, multi-file changes`

`Enter` applies an effort and `Tab` goes back to the model list. The current effort is part of the model chip on the composer, drawn as `Cortex Mini 1 (medium)`.

## Which control do I want?

| I want to                                         | Use                                                                       |
| ------------------------------------------------- | ------------------------------------------------------------------------- |
| Explore without changing anything                 | Mode **Ask**, or `--sandbox read-only`                                    |
| See the approach first                            | Mode **Plan**, or `/spec` for a structured plan with a hard lock          |
| Let it work but confirm installs and deletes      | Mode **Agent** with the **Smart** preset                                  |
| Never be interrupted, but stay inside the project | `--full-auto`                                                             |
| Forbid one command family everywhere              | `[permission.bash]` with `"rm *" = "deny"`                                |
| Run a task with nobody there to ask               | `cortex exec --auto read-only`, raising the level only as far as you need |

## Related

* [The TUI](/cli/tui) - where the chips, the prompt and the footer hints live
* [Plan and Spec modes](/cli/plan-mode) - the read-first modes in detail
* [Configuration](/cli/configuration) - `approval_policy`, `sandbox_mode` and the permission table
* [Permission policy](/cli/policy) - organization-wide rules
* [Headless and one-shot runs](/cli/headless) - autonomy when there is no prompt to answer