# Permission Modes

> Controls whether CodeBuddy should stop and ask before editing files, running commands, or making network requests. The mode determines the pace of the entire session: conservative modes require approval step by step, while more permissive modes let CodeBuddy continue for longer without interruption and report back at the end. Use strict modes for sensitive operations, and permissive modes when you trust the direction.

## Available Modes

CodeBuddy Code provides the following permission modes. The first four are directly exposed to CLI users; the rest are for IDE integrations and subagent scenarios.

### Modes You Can Switch Manually

| Mode                                                         | What can run without asking                                                                                   | Use case                                                    |
| :----------------------------------------------------------- | :------------------------------------------------------------------------------------------------------------ | :---------------------------------------------------------- |
| `default`                                                    | Read tool inside trusted directories                                                                          | Default; suitable for sensitive work / getting started       |
| [`acceptEdits`](#acceptedits-auto-approve-file-edits)        | Read + Edit-family tools inside trusted directories                                                           | Keep writing, then review with git diff                     |
| [`plan`](#plan-explore-before-changing)                      | Delegates to the mode active before entering plan (default = `default`); additionally allows writing session plan files | Explore the code before deciding what to change              |
| [`bypassPermissions`](#bypasspermissions-skip-all-checks)    | All tools, without asking                                                                                     | Use only in sandbox containers / VMs / offline dev containers |
| [`delegate`](#delegate-multi-agent-coordination-mode)        | Coordination tools only (such as Agent / TaskCreate / SendMessage / team management); implementation tools are blocked | The main agent only decomposes and delegates work to subagents |

### Programmatic / Integration Modes (Not in the Shift+Tab Cycle)

| Mode            | When it appears                                                                                                                   |
| :-------------- | :-------------------------------------------------------------------------------------------------------------------------------- |
| `fullAccess`    | Passed by an IDE client through the protocol; semantically equivalent to globally allowing everything like `bypassPermissions` |
| `work`          | Passed by an IDE client. Read is allowed directly (without checking trusted directories), Edit always asks, Bash allows only safe commands directly, and other tools ask |
| `ignore`        | Only takes effect for subagents / teammates. It means “use the main session’s mode; do not let the subagent’s own frontmatter override it”. Main sessions do not use it |

## Switching Permission Modes

You do not switch modes by telling CodeBuddy in chat. Set them through the following three entry points instead.

### Switch During a Session: Shift+Tab

In the CLI, press `Shift+Tab` to cycle through the following five modes:

```
default → bypassPermissions → acceptEdits → plan → delegate → default → ...
```

After switching, the current mode is shown in the lower-left status bar:

| Mode                 | Status bar text                              | Color                                |
| :------------------- | :------------------------------------------- | :----------------------------------- |
| `default`            | Not shown                                    | —                                    |
| `bypassPermissions`  | `⏵⏵ bypass permissions on (shift+tab to cycle)` | warning                       |
| `acceptEdits`        | `⏵⏵ accept edits on (shift+tab to cycle)`       | info                          |
| `plan`               | `⏸ plan mode on (shift+tab to cycle)`           | planMode                      |
| `plan` + pre-mode    | `⏸ plan + accept edits (shift+tab to cycle)` and similar | planMode              |
| `delegate`           | `⇢ delegate mode on (shift+tab to cycle)`        | delegateMode                  |

### Specify at Startup: `--permission-mode`

```bash
codebuddy --permission-mode plan
codebuddy --permission-mode acceptEdits
codebuddy --permission-mode bypassPermissions
codebuddy --permission-mode default
```

The CLI option `--permission-mode` accepts only these four literals. Other modes (`delegate` / `work` / `fullAccess` / `ignore`) cannot be passed on the command line.

It also works under `-p` ([headless mode](headless.md)):

```bash
codebuddy -p --permission-mode acceptEdits "refactor src/utils/foo.ts"
```

You can also add the following at startup:

- `-y` / `--dangerously-skip-permissions`: equivalent to `--permission-mode bypassPermissions`; skips all permission checks

### Persistent Default: `defaultMode`

Write it to `~/.codebuddy/settings.json` or repository `.codebuddy/settings.json`:

```json
{
  "permissions": {
    "defaultMode": "acceptEdits"
  }
}
```

If `--permission-mode` is also provided at startup, the CLI argument takes precedence. The fallback order is: current session value → `permissions.defaultMode` → `default`.

### Automatic Memory of the “Pre-Plan Mode”

When entering `plan`, CodeBuddy remembers the current mode and restores it when leaving plan. This means:

- If you press `Shift+Tab` from `acceptEdits` into `plan`, the approval strategy for Read/Edit/Bash during plan still follows `acceptEdits` rules (except for the plan file, which never asks)
- When leaving plan, you return to `acceptEdits`; it will not be forcibly dropped to `default`

## Detailed Semantics by Mode

### default (Default)

A step-by-step approval mode. This is the safe option for beginners and for sensitive work.

| Tool type | Decision                                                                                            |
| :-------- | :-------------------------------------------------------------------------------------------------- |
| Read      | Path is inside a trusted directory (cwd + `permissions.additionalDirectories` + user-added `addDir`) → allow; otherwise ask |
| Edit      | Always ask                                                                                          |
| Bash      | Always ask                                                                                          |
| Other     | Always ask                                                                                          |

### acceptEdits (Auto-Approve File Edits)

Suitable when you want to keep writing and review the diff later, without being interrupted by every Edit approval prompt.

| Tool type | Decision                                                                                            |
| :-------- | :-------------------------------------------------------------------------------------------------- |
| Read      | Inside trusted directories → allow; otherwise ask                                                   |
| Edit      | **Always allow**                                                                                    |
| Bash      | Always ask                                                                                          |
| Other     | Always ask                                                                                          |

Notes:

- Only **Edit-family tools** are auto-approved (Edit / Write / NotebookEdit, etc.). This does not affect Bash — Bash always follows a separate safety classification
- “Trusted directories” are based on the workspace root + user-configured `permissions.additionalDirectories` + startup `--add-dir`
- Writes to [protected files](#protected-critical-files) still ask according to the original mode and do not use automatic allow

### plan (Explore Before Changing)

In plan mode, CodeBuddy focuses on reading code and running read-only Bash commands to investigate, writes the proposal as a plan, and then comes back for your approval. It does not apply changes to your source code.

Plan mode is not an independent “fully read-only block”; it **delegates to the pre-plan mode**:

- Read: delegates the decision to the pre-plan mode (default is `default`)
- Edit: only allowed when the target path is the current session’s **plan file**; otherwise delegates to the pre-plan mode
- Bash: delegates to the pre-plan mode
- Enter plan through `Shift+Tab` or the `EnterPlanMode` tool; exit through another `Shift+Tab` or `ExitPlanMode`

Start directly in plan mode:

```bash
codebuddy --permission-mode plan
```

### bypassPermissions (Skip All Checks)

Literally: **skip all approvals**. All Bash, Edit, network, and MCP operations execute immediately. Use only in the following scenarios:

- Isolated containers / VMs / dev containers
- Sandboxes with no external network access
- Scripted scenarios where you fully understand the consequences

Startup methods:

```bash
codebuddy --permission-mode bypassPermissions
# Equivalent
codebuddy -y
codebuddy --dangerously-skip-permissions
```

#### Disable Channel (Administrators)

Write `permissions.disableBypassPermissionsMode: "disable"` to settings at any layer:

```json
{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  }
}
```

After this is written, even if the session switches to `bypassPermissions`, the permission strategy will **fall back to `default` decisions**. It takes effect when any layer of settings (user / project / local / CLI startup flag) is set to `"disable"`.

### delegate (Multi-Agent Coordination Mode)

In `delegate` mode, the main agent can **only coordinate**: assign tasks, start subagents, and communicate across members. It does not edit files or run commands itself.

Behavior:

- Only coordination tools (Agent / TaskCreate / SendMessage, etc.) remain in the main agent’s tool set, all allowed automatically
- Implementation tools (Read / Write / Edit / Bash, etc.) are blocked, and execution is delegated to subagents

This is suitable when you explicitly want the main agent to “plan only, with specialized subagents doing the implementation” ([Agent Teams](agent-teams.md) / [Subagents](sub-agents.md)).

Press `Shift+Tab` until `delegate` appears to enter it.

### work (IDE Integration)

Set by the IDE client through the protocol; not directly exposed to CLI users. Semantics:

| Tool type | Decision                                                |
| :-------- | :------------------------------------------------------ |
| Read      | **Allow directly** (does not check trusted directories)  |
| Edit      | Always ask                                              |
| Bash      | Safe commands are allowed directly; risky ones ask       |
| Other     | Allow                                                   |

### fullAccess (IDE Integration)

Only passed through the IDE client protocol; same semantics as `bypassPermissions`.

### ignore (Subagent Only)

Only used by subagent frontmatter / options. When a subagent writes `permissionMode: ignore` in its metadata, it is treated as “do not override the parent agent’s mode” and continues using the parent session’s current mode. This value does not appear in main sessions.

## Protected Critical Files

Write operations to the following paths retain special handling even under `acceptEdits` / `bypassPermissions`:

- Repository itself: `.git`, `.gitconfig`, `.gitmodules`
- Shell config: `.bashrc` / `.bash_profile` / `.zshrc` / `.zprofile` / `.envrc`, etc.
- Package management: `.npmrc` / `.yarnrc` / `.pnpmfile.cjs` / `bunfig.toml`, etc.
- IDE / tools: `.vscode` / `.idea` / `.husky` / `.devcontainer` / `.cargo` / `.yarn` / `.mvn`
- CodeBuddy itself: `.codebuddy` (except `.codebuddy/worktrees`)
- MCP / config: `.mcp.json` / `.codebuddy.json`

## Permission Mode Inheritance for Subagents

Subagents ([Agent](sub-agents.md) tool calls and [Agent Teams](agent-teams.md) members) inherit the main session’s permission mode by default. To force an override at the team / project layer:

```json
{
  "permissions": {
    "subagentPermissionMode": "bypassPermissions"
  }
}
```

After this is written, all subagents run under `bypassPermissions`. Notes:

- Passing the `mode` parameter explicitly in an Agent tool call → **highest priority**, overrides this setting
- Writing `permissionMode: ignore` in subagent frontmatter → still runs under the main session mode (not affected by this setting)

## Working with Permission Rules

Permission modes define the “baseline”. You can layer additional rules under `permissions` in `~/.codebuddy/settings.json` or repository `.codebuddy/settings.json`:

```json
{
  "permissions": {
    "defaultMode": "default",
    "allow": ["Bash(npm test)", "Read(/etc/hosts)"],
    "ask": ["WebFetch"],
    "deny": ["Bash(rm -rf *)", "Edit(.git/**)"]
  }
}
```

- The `allow` / `ask` / `deny` layers have higher priority than mode decisions (except that `bypassPermissions` skips the entire permission layer)
- For detailed rule syntax, see [Settings](settings.md), [Security](security.md), and [IAM](iam.md)

## Related Resources

- [Agent Teams: Multi-Agent Collaboration](agent-teams.md): let the main agent focus on coordination in `delegate` mode
- [Subagents](sub-agents.md): subagent tools and permission mode inheritance
- [Hooks](hooks-guide.md): use `PreToolUse` hooks for custom allow / block behavior
- [Bash sandboxing](bash-sandboxing.md): add filesystem / network isolation at the Bash command layer
- [Settings](settings.md): complete fields for permission rules, trusted directories, `disableBypassPermissionsMode`, and more
- [CLI reference](cli-reference.md): startup parameters such as `--permission-mode` / `-y` / `--add-dir`
- [Headless mode](headless.md): use permission modes under the `-p` flow
