Skip to main content
Every tool invocation passes through a centralized permission check before execution. The permission system lets you define which operations Claude can perform automatically and which require explicit approval.

​
Permission modes

The active permission mode applies globally to all tool invocations for the current session.
ModeBehavior
defaultPrompts the user for each potentially destructive operation
planShows the full execution plan, asks once for batch approval
bypassPermissionsAuto-approves all operations (for trusted environments only)
autoML-based classifier automatically decides (experimental)
bypassPermissions skips all confirmation prompts. Only use this in sandboxed or fully trusted environments where unreviewed file and shell operations are acceptable.

​
Rule syntax

Permission rules use wildcard patterns to match tool invocations. Rules are evaluated in order — the first match wins. 
Bash(git *)           # Allow all git commands without prompting
Bash(npm test)        # Allow 'npm test' specifically
FileEdit(/src/*)      # Allow edits to anything under /src/
FileRead(*)           # Allow reading any file
The pattern format is ToolName(argument-pattern), where * is a wildcard matching any sequence of characters. Examples: 
Bash(git log *)             # Allow git log with any arguments
Bash(git commit -m *)       # Allow git commit with a message flag
FileEdit(/home/user/app/*)  # Allow edits within a specific directory
FileRead(/etc/*)            # Allow reading /etc/ files

​
How checkPermissions() works

1

Tool invocation

The Query Engine calls a tool with its input arguments and execution context.
2

Permission check

checkPermissions(input, context) is called on the tool before any action is taken.
3

Rule matching

The permission handler checks the invocation against configured rules in PermissionContext. If a matching allow rule exists, the tool proceeds automatically.
4

User prompt (if needed)

If no rule auto-approves the action, the user is prompted via the terminal (CLI) or the IDE UI (bridge mode). The user can approve, deny, or create a persistent rule.
5

Logging

All permission decisions — including auto-approvals — are recorded via permissionLogging.ts for auditability.

​
User prompting flow

When a tool requires approval, Claude Code presents the proposed action and waits for one of these responses:
  • Yes — approve this single invocation
  • Yes, always — approve and add a persistent allow rule
  • No — deny and report back to the model
  • Edit rule — customize the pattern before saving
In plan mode, all tool calls in the upcoming execution plan are shown together, and the user approves or rejects the entire batch before any tool runs.

​
Key files

FilePurpose
src/hooks/toolPermission/PermissionContext.tsHolds the active permission rules and mode for a session
src/hooks/toolPermission/handlers/Per-tool permission handler implementations
src/hooks/toolPermission/permissionLogging.tsAudit logging for all permission decisions
src/types/permissions.tsTypeScript types for permission rules and contexts

Build docs developers (and LLMs) love

Get started for freeTalk to us