CClaude Code Guide中文

Claude Code permissions

Permissions decide what Claude Code can read, edit, run, or access through tools. Good permission design balances speed with the risk level of the repository.

Last verified
Applies to
Claude Code 2.1.x. CLI spellings were checked on local version 2.1.198; current official docs may describe newer 2.1.x behavior.
Verification method
Official documentation, CLI reference, and changelog reviewed on 2026-07-19. Permission modes and flag names were checked in local help; deny precedence and file-rule limits are documentation-based.
Official sources
Permissions referenceCLI referenceChangelog

Reproducible practice

Design a read-first permission profile and test its denial path

Start from plan mode, allow only needed inspection tools, deny secret reads, and verify that denial is visible before implementation.

Prerequisites

  • A shell session allowed to create a disposable directory outside every real repository.
  • A placeholder .env containing no real secret; never run this exercise against existing settings.
  • A list of commands the task genuinely needs.

Steps

  1. Create a disposable repository and local-only deny rule

    Create a unique temporary repository first, then deny reading .env. The command never opens or overwrites settings in an existing repository.

    Step 1
    PERMISSION_LAB=$(mktemp -d "${TMPDIR:-/tmp}/claude-permissions.XXXXXX")
printf '%s\n' "$PERMISSION_LAB"
cd "$PERMISSION_LAB"
git init -q
mkdir .claude
printf '%s\n' '{"permissions":{"deny":["Read(.env)"]}}' > .claude/settings.local.json
printf '%s\n' 'placeholder-only' > .env

  2. Validate configuration syntax

    A parseable file is necessary but does not prove rule behavior.

    Step 2
    jq -e . .claude/settings.local.json >/dev/null

  3. Start with narrow tools and plan mode

    Allow reads and searches needed for research without enabling edits.

    Step 3
    claude --permission-mode plan --allowedTools "Read" "Grep" "Bash(git status --short)"

  4. Exercise allow and deny paths

    Ask to inspect a normal source file, then ask to read .env. The second request should be blocked by the deny rule.

Expected result

Normal inspection works, the secret-path request is denied, and no file edit occurs while the session remains in plan mode.

Validation

  • Inspect the permission prompt or denial rather than relying on the model's description.
  • Run git status to verify that only the intentional local settings and placeholder fixture changed.
  • Review every additional allowed tool against the task's actual need.

Failure handling

Deny does not match

Use documented Read/Edit path syntax and check the path anchor; do not substitute unsupported Write(path) assumptions.

A subprocess still reads data

File rules do not govern every arbitrary subprocess; enable OS sandboxing for stronger enforcement.

Cleanup or rollback

  • Return to the original directory, verify PERMISSION_LAB is the printed mktemp path, then remove only that disposable directory.
  • Exit the session before broadening permissions for a different task.

Boundaries and when not to use it

  • Deny rules from any scope take precedence over allow rules and hooks.
  • Plan mode and permission rules are application controls, not a substitute for OS isolation or secret management.

Permission modes

Different modes fit different stages. Exploration can start with narrow access, implementation may need edit permission, and sensitive commands should remain explicit.

Allow and deny rules

Rules are useful for repeated commands and known safe paths. Deny rules protect generated files, secrets, infrastructure state, or commands that should not run without a human decision.

Approval prompts

Approval prompts are part of the safety model. Treat them as a chance to inspect command intent, working directory, affected files, and whether the action matches the plan.

Sensitive repositories

For production infrastructure, security-sensitive code, or private data, start with the smallest useful access and expand only after the task and verification path are clear.

CommandDescription
/permissionsConfigure approval rules inside a session.
--permission-mode planRequire planning before edits are allowed.
--permission-mode bypassPermissionsSkip prompts; use only in trusted automation with review gates.
--allowedTools "Read"Auto-approve only read operations for research tasks.
--disallowedTools "Edit"Remove edit capability from the model context entirely.

Permission design examples

Good permission rules match real team habits: safe read commands auto-approved, destructive commands denied, and everything else reviewed.

CI automation

Use explicit allow lists for git, test, and lint commands; deny branch pushes outside the workflow.

Read guide

Permission checklist

Related topics

HooksMCPCI/CDTroubleshooting