# How to Configure the Permission System in Claude Code: A Complete Guide

> Configure Claude Code's permission system by editing .claude.json or settings.json. Define ask, deny, and sandbox rules to control tool execution automatically, require approval, or block tools.

- Repository: [Anthropic/claude-code](https://github.com/anthropics/claude-code)
- Tags: how-to-guide
- Published: 2026-04-02

---

**You configure Claude Code's permission system by editing `~/.claude.json` or project-level [`settings.json`](https://github.com/anthropics/claude-code/blob/main/settings.json) files to define `ask`, `deny`, and `sandbox` rules that control whether tools run automatically, require approval, or are blocked entirely.**

The **permission system** in Claude Code acts as a security gatekeeper for AI-driven operations. According to the `anthropics/claude-code` repository, this system determines whether tools like `Bash`, `WebSearch`, and `Write` execute automatically, prompt for user confirmation, or return permission errors. You control these behaviors through JSON configuration files that the engine reads at startup and merges with any remote policy settings.

## Core Permission Concepts

Claude Code organizes permissions around several key configuration fields that you set in your settings files.

### Ask and Deny Lists

The **`permissions.ask`** array lists tool names that always trigger a user confirmation dialog before execution. The **`permissions.deny`** array contains tools that Claude Code will never run, returning an error instead.

```json
{
  "permissions": {
    "ask": ["Bash", "Write"],
    "deny": ["WebSearch", "WebFetch"]
  }
}

```

When a tool matches an `ask` rule, the UI displays a modal asking *"Allow Bash command …?"* with options to allow, deny, or defer the decision. Denied tools are logged for audit and appear in the `/permissions` screen under the Recent tab.

### Bypass Permission Controls

The **`permissions.disableBypassPermissionsMode`** field accepts the value `"disable"` to hide the "bypass-permissions" toggle in the UI. This prevents accidental clicks that would otherwise allow all tools to run unrestricted, enforcing stricter compliance in enterprise environments.

### Managed Settings Enforcement

Enterprise deployments use **`allowManagedPermissionRulesOnly`** and **`allowManagedHooksOnly`** booleans. When set to `true`, these flags instruct Claude Code to apply only permission rules or hooks supplied by managed settings (e.g., enterprise policies), ignoring user-defined rules in local configuration files.

### Sandbox Configuration

The **`sandbox`** object controls Bash execution isolation and network restrictions:

- **`autoAllowBashIfSandboxed`**: Boolean allowing automatic Bash execution when running in a sandboxed environment
- **`excludedCommands`**: Array of specific Bash commands to block
- **`network`**: Object defining `allowedDomains`, `allowUnixSockets`, `httpProxyPort`, and other network restrictions
- **`enableWeakerNestedSandbox`**: Boolean controlling nested sandbox behavior for complex execution environments

## Configuration File Locations

Claude Code loads permissions from multiple locations in a specific precedence order:

1. **`~/.claude.json`** in your home directory (user-wide settings)
2. **[`settings.json`](https://github.com/anthropics/claude-code/blob/main/settings.json)** in the project root or under `examples/settings/` (project-specific settings)
3. **Remote settings** ([`remote-settings.json`](https://github.com/anthropics/claude-code/blob/main/remote-settings.json)) loaded from enterprise policy servers

When conflicts arise, managed and remote settings take precedence over local user configurations. Referenced in the [`CHANGELOG.md`](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) entry for version 3.16, the system specifically fixed managed settings not being applied at startup, ensuring enterprise policies override local preferences.

You must restart Claude Code or reload the session for new permission rules to take effect.

## Permission Configuration Examples

### Strict Security Mode

For high-security environments, use the configuration from [`examples/settings/settings-strict.json`](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-strict.json):

```json
{
  "permissions": {
    "disableBypassPermissionsMode": "disable",
    "ask": ["Bash"],
    "deny": ["WebSearch", "WebFetch"]
  },
  "allowManagedPermissionRulesOnly": true,
  "allowManagedHooksOnly": true,
  "strictKnownMarketplaces": [],
  "sandbox": {
    "autoAllowBashIfSandboxed": false,
    "network": {
      "allowUnixSockets": [],
      "allowAllUnixSockets": false,
      "allowLocalBinding": false,
      "allowedDomains": [],
      "httpProxyPort": null,
      "socksProxyPort": null
    },
    "enableWeakerNestedSandbox": false
  }
}

```

This configuration forces approval for all Bash commands, blocks web search tools, disables bypass toggles, and restricts network access entirely.

### Minimal Lax Mode

For trusted environments, the [`examples/settings/settings-lax.json`](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-lax.json) provides minimal restrictions:

```json
{
  "permissions": {
    "disableBypassPermissionsMode": "disable"
  },
  "strictKnownMarketplaces": []
}

```

This allows most tools to run automatically while still preventing the bypass toggle from being hidden.

### Wildcard Bash Rules

As implemented in version 2.2.0 (see [`CHANGELOG.md`](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) entry 1434), you can use wildcards to match specific Bash command patterns:

```json
{
  "permissions": {
    "ask": ["Bash(git *)"],
    "deny": ["Bash(rm *)"]
  }
}

```

This rule triggers confirmation prompts **only** for Git commands while automatically blocking removal commands, allowing other Bash operations like `npm install` to proceed without interruption.

## How the Permission Engine Works

The permission system processes requests through a normalization and evaluation pipeline:

1. **Loading Phase**: At startup, Claude Code reads local settings, then overlays remote or policy-set JSON configurations (as noted in [`CHANGELOG.md`](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) version 6.28, remote environments ignore `permissions.defaultMode` values other than `acceptEdits` or `plan`)

2. **Rule Normalization**: The engine converts each permission into a **tool-action tuple** (`allow`, `deny`, or `ask`), supporting wildcards for Bash command matching

3. **Hook Integration**: Pre-tool-use hooks can override or augment decisions. The UI displays hook source information when a hook requires confirmation (feature added in version 4.59 per [`CHANGELOG.md`](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md))

4. **Execution Decision**: Final decisions are cached per-project, per-user, or per-session, with denied commands appearing in the `/permissions` Recent tab

## CLI Flags for Permission Overrides

You can temporarily override permission settings using command-line flags:

- **`--dangerously-skip-permissions`**: Bypasses all permission checks (useful for automated CI/CD scripts). Note that version 15.78 fixed an issue where this flag was not loading when using [`.mcp.json`](https://github.com/anthropics/claude-code/blob/main/.mcp.json) configurations

- **`--disallowedTools`**: Explicitly blocks specific tool names, overriding user settings. Supports agent-specific syntax like `Task(AgentName)` (added in version 2.2.0, see [`CHANGELOG.md`](https://github.com/anthropics/claude-code/blob/main/CHANGELOG.md) entry 1438)

- **`--print`**: Prints the execution plan without running tools, suppressing permission prompts

## Summary

- Configure permissions by editing `~/.claude.json` or [`settings.json`](https://github.com/anthropics/claude-code/blob/main/settings.json) with `permissions.ask`, `permissions.deny`, and `sandbox` keys
- Use `disableBypassPermissionsMode: "disable"` to prevent users from bypassing restrictions in the UI
- Set `allowManagedPermissionRulesOnly: true` to enforce enterprise policy compliance over local settings
- Reference [`examples/settings/settings-strict.json`](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-strict.json) and [`examples/settings/settings-lax.json`](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings-lax.json) for complete configuration templates
- Restart Claude Code after editing permissions, and use `/permissions` to review active rules interactively

## Frequently Asked Questions

### Where do I place my Claude Code permission configuration file?

Place your primary configuration file at `~/.claude.json` in your home directory for user-wide settings, or create a [`settings.json`](https://github.com/anthropics/claude-code/blob/main/settings.json) in your project root for repository-specific rules. Claude Code also checks [`examples/settings/settings.json`](https://github.com/anthropics/claude-code/blob/main/examples/settings/settings.json) for local testing configurations. The system loads these at startup and merges them with any remote policy files.

### Can I use wildcards to match specific Bash commands in permission rules?

Yes, wildcard patterns are supported for Bash commands as of version 2.2.0. Use syntax like `"Bash(git *)"` in your `permissions.ask` or `permissions.deny` arrays to match command prefixes. This allows you to require approval only for Git operations while allowing other commands to run automatically, or to block dangerous patterns like `"Bash(rm *)"`.

### How do enterprise managed settings interact with my local configuration?

When `allowManagedPermissionRulesOnly` is set to `true` in managed settings, Claude Code applies only permission rules supplied by enterprise policy servers and ignores your local `~/.claude.json` settings. Remote settings take precedence over local configurations, and managed hooks override user-defined hooks when `allowManagedHooksOnly` is enabled.

### What happens if I use the `--dangerously-skip-permissions` flag?

The `--dangerously-skip-permissions` flag bypasses all permission checks, allowing Claude Code to execute any tool without prompting for approval. Use this only in secure automated environments or CI/CD pipelines. Be aware that version 15.78 fixed an issue where this flag failed to load when using [`.mcp.json`](https://github.com/anthropics/claude-code/blob/main/.mcp.json) configurations, so ensure you are running a current version.