YouTip

Claude Code uses a tiered permission system to balance functionality and security, supporting fine-grained permission rules, permission modes, and sandbox policies to control what Claude can access and execute. Properly configuring permissions allows AI to complete tasks efficiently while preventing accidental operations from damaging code or leaking sensitive files.\\n\\n> Starting from Claude Code v1.1.1, a new permission configuration method is recommended. The old `tools` boolean configuration is still supported, but migrating to the new permission rule syntax is recommended.\\n\\n* * *\\n\\n## Permission System Overview\\n\\nClaude Code's permission system divides operations into three categories, with different default permission policies for different types of operations:\\n\\n| Tool Type | Example | Requires Approval | Permanent Allow Behavior |\\n| --- | --- | --- | --- |\\n| Read-only operations | File reading, Grep search | No | Not applicable |\\n| Bash commands | Shell command execution | Yes | Permanent per project directory and command |\\n| File modifications | Edit/Write files | Yes | Until session ends |\\n\\n* * *\\n\\n## Three Permission Actions\\n\\nEach permission rule ultimately resolves to one of the following three actions:\\n\\n| Action | Effect | Applicable Scenarios |\\n| --- | --- | --- |\\n| `"allow"` | Runs automatically without approval | Low-risk, high-frequency operations, such as git status, npm run build |\\n| `"ask"` | Prompts for approval, you decide whether to allow | Operations with some risk, such as file writing, dangerous command execution |\\n| `"deny"` | Blocked directly, will not execute and will not prompt | Explicitly disallowed dangerous operations, such as git push, rm -rf |\\n\\n> **Rule Priority: deny → ask → allow.** The first matching rule wins, so deny rules always take precedence over allow and ask.\\n\\n* * *\\n\\n## Permission Modes\\n\\nPermission modes control whether Claude asks the user before executing an operation. Different tasks require different levels of autonomy.\\n\\n### 1. Six Available Modes\\n\\n| Mode | Description | Best Use Case |\\n| --- | --- | --- |\\n| `default` | Standard behavior: prompts for permission on first use of each tool | Getting started, sensitive work requiring full supervision |\\n| `acceptEdits` | Automatically accepts file edit permissions for the session, except for protected directories | Iterating on code being reviewed |\\n| `plan` | Plan Mode: Claude can analyze but cannot modify files or execute commands | Exploring codebase, planning refactoring |\\n| `auto` | Automatically approves tool calls with background safety checks (research preview) | Long-running tasks, reducing prompt fatigue |\\n| `dontAsk` | Automatically rejects tool calls unless pre-approved via permission rules | Locked down environments, CI pipelines |\\n| `bypassPermissions` | Skips permission prompts, but still prompts for writes to protected directories | Isolated containers and VMs only |\\n\\n> **Protected Directory Note:** Regardless of mode, writes to `.git`, `.vscode`, `.idea`, `.husky`, and `.claude` are never automatically approved, except for `.claude/commands`, `.claude/agents`, and `.claude/skills`.\\n\\n### 2. Switching Permission Modes\\n\\n**Switch during session:** Press `Shift+Tab` to cycle through `default` → `acceptEdits` → `plan` → `auto`\\n\\n**Specify mode at startup:**\\n\\nclaude --permission-mode plan claude --permission-mode bypassPermissions\\n**Set as default mode (settings.json):**\\n\\n## Instance\\n\\n{\\n\\n"permissions":{\\n\\n"defaultMode":"acceptEdits"\\n\\n}\\n\\n}\\n\\n* * *\\n\\n## Permission Rule Syntax\\n\\n### 1. Basic Format\\n\\nPermission rules follow the format `Tool` or `Tool(specifier)`:\\n\\n## Instance\\n\\n{\\n\\n"permissions":{\\n\\n"allow":["Bash","WebFetch","Read"],\\n\\n"deny":\\n\\n}\\n\\n}\\n\\n### 2. Matching All Tool Uses\\n\\nA rule without a specifier matches all uses of that tool:\\n\\n| Rule | Effect |\\n| --- | --- |\\n| `Bash` | Matches all Bash commands |\\n| `WebFetch` | Matches all network fetch requests |\\n| `Read` | Matches all file reads |\\n| `Edit` | Matches all file edits |\\n\\n`Bash(*)` is equivalent to `Bash`, both have the same effect.\\n\\n### 3. Fine-grained Control Using Specifiers\\n\\n## Instance\\n\\n{\\n\\n"permissions":{\\n\\n"allow":[\\n\\n"Bash(npm run build)",// Matches exact commands\\n\\n"Read(./.env)",// Matches reading from the current directory .env Files\\n\\n"WebFetch(domain:example.com)"// Matches requests to example.com GET requests\\n\\n]\\n\\n}\\n\\n}\\n\\n### 4. Wildcard Patterns\\n\\nBash rules support glob patterns with `*`, and wildcards can appear anywhere in the command:\\n\\n## Instance\\n\\n{\\n\\n"permissions":{\\n\\n"allow":[\\n\\n"Bash(npm run *)",// Match npm run build, npm run test, etc..\\n\\n"Bash(git commit *)",// Matches git commit -m "message" etc.\\n\\n"Bash(git * main)",// Match git checkout main, git merge main, etc..\\n\\n"Bash(* --version)",// Matches any command with the --version argument\\n\\n"Bash(* --help *)"// Matches any command with the --help argument\\n\\n],\\n\\n"deny":[\\n\\n"Bash(git push *)"// Blocks all git push operations\\n\\n]\\n\\n}\\n\\n}\\n\\n> **Note the space before the wildcard:** `Bash(ls *)` matches `ls -la` but not `lsof`; `Bash(ls*)` matches both.\\n\\n* * *\\n\\n## Tool-Specific Permission Rules\\n\\n### 1. Bash Commands\\n\\n| Rule | Match Example |\\n| --- | --- |\\n| `Bash(npm run build)` | Only `npm run build` |\\n| `Bash(npm run test *)` | `npm run test`, `npm run test --coverage` |\\n| `Bash(npm *)` | Any command starting with npm |\\n| `Bash(* install)` | Any command ending with install |\\n| `Bash(git * main)` | `git checkout main`, `git merge main` |\\n\\n> **Important Limitation:** Bash permission patterns attempting to constrain command arguments can be fragile. Options before URLs, different protocols, redirections, variables, and extra spaces can all cause mismatches. It is recommended to use the WebFetch tool with `domain:` permissions for URL filtering.\\n\\n### 2. Read and Edit (File Operations)\\n\\nFile paths support multiple path prefix patterns:\\n\\n| Pattern Prefix | Meaning | Example |\\n| --- | --- | --- |\\n| `//path` | Absolute path (from file system root) | `Read(//Users/alice/secrets/**)` matches `/Users/alice/secrets/**` |\\n| `~/path` | Home directory path | `Read(~/Documents/*.pdf)` matches `/Users/alice/Documents/*.pdf` |\\n| `/path` | Relative to project root | `Edit(/src/**/*.ts)` matches `/src/**/*.ts` |\\n| `path` or `./path` | Relative to current directory | `Read(*.env)` matches `/*.env` |\\n\\n## Instance\\n\\n{\\n\\n"permissions":{\\n\\n"allow":[\\n\\n"Edit(/docs/**)",// Allows editing Files under the project's docs directory\\n\\n"Read(~/.zshrc)",// Allows reading from the home directory .zshrc\\n\\n"Edit(//tmp/scratch.txt)",// Allows editing temporary Files with absolute paths\\n\\n"Read(src/**)"// Allows reading Files in the src subdirectory of the current directory\\n\\n],\\n\\n"deny":[\\n\\n"Read(*.env)",// Blocks reading .env Files（Prevents secret leakage)\\n\\n"Edit(//etc/**)"// Blocks editing system directory Files\\n\\n]\\n\\n}\\n\\n}\\n\\n> **Note:** Read and Edit deny rules do not apply to `cat .env` in Bash subprocesses. For OS-level enforcement, enable the sandbox.\\n\\n### 3. WebFetch (Network Requests)\\n\\n## Instance\\n\\n{\\n\\n"permissions":{\\n\\n"allow":[\\n\\n"WebFetch(domain:github.com)",// Allows access to GitHub\\n\\n"WebFetch(domain:api.example.com)"// Allows access to internal APIs\\n\\n],\\n\\n"deny":[\\n\\n"WebFetch(domain:untrusted.com)"// Blocks access to untrusted domains\\n\\n]\\n\\n}\\n\\n}\\n\\n### 4. MCP (Model Context Protocol)\\n\\n## Instance\\n\\n{\\n\\n"permissions":{\\n\\n"allow":[\\n\\n"mcp__puppeteer",// Allows any tools provided by the puppeteer server\\n\\n"mcp__puppeteer__*"// Allows all tools from the puppeteer server\\n\\n],\\n\\n"deny":[\\n\\n"mcp__puppeteer__puppeteer_navigate"// Blocks specific tools\\n\\n]\\n\\n}\\n\\n}\\n\\n### 5. Agent (Sub-agents)\\n\\n## Instance\\n\\n{\\n\\n"permissions":{\\n\\n"allow":[\\n\\n"Agent(Explore)",// Allows using the Explore sub-agent\\n\\n"Agent(Plan)"// Allows using the Plan sub-agent\\n\\n],\\n\\n"deny":[\\n\\n"Agent(my-custom-agent)"// Blocks custom sub-agents\\n\\n]\\n\\n}\\n\\n}\\n\\n* * *\\n\\n## Working Directory Configuration\\n\\nBy default, Claude Code only allows access to the working directory at startup and its subdirectories. If you need to access paths outside the project directory, you must configure it explicitly.\\n\\n### 1. Extending Access\\n\\n* **During startup:** Use the `--add-dir ` CLI argument\\n* **During session:** Use the `/add-dir` command\\n* **Persistent configuration:** Add to `additionalDirectories` in settings.json\\n\\n## Instance\\n\\n{\\n\\n"additionalDirectories":[\\n\\n"~/projects/personal/**",// Allows access to personal project directories\\n\\n"~/projects/work/**",// Allows access to working project directories\\n\\n"~/dotfiles/**"// Allows access to configuration Files directories\\n\\n]\\n\\n}\\n\\n### 2