Guia Completo de Permissões do Claude Code | settings.json, Hooks e Allowlist Explicados

O Claude Code possui capacidades extremamente poderosas de operação de arquivos e execução de comandos. As permissões (permissions) são o que permite controlar esse poder com segurança. Supere o estado de “usar sem realmente entender” e projete um Claude Code que funcione exatamente como pretendido.

Este artigo explica detalhadamente, com código funcional, todas as configurações do .claude/settings.json, os padrões de implementação de Hooks e o design de permissões por ambiente.

Visão Geral das Permissões

As permissões do Claude Code são controladas em 3 níveis.

Nível	Chave	Comportamento
Permitir	`allow`	Executa automaticamente sem diálogo de confirmação
Perguntar	`ask`	Requer aprovação do usuário a cada vez
Negar	`deny`	Não pode ser executado de forma alguma (bloqueado com erro)

As configurações são oficialmente gerenciadas por settings.json. Use ~/.claude/settings.json para configurações do usuário, .claude/settings.json para regras compartilhadas pelo time e .claude/settings.local.json para overrides pessoais. ~/.claude.json ainda pode guardar estado como MCP, mas regras de permissão devem ser tratadas como configuração de settings.json.

Prioridade (maior primeiro):
Managed settings
    > Argumentos de linha de comando
        > Local .claude/settings.local.json
            > Project .claude/settings.json
                > User ~/.claude/settings.json

Permission rules são mescladas entre scopes e avaliadas na ordem deny -> ask -> allow

Estrutura Básica do settings.json

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm run *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push --force*)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)"
    ]
  },
  "hooks": {
    "PreToolUse": [],
    "PostToolUse": []
  }
}

Nomes de Ferramentas e Sintaxe de Padrões

As permissões são escritas no formato “NomeFerramenta(padrão de argumento)”.

Lista das Principais Ferramentas

Nome da Ferramenta	Descrição
`Read`	Leitura de arquivos
`Write`	Criação de novos arquivos
`Edit`	Modificação parcial de arquivos existentes
`Bash`	Execução de comandos shell
`Glob`	Busca por padrão de arquivos
`Grep`	Busca de conteúdo
`WebFetch`	Busca de URL
`Agent`	Inicialização de sub-agente

Sintaxe de Padrões

"Read(**)"          // Permitir leitura de todos os arquivos
"Read(src/**)"      // Permitir apenas sob src/
"Read(*.md)"        // Permitir apenas arquivos .md
"Bash(npm run *)"   // Permitir apenas comandos que começam com npm run
"Bash(git *)"       // Permitir todos os comandos git
"Bash(rm -rf *)"    // Negar rm -rf

** corresponde a todos os caminhos incluindo diretórios; * corresponde a um único segmento.

Padrões Práticos

Padrão 1: Desenvolvimento Solo (relativamente permissivo)

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm *)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git add*)",
      "Bash(node *)",
      "Bash(echo *)",
      "Bash(cat *)",
      "Bash(ls *)"
    ],
    "deny": [
      "Bash(rm -rf /)",
      "Bash(rm -rf ~*)",
      "Bash(git push --force *main*)",
      "Bash(git push --force *master*)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(rm *)"
    ]
  }
}

Padrão 2: Desenvolvimento em Equipe (focado em segurança)

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(npm run lint)",
      "Bash(npm run test)",
      "Bash(npm run typecheck)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git branch*)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Bash(git push -f*)",
      "Bash(git reset --hard*)",
      "Bash(git rebase *main*)",
      "Bash(git rebase *master*)",
      "Bash(DROP *)",
      "Bash(TRUNCATE *)",
      "Bash(curl * | bash)",
      "Bash(wget * | sh)"
    ],
    "ask": [
      "Write(**)",
      "Edit(**)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(git add*)",
      "Bash(npm install*)",
      "Bash(*deploy*)"
    ]
  }
}

Padrão 3: Ambiente de Produção (somente leitura)

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(git show*)",
      "Bash(cat *)",
      "Bash(ls *)",
      "Bash(ps *)",
      "Bash(df *)",
      "Bash(top *)"
    ],
    "deny": [
      "Write(**)",
      "Edit(**)",
      "Bash(git push*)",
      "Bash(git commit*)",
      "Bash(git reset*)",
      "Bash(rm *)",
      "Bash(mv *)",
      "Bash(*deploy*)",
      "Bash(*restart*)",
      "Bash(*kill *)"
    ],
    "ask": []
  }
}

Em worktrees ou repositórios próximos de produção, coloque esta configuração como .claude/settings.json ativo e inicie com claude --permission-mode plan ou um dontAsk pré-aprovado. Isso segue melhor o modelo oficial de scopes e permission modes do que trocar um arquivo alternativo por variável de ambiente.

Padrão 4: Apenas Geração de Conteúdo (o padrão usado neste site)

{
  "permissions": {
    "allow": [
      "Read(**)",
      "Glob(**)",
      "Grep(**)",
      "Write(site/src/content/**)",
      "Write(content/**)",
      "Edit(site/src/content/**)",
      "Edit(content/**)",
      "Bash(git log*)",
      "Bash(git diff*)",
      "Bash(git status*)",
      "Bash(node scripts/*)",
      "Bash(QIITA_TOKEN=* node scripts/qiita-publish.mjs)"
    ],
    "deny": [
      "Bash(rm -rf*)",
      "Bash(git push --force*)",
      "Edit(.env*)",
      "Read(.env*)"
    ],
    "ask": [
      "Bash(git add*)",
      "Bash(git commit*)",
      "Bash(git push*)",
      "Bash(bash scripts/deploy.sh*)"
    ]
  }
}

A chave é restringir as escritas a um diretório específico, como com Write(site/src/content/**).

Hooks: Executar Processos Antes e Depois das Permissões

Hooks são um mecanismo que executa comandos automaticamente antes e depois da execução de ferramentas. Podem ser usados para verificações de segurança e formatação automática.

PreToolUse: Hook Antes da Execução

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(git add*)",
        "hooks": [{
          "type": "command",
          "command": "git diff --cached --name-only | grep -E '^\\.env' && echo '🚨 Adição de .env detectada!' && exit 1 || exit 0"
        }]
      },
      {
        "matcher": "Bash(git commit*)",
        "hooks": [{
          "type": "command",
          "command": "node scripts/secret-scan.mjs"
        }]
      },
      {
        "matcher": "Bash(rm*)",
        "hooks": [{
          "type": "command",
          "command": "echo '⚠️ Comando de exclusão detectado. Executando em 5 segundos. Ctrl+C para cancelar.' && sleep 5"
        }]
      }
    ]
  }
}

Se um comando hook retornar código de saída 1, a execução da ferramenta é bloqueada. Este é o ponto mais importante.

PostToolUse: Hook Após a Execução

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{
          "type": "command",
          "command": "npx tsc --noEmit 2>&1 | head -20 || true"
        }]
      },
      {
        "matcher": "Bash(git commit*)",
        "hooks": [{
          "type": "command",
          "command": "git log --oneline -3"
        }]
      }
    ]
  }
}

PostToolUse é usado para verificações pós-execução e efeitos colaterais — por exemplo, executar automaticamente verificações de tipo após editar arquivos ou exibir as 3 entradas de log mais recentes após um commit.

Coleção de Receitas Práticas de Hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash(npm install*)",
        "hooks": [{
          "type": "command",
          "command": "echo '📦 Adicionando pacote. Por favor, verifique o package.json.'"
        }]
      },
      {
        "matcher": "Bash(*deploy*)",
        "hooks": [{
          "type": "command",
          "command": "read -p '🚀 Prestes a fazer deploy. Continuar? [y/N] ' ans && [ \"$ans\" = 'y' ] || exit 1"
        }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Write(*.ts)|Edit(*.ts)",
        "hooks": [{
          "type": "command",
          "command": "npx eslint --fix $CLAUDE_TOOL_INPUT_FILE_PATH 2>/dev/null || true"
        }]
      }
    ]
  }
}

Modos de Permissão: Nível de Permissão na Inicialização

Você também pode especificar o modo ao iniciar o comando claude.

# Modo normal (segue settings.json)
claude

# Aprovar automaticamente todas as operações (perigoso! apenas para ambientes confiáveis)
claude --dangerously-skip-permissions

# Pular apenas operações específicas
claude --allowedTools "Read,Grep,Glob"

# Modo não-interativo (usado em CI/CD)
claude -p "Execute os testes e relate os resultados" --dangerously-skip-permissions

--dangerously-skip-permissions deve ser usado apenas para automação CI/CD ou scripts de automação completamente compreendidos, e evitado no uso interativo diário.

2026: Permission budget seguro e revisão em equipe

Aqui, permission budget não é nome oficial de recurso. É o limite operacional do que você permite que o Claude Code execute automaticamente na primeira semana. Em 1 de junho de 2026, a documentação oficial descreve permission rules avaliadas na ordem deny -> ask -> allow. Hooks PreToolUse adicionam verificações em tempo de execução, mas não substituem um deny ou ask já correspondente. Portanto, o primeiro budget deve priorizar reversibilidade, não velocidade.

Um budget inicial seguro é pequeno. Em allow, deixe apenas leitura e verificação: Read, Glob, Grep, git status, git diff, git log, npm run lint e npm run test. Em ask, coloque operações que mudam intenção: Edit, Write, git add, git commit, git push, npm install e deploy. Em deny, coloque o irreversível ou sensível: .env, secrets/**, rm -rf, git reset --hard, git push --force, curl | bash, wget | sh e comandos de banco de produção. bypassPermissions só deve existir em contêineres, VMs ou devcontainers descartáveis.

Em equipe, revise .claude/settings.json como código de aplicação. Cada PR deve responder a três perguntas: todo allow é seguro se rodar repetidas vezes, cada ask é um ponto real de confirmação humana, e deny cobre secrets, force push, exclusões e produção? Em organizações gerenciadas, administradores podem usar server-managed settings para definir disableBypassPermissionsMode e disableAutoMode como "disable", e allowManagedPermissionRulesOnly para bloquear regras locais ou de projeto.

Um erro perigoso é liberar Bash(git *) ou Bash(node *) de forma ampla e presumir que Read(.env*) protege secrets. A documentação oficial explica que deny de Read e Edit se aplica às ferramentas de arquivo do Claude Code e comandos reconhecidos, mas não impede subprocessos arbitrários, como scripts Node ou Python, de abrir arquivos diretamente. Para proteger secrets, evite Bash amplo e combine regras com sandbox, permissões do sistema operacional e checks PreToolUse.

Defina a recuperação antes do incidente. Se aparecer uma edição indesejada, abra /permissions para ver a regra ativa e a origem, revise git diff e reverta com git restore -p para manter hunks bons. Para arquivos não rastreados, rode git clean -n antes de apagar. Se um secret pode ter sido lido ou entrado no transcript, corrigir .claude/settings.json não basta: rotacione o token.

Para transformar este artigo em política de repositório, comece com permission budget loop e permission audit checklist. Para templates e material de estudo pronto, compare os produtos Claude Code. Para rollout em equipe, revisão de permissões e onboarding seguro, a consultoria é melhor do que adivinhar regras sozinho.

Prioridade e Substituição de Arquivos de Configuração

Quando existem vários arquivos de configuração:

~/.claude/settings.json     ← User (compartilhado entre projetos)
.claude/settings.json       ← Project (gerenciado pelo git)
.claude/settings.local.json ← Local (pessoal, em gitignore)
managed-settings.json       ← Managed (política da organização, maior prioridade)

Permission rules são mescladas, e deny sempre é avaliado antes de allow

Escreva configurações adicionais pessoais em .claude/settings.local.json e adicione ao gitignore. Para evitar que as listas deny da equipe sejam substituídas por configurações pessoais, o design seguro é escrever regras deny apenas no settings.json.

# Adicionar ao .gitignore
.claude/settings.local.json

As 5 Armadilhas Mais Comuns

1. Errar os padrões de wildcard

// ❌ Isso só corresponde ao comando único "git"
"Bash(git)"

// ✅ Também corresponde a git seguido de argumentos
"Bash(git *)"
"Bash(git*)"  // Também funciona sem espaço, mas * explícito é mais seguro

2. Esquecer que deny tem prioridade sobre ask

// Com esta configuração, Bash(rm -rf /tmp/test) é capturado por deny e bloqueado
// Nunca chega a ask
{
  "deny": ["Bash(rm -rf*)"],
  "ask": ["Bash(rm*)"]  // ← rm -rf é tratado por deny
}

3. Não prestar atenção aos códigos de saída dos hooks

# Se o comando do hook PreToolUse sempre retornar exit 0,
# falhas de varredura não bloquearão a execução

# ❌ Passa mesmo em caso de erro
"command": "node scan.mjs"

# ✅ Controlar explicitamente o código de saída
"command": "node scan.mjs || exit 1"

4. Adicionar acidentalmente settings.json ao .gitignore

Algumas equipes adicionam acidentalmente settings.json—que querem compartilhar—ao .gitignore. A abordagem correta é configuração do projeto sob git, apenas settings.local.json no gitignore.

5. Esquecer de trocar manualmente a configuração de produção

# ❌ Trabalhando em produção com as configurações do dia a dia

# ✅ Iniciar em plan mode e manter o .claude/settings.json do worktree seguro para produção
claude --permission-mode plan

Registrar um alias torna mais difícil de esquecer:

# ~/.bashrc or ~/.zshrc
alias claude-prod='claude --permission-mode plan'

Depurando a Configuração

Quando não está claro “por que este comando está sendo bloqueado”:

# Verificar as configurações atuais
claude --print-settings 2>/dev/null || cat .claude/settings.json

# Verificar qual regra está correspondendo (modo verbose)
claude --verbose -p "Execute git push"

Resumo: Melhores Práticas para Design de Permissões

1. Começar com deny
   → Listar comandos que nunca devem ser executados
   → rm -rf, git push --force, DROP TABLE são essenciais

2. Depois configurar ask
   → Operações de escrita e deploy que precisam de confirmação

3. Allow para todo o resto
   → Operações de leitura e CI: tudo em allow para eficiência

4. Automatizar segurança com Hooks
   → Varredura pré-commit, verificação de tipos automática após edições

5. Preparar arquivos de configuração específicos por ambiente
   → settings.json (desenvolvimento), settings.production.json (produção)

Com configurações de permissão adequadas, você parará de pressionar mecanicamente botões de aprovação e poderá se concentrar apenas nas operações que realmente precisam de revisão. Dedicar 30 minutos ao design inicial tornará centenas de horas futuras de trabalho mais seguras.