Claude Code Permissions: Control What Your AI Assistant Can Do

Permission boundaries exist because Claude Code can take destructive actions faster than a human can stop it. A single bash command (rm -rf src/) or a careless git push --force can wipe out hours of work. Unlike a developer who pauses to think, Claude Code will execute a command if it believes the action serves your goal—which is exactly why you want explicit permission gates.

Real scenarios where permissions save projects: You want Claude to run npm test and commit passing changes, but you don't want it running npm publish to push a broken package to the registry. You want it to read your application code in src/, but deny it access to .env, .vercel/, or node_modules/. You want it to fetch documentation from trusted domains but block access to your internal wiki or private GitHub repos. Each of these requires a permission rule—otherwise, the AI will try the operation if it thinks it's necessary.

Claude Code operates in one of several permission modes, each defining the default behavior when no specific rule matches. Think of modes as your baseline trust level—then override that baseline with specific allow and deny rules for fine-grained control.

Manual mode is the safest: Claude Code asks for approval before every tool invocation. This is slow but gives you full visibility and control; use it when onboarding Claude Code to a new project or when working with sensitive operations. Auto mode trusts Claude Code to act without prompting for non-destructive reads; it still prompts for writes and risky bash commands. Plan mode (the default for most workflows) prompts for risky operations like git push, rm, and writes to production paths, but executes safe reads like ls and cat without asking. dontAsk mode runs almost everything without prompting, except for operations explicitly denied by your rules. bypassPermissions (used in automation scripts) removes all prompts and applies only deny rules—useful in CI/CD pipelines where you cannot interact. acceptEdits is a convenience mode that auto-approves file edits without prompting.

Permission rules come in three flavors, evaluated in a strict order: deny, ask, then allow. A deny rule will always block the operation, regardless of whether an allow rule exists. An ask rule prompts the user for approval. An allow rule executes the operation immediately.

Deny rules typically protect broad categories—all .env files, all git push operations, all npm publish commands. Ask rules narrow down to specific operations where you want a safety check—edit src/config.ts, run git push to origin/main only. Allow rules grant explicit permission—read any file in src/, run npm test, fetch from docs.example.com. The key insight: start with deny, then be selective about allow. This way, if the AI encounters an operation you haven't explicitly thought about, it will ask before proceeding, rather than silently running it.

Permission rules use glob patterns (similar to .gitignore) to scope which files, commands, or domains are affected. A pattern like src/** means 'all files under src recursively,' while *.env means 'any file ending in .env in the project root.' Precision matters: overly broad patterns (like ** or /*) defeat the purpose of permissions, while overly narrow patterns might accidentally allow something dangerous.

Exact path matches always take precedence over glob patterns. If you define a rule for /src/config.ts (exact) and another for /src/** (glob), the exact rule wins. This is useful when you want to block one critical file while allowing reads to its parent directory—for example, deny /secrets.json (exact) while allowing /src/**. Symlinks behave differently depending on the rule type: a deny rule follows symlinks (if /config symlinks to /.private/config, the deny applies to both paths), but an allow rule respects the target (allows read to the symlink only if the target matches the allow rule). This distinction prevents attackers from bypassing deny rules via symlink tricks.

Each tool (Bash, Read/Edit, WebFetch, MCP, Agents) has its own rule syntax and risk profile. Bash rules filter by command name and arguments. Read/Edit rules filter by file path and glob patterns. WebFetch rules filter by domain and protocol. Understanding each tool type prevents accidentally opening security holes.

Bash rules can allow or deny entire commands or filter by partial match. A rule like allow npm test permits the literal command npm test. A rule like deny rm blocks any rm command, including rm -rf. Read-only bash commands (like ls, cat, grep, ps, curl) never prompt in plan or auto mode because they don't change state. Dangerous bash commands (like git push, rm, docker run, ssh) always prompt or require an allow rule. Read/Edit rules use file paths; allow src/** grants read to all files under src. Edit rules require explicit permission—you cannot implicitly allow edits even in auto mode; Claude Code always prompts unless you set an explicit allow rule. WebFetch/WebSearch rules whitelist or blacklist domains. You might allow docs.anthropic.com but deny internal-wiki.company.com. MCP (Model Context Protocol) and Agent rules inherit permissions from the parent—if the parent (Claude Code) is in plan mode, subagents also run in plan mode, but parent deny rules apply to subagents too.

Let's set up permissions for a realistic scenario: a team Node.js project where you want Claude Code to run tests and commit changes, but not publish to npm. You want it to read source files but not access deployment secrets or vendor code.

Your settings.json starts with a deny-first foundation: block all sensitive paths (.env, .vercel, deployment keys), block all npm publish and git force-push. Then ask for approval on code deletes and direct-to-main pushes—this prompts for confirmation so you catch mistakes. Finally, allow the safe operations: read all source code, run npm test, commit to feature branches, fetch documentation. When Claude Code tries to run npm test, the rule allow bash npm test is matched and the command runs silently. If Claude Code later tries npm publish, the deny rule deny bash npm publish blocks it immediately. If Claude Code tries to commit to main, the ask rule prompts you first—you see the diff and approve or reject. This layered approach keeps the project secure while letting the AI automate routine tasks.

Claude Code evaluates permission rules in a strict order: first deny, then ask, then allow. If a deny rule matches, the operation is blocked—period. If no deny matches but an ask rule does, Claude Code prompts you. If no deny or ask matches but an allow rule does, it runs silently. If none of the three match, the permission mode determines the default: plan mode prompts, auto mode allows, manual mode always prompts.

Compound bash commands (those using &&, ||, ;, or |) are parsed and each step is evaluated separately. A command like npm test && git commit is split into npm test and git commit, and permission rules are applied to each. If either step is denied, the whole pipeline is blocked. Wrappers like timeout, nice, xargs, docker exec, and env are stripped before rule matching—so a rule deny rm will block both rm file.txt and timeout 10 docker exec container rm file.txt. This prevents bypassing rules by wrapping commands.

When you're designing permission rules, a simple decision tree helps you categorize each operation. For any operation, first ask: Is it destructive or dangerous? If yes, deny it by default. Examples: git push --force (rewrites history), rm -rf (deletes data), npm publish (releases to the world), docker push (deploys images). These should all be denied unless there's an explicit exception.

If the operation isn't inherently dangerous, ask: Would it be useful to get user approval? If the operation is usually safe but warrants a check (like pushing to a remote repository where you'd want to see what's being pushed), add an ask rule so Claude Code prompts you. If the operation is routine and safe (like running tests, checking git status, reading documentation), allow it silently. This decision tree ensures you neither over-constrain (making the AI too slow) nor under-constrain (opening security holes).

For complex permission scenarios, Claude Code supports PreToolUse hooks—custom code that runs before a tool invocation and can modify permissions, inject environment variables, or log sensitive operations. A hook receives the tool request, inspects it, and returns a modified request or a denial. This lets you layer additional logic on top of static rules.

Common use cases for hooks: inject temporary credentials into the environment before running a deploy script, log all aws cli commands to an audit trail, validate that a database migration script contains only safe operations before allowing it, or require an additional approval step for risky tools by integrating with your team's approval system. Hooks are written in JavaScript/TypeScript and run in a sandboxed context—they cannot access the file system or network directly, but they can read the tool request and return metadata about it.

Permission rules control what Claude Code's AI can decide to do, but they don't replace operating-system-level security. A user running Claude Code in a terminal inherits all the permissions of their shell—if your OS user can delete /home/user/project, Claude Code can delete /home/user/project regardless of permission rules. Permission rules are a behavioral guardrail, not a security boundary.

For strong isolation in production environments, combine Claude Code permissions with OS-level controls: run Claude Code in a Docker container with a restricted file system (read-only / except for specific mounted volumes), use a dedicated unprivileged OS user, or deploy Claude Code in a Kubernetes pod with resource quotas and network policies. In CI/CD pipelines, use separate credentials for each stage (e.g., deploy role with no delete permissions) so even if the AI requests rm -rf /, the AWS/GCP/cloud provider identity limits the damage. Permission rules shine for local development and team collaboration where you want to prevent accidental mistakes and enforce safe practices—but for financial data, customer PII, or production infrastructure, layer OS-level controls too. See Claude Code Sandboxing for deeper isolation strategies.