# Permissions

> Source: https://parallelworks.com/docs/ai/code/permissions

# Permissions

`pw code` decides what it may do on its own and what needs your approval through three layers: a **permission mode** that sets the overall level of autonomy, **allow rules** that pre-approve specific tools and commands, and a **workspace boundary** that keeps file access inside the directory you started in.

## Permission Modes

A session runs in one of four modes. The default is `accept-edits`. Each mode sets what the agent may do across reads, file edits, shell commands, and MCP tools (tools from connected [MCP servers](/docs/ai/code/mcp)).

| Mode | Reads & searches | File edits | Shell commands | MCP tools |
| --- | --- | --- | --- | --- |
| `read-only` | Allowed | Denied | Denied | Denied |
| `accept-edits` (default) | Allowed | Allowed | Prompt each time | Prompt each time |
| `plan` | Allowed | Plan files only | Denied | Denied |
| `bypass-permissions` | Allowed | Allowed | Allowed | Allowed |

[Allow rules](#allow-rules) skip the prompt in every mode except `plan`: an allowlisted command runs without asking even in `read-only` mode.

:::warning bypass-permissions runs everything
In `bypass-permissions` mode every tool call executes without prompting, including shell commands and file access outside the workspace. Use it only where that is acceptable, such as disposable environments or automation.
:::

### Plan Mode

Plan mode lets the agent work out an approach before touching anything. Reads, searches, and web fetches are allowed, but file edits are restricted to plan documents (`PLAN.md`, `plan.md`, or Markdown files inside a `plans/` directory), and shell commands are always denied, even when an allow rule matches them.

## Setting the Mode

- **At startup**: pass the `--permission-mode` flag:

  ```bash
  pw code --permission-mode read-only
  ```

- **During a session**: press <kbd>Shift</kbd>+<kbd>Tab</kbd> to cycle `read-only` → `accept-edits` → `bypass-permissions` → `plan`. The status line below the composer shows the current mode, and you can cycle it even while the agent is working. The new mode applies to its next tool call.
- **In the settings menu**: run `/settings` and activate the **Permission mode** row, which cycles through the same order.
- **In your settings file**: set the `permissionMode` key. See [Settings](/docs/ai/code/settings).

Mode changes made with <kbd>Shift</kbd>+<kbd>Tab</kbd> or `/settings` are saved as your default for future sessions. The `--permission-mode` flag overrides the saved setting for that run.

## Approval Prompts

In the default `accept-edits` mode the agent reads and edits workspace files freely but stops before every shell command and MCP tool call that no allow rule covers. The prompt shows the exact command and why it needs approval, with four choices:

<TerminalWindow>
  
</TerminalWindow>

- **Yes, allow this command**: run it once. The next command prompts again.
- **Yes, and allow this directory for the session**: run it and remember the directories it touches, so later operations on those locations (such as access outside the workspace) do not prompt again this session.
- **No, deny this command**: skip it. The agent is told the command was denied.
- **No, and provide feedback to the agent**: deny it and type an explanation the agent can act on.

Pressing <kbd>Esc</kbd> also denies the command. Approval is per command: approving one shell command does not approve the next one. To stop a recurring prompt, add an allow rule instead.

Commands the CLI classifies as destructive (for example `rm -rf`, `git reset --hard`, or a force push) prompt for confirmation in every mode except `bypass-permissions`.

In [non-interactive mode](/docs/ai/code/non-interactive) there is no way to prompt, so actions that would require confirmation fail instead. Pre-approve them with allow rules, `--add-dir`, or `--permission-mode bypass-permissions`.

## Allow Rules

Allow rules pre-approve specific tool calls so they never prompt. Manage them from inside a session with `/permissions`:

```text
/permissions                          # list the rules in effect
/permissions add Bash(git status:*)   # add a rule
/permissions remove Bash(git status:*)
/permissions remove 2                 # or remove by its number from the list
```

Rules added with `/permissions add` take effect immediately and are saved to your user-level settings, so they persist across sessions. Rules that came from project settings or the command line can only be removed for the current session.

You can also pass rules at startup with the repeatable `--allowedTools` flag, or store them under the `allowedTools` key in [settings](/docs/ai/code/settings). Rules from settings files and the flag are combined:

```bash
pw code --allowedTools 'ReadFile' --allowedTools 'Bash(git status:*)'
```

### Rule Syntax

| Rule | Effect |
| --- | --- |
| `ReadFile` | A bare tool name allows every call of that tool. |
| `Bash(git status:*)` | The `:*` suffix allows a command prefix with any arguments: here `git status` alone or followed by anything. |
| `ReadFile(/data/**)` | The `/**` suffix matches a directory and everything under it. Path-scoped rules on file tools also grant access outside the workspace. |

For shell commands, every part of a compound command must match a rule: `git status && curl example.com` only runs unprompted if both `git status` and `curl example.com` are allowlisted. Commands containing command substitution (`$(...)` or backticks) are never auto-approved.

A bare tool rule such as `ReadFile` suppresses prompts for normal calls but does not widen the tool's reach: reads outside the workspace still require a path-scoped rule, `--add-dir`, or your approval.

## Workspace Boundary

The agent works within your workspace: the directory you start `pw code` in, or the one passed with `--workspace`. Paths are fully resolved before they are checked, so symlinks cannot escape the boundary.

When the agent tries to read or write a file outside the workspace, it asks first. Choosing **Yes, and allow this directory for the session** whitelists that file's directory, so further access there does not prompt again. To grant access up front:

- `--add-dir <path>` (repeatable) approves directories for outside-workspace reads for the whole session.
- Path-scoped allow rules such as `ReadFile(/data/**)` or `WriteFile(/tmp/**)` grant persistent access.

```bash
pw code --add-dir /data --add-dir /shared/results
```

In `bypass-permissions` mode, outside-workspace access is allowed without prompting.

Commands you type yourself in [shell mode](/docs/ai/code/interface#shell-mode) (the `!` prefix) run outside the agent's permission system entirely.

## Subagents and Permissions

- **Inherited at spawn**: subagents get the session's permission mode, allow rules, and `--add-dir` directories.
- **Live changes reach them**: changing the session's mode (for example with <kbd>Shift</kbd>+<kbd>Tab</kbd>) applies to running subagents immediately, in both directions.
- **Definitions only narrow**: a [custom agent](/docs/ai/code/custom-agents) definition can restrict a subagent's mode or tools but never widen them past the session; see [Permission Clamping](/docs/ai/code/custom-agents#permission-clamping-for-definition-authors) for the exact rules.
- **Approvals stay per-subagent**: an approval prompt names the agent asking, and what you approve applies to that subagent only. Cycling the mode inside a subagent's window adjusts that subagent alone, still capped by the session.

## Related Documentation

- [pw code Overview](/docs/ai/code): Feature overview and quick start
- [Settings](/docs/ai/code/settings): The `permissionMode` and `allowedTools` keys
- [Slash Commands](/docs/ai/code/slash-commands): `/permissions` and other in-session commands
- [Non-Interactive Mode](/docs/ai/code/non-interactive): How approvals behave in one-shot runs
- [Subagents](/docs/ai/code/subagents): Delegated tasks and inherited permissions
- [Custom Agents](/docs/ai/code/custom-agents): Narrowing permissions per agent
- [MCP Servers](/docs/ai/code/mcp): How MCP tools are configured and approved
- [Interface & Shortcuts](/docs/ai/code/interface): Keyboard shortcuts including <kbd>Shift</kbd>+<kbd>Tab</kbd>