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

You configure Claude Code's permission system by editing ~/.claude.json or project-level 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.

{
  "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 in the project root or under examples/settings/ (project-specific settings)
3. Remote settings (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 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:

{
  "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 provides minimal restrictions:

{
  "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 entry 1434), you can use wildcards to match specific Bash command patterns:

{
  "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 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)

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 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 entry 1438)

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

Summary

• Configure permissions by editing ~/.claude.json or 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 and 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 in your project root for repository-specific rules. Claude Code also checks 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 configurations, so ensure you are running a current version.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}