Configurar permissões

Controle o que Claude Code pode acessar e fazer com regras de permissão refinadas, modos e políticas gerenciadas.

Claude Code suporta permissões refinadas para que você possa especificar exatamente o que o agente pode fazer e o que não pode. Você pode verificar as configurações de permissão no controle de versão para compartilhá-las com todos os desenvolvedores da sua organização, e cada desenvolvedor pode personalizar as suas próprias.

Sistema de permissões

Claude Code usa um sistema de permissões em camadas para equilibrar poder e segurança. A tabela mostra, para cada tipo de ferramenta, se o modo Manual pede aprovação antes da ação ser executada. Os outros modos de permissão alteram quais desses pedem sua aprovação; no modo automático um classificador revisa as ações em vez de você, e como o classificador avalia ações lista quais ele vê.

Quando você escolhe "Sim, não pergunte novamente" e a aprovação é salva permanentemente, como para um comando Bash ou um domínio WebFetch, Claude Code salva a regra em .claude/settings.local.json na raiz do repositório git, resolvida através de worktrees para o checkout principal. A regra se aplica a futuras sessões em qualquer lugar desse repositório, incluindo sessões iniciadas em subdiretórios e em worktrees. Uma aprovação de modificação de arquivo não é salva no arquivo: como a tabela mostra, ela dura até o final da sessão. Em alguns casos, como fora de um repositório git ou no Windows, Claude Code não usa a raiz do repositório; Onde Claude Code procura por cada arquivo lista esses casos e onde ele salva a regra em vez disso.

Antes da v2.1.211, Claude Code sempre salvava a regra no diretório inicial, então uma aprovação concedida em uma worktree ou subdiretório não se aplicava ao resto do repositório. Regras que versões anteriores salvaram em um subdiretório ou worktree ainda se aplicam a sessões iniciadas lá.

Às vezes um prompt de permissão oferece apenas uma aprovação única, sem opção de "não pergunte novamente" e sem opção de permitir a ação pelo resto da sessão. Claude Code oferece essas opções apenas quando o prompt pode mostrar a você tudo o que elas permitiriam, então uma regra que você salva de um prompt cobre apenas o que sua opção nomeada.

Quando o diretório em que você iniciou Claude Code é o que torna o rótulo da opção muito longo, Claude Code o encurta no rótulo, substituindo seu diretório inicial por ~ e depois o final do caminho por …, e mantém a opção. Você ainda salva a mesma regra. Claude Code deixa as opções de fora em três casos:

• Comando ou edição: muito grande para mostrar na íntegra.
• Comandos ou caminhos que a regra cobriria: o rótulo não pode caber em todos eles.
• Diretório inicial muito longo, não encurtado: contém caracteres que Claude Code não pode exibir com segurança, ou mesmo seu início não cabe.

Aprove a ação uma vez, ou adicione a regra você mesmo em /permissions.

Adicione um comentário quando você responder a um prompt de permissão

Você pode anexar uma nota a Claude quando aprova ou nega uma ação única. Na maioria dos prompts de permissão, incluindo Bash, PowerShell, arquivo e prompts de ferramenta MCP, mova para Sim ou Não e pressione Tab para abrir um campo de comentário nessa opção. Prompts de WebFetch e navegador não oferecem o campo. As opções que permitem a ação pelo resto da sessão ou salvam uma regra também não aceitam uma.

Com o campo aberto, digite o comentário e depois pressione uma dessas teclas:

• Enter: envia sua resposta com o comentário anexado. Se você deixar o campo vazio, Claude Code envia a resposta sem um comentário.
• Tab: fecha o campo sem responder. Claude Code mantém o texto que você digitou e ainda o envia se você responder com essa opção.
• Shift+Tab: em um prompt de arquivo, como um prompt Edit ou Write, fecha o campo da mesma forma que Tab. Antes da v2.1.235, pressionar Shift+Tab dentro do campo em vez disso selecionava a opção que permite a ação pelo resto da sessão, então Claude Code aprovava a ação pelo resto da sessão e descartava o comentário.

Claude Code entrega o comentário de forma diferente dependendo de como você respondeu:

• Sim: Claude Code executa a ação, depois envia seu comentário a Claude após o resultado.
• Não: Claude Code envia seu comentário a Claude como o motivo da negação, e Claude continua trabalhando. Se você selecionar Não sem um comentário em um prompt da conversa principal, Claude Code interrompe a rodada.

Gerenciar permissões

Você pode visualizar e gerenciar as permissões de ferramentas do Claude Code com /permissions. Esta interface lista todas as regras de permissão e o arquivo settings.json do qual cada regra é originária. Você pode abrir a interface enquanto Claude está trabalhando: quando você adiciona ou remove uma regra, Claude Code aplica a alteração começando com a próxima chamada de ferramenta do Claude no mesmo turno. Antes da v2.1.234, Claude Code enfileirava o comando até que o turno terminasse.

• As regras Allow permitem que Claude Code use a ferramenta especificada sem aprovação manual.
• As regras Ask solicitam confirmação sempre que Claude Code tenta usar a ferramenta especificada.
• As regras Deny impedem que Claude Code use a ferramenta especificada.

As regras são avaliadas em ordem: deny, depois ask, depois allow. A primeira correspondência nessa ordem determina o resultado, e a especificidade da regra não altera a ordem.

Uma regra deny ampla como Bash(aws *) bloqueia cada chamada correspondente, incluindo chamadas que também correspondem a uma regra allow mais estreita como Bash(aws s3 ls), portanto uma regra deny não pode carregar exceções de lista de permissões. A mesma precedência se aplica entre ask e allow: uma regra ask correspondente solicita confirmação mesmo quando uma regra allow mais específica também corresponde à mesma chamada.

As regras deny se comportam de forma diferente dependendo se nomeiam uma ferramenta ou definem o escopo de um padrão dentro de uma. Um nome de ferramenta simples como Bash remove a ferramenta do contexto do Claude completamente, então Claude nunca a vê. A remoção com nome simples se aplica a todas as ferramentas exceto EndConversation: uma regra deny não pode removê-la enquanto qualquer outra ferramenta permanecer, e uma regra ask nunca solicita confirmação para ela. Uma regra com escopo como Bash(rm *) deixa a ferramenta disponível e bloqueia chamadas correspondentes quando Claude tenta usá-las.

Quando o modo automático está disponível para sua sessão, a interface também inclui as regras do classificador de modo automático. Selecione a aba Auto mode para visualizá-las.

Modos de permissão

Claude Code suporta vários modos de permissão que controlam como ele aprova chamadas de ferramentas. Veja Modos de permissão para quando usar cada um. Para alterar o modo em que as sessões começam, defina defaultMode em seus arquivos de configuração. Qual modo uma sessão começa cobre o padrão integrado para cada plano e o que a extensão VS Code lê.

Para evitar que o modo bypassPermissions ou auto seja usado, defina permissions.disableBypassPermissionsMode ou permissions.disableAutoMode como "disable" em qualquer arquivo de configuração. Estes são mais úteis em configurações gerenciadas onde não podem ser substituídos.

Sintaxe de regra de permissão

As regras de permissão seguem o formato Tool ou Tool(specifier). Parênteses dentro do especificador são literais, portanto um comando ou caminho que os contém não precisa de escape.

Corresponder todos os usos de uma ferramenta

Para corresponder todos os usos de uma ferramenta, use apenas o nome da ferramenta sem parênteses:

Bash(*) é equivalente a Bash e corresponde a todos os comandos Bash. Como uma regra de negação, ambas as formas removem a ferramenta do contexto do Claude.

Use especificadores para controle refinado

Adicione um especificador entre parênteses para corresponder a usos específicos de ferramentas:

Corresponder por parâmetro de entrada

As regras de negação e pergunta podem corresponder a um parâmetro de entrada de nível superior em qualquer ferramenta integrada com Tool(param:value).

Para corresponder a um parâmetro em uma ferramenta MCP, passe uma regra de negação com --disallowedTools. Quando Claude Code carrega um arquivo de configurações, ele ignora qualquer regra mcp__ que tenha parênteses. Claude Code lista a regra ignorada no diálogo de configurações inválidas quando uma sessão interativa é iniciada, e na saída de claude doctor.

Uma regra de parâmetro corresponde quando Claude chama a ferramenta com esse parâmetro definido para esse valor exato. Uma regra de permissão para um valor de parâmetro não estabeleceria que a chamada é segura em geral, portanto as regras de permissão continuam a usar a sintaxe de especificador própria de cada ferramenta. Isso funciona para qualquer parâmetro escalar que a ferramenta aceita:

A correspondência de parâmetros segue estas regras:

• O nome do parâmetro deve ser um campo direto da entrada da ferramenta, como model na ferramenta Agent. Campos aninhados dentro de um objeto ou array não são correspondíveis
• Cada regra nomeia um parâmetro. Para controlar tanto model quanto isolation, escreva duas regras, Agent(model:opus) e Agent(isolation:worktree), em vez de combiná-las em uma regra
• O valor suporta * como um caractere curinga que corresponde a qualquer sequência de caracteres, portanto Agent(isolation:*) corresponde a qualquer valor de isolamento explícito. Sem * a correspondência é exata
• Um parâmetro que o modelo omite nunca é correspondido, portanto Agent(model:*) não corresponde a uma chamada que deixa model não definido
• O valor é comparado com a entrada literal que Claude envia, antes de qualquer normalização. Agent(model:opus) corresponde ao alias opus mas não a um ID de modelo completo. Execute com --verbose para ver os nomes e valores exatos dos parâmetros em cada chamada de ferramenta
• O espaço em branco ao redor do dois-pontos é ignorado

Você não pode corresponder a um campo de conteúdo primário de uma ferramenta desta forma: command para Bash e PowerShell, file_path para Read, Edit e Write, path para Grep e Glob, notebook_path para NotebookEdit, e url para WebFetch. Uma regra como Bash(command:rm *) seria contornável por um comando composto, portanto Claude Code a ignora e emite um aviso de inicialização. Use Bash(rm *), Read(./path) ou WebFetch(domain:host) em vez disso.

Padrões com caracteres curinga

Um * em uma regra Bash corresponde a qualquer texto, incluindo espaços, portanto uma regra cobre uma família de comandos. Uma regra sem * corresponde a um comando exato.

Escreva o comando que você quer que Claude execute sem perguntar, e substitua as partes que variam com *. Com esta configuração, Claude Code executa scripts npm e commits git sem perguntar e recusa comandos que começam com git push. Um push escrito de outra forma, como git -C . push, não é correspondido; veja o que uma regra Bash não corresponde.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Um * pode ir em qualquer lugar na regra: no início, no meio ou no final. Cada linha mostra uma regra, comandos que ela corresponde e comandos próximos que ela não corresponde:

Três regras de correspondência produzem essas linhas:

• O * representa qualquer texto em seu lugar. Em Bash(git * main), ele representa o subcomando, portanto Claude Code corresponde a todos os subcomandos git e todas as opções antes dele. Isso inclui -c, que faz git executar um programa que você nomeia. Em Bash(* --version), o * representa o programa, portanto qualquer programa corresponde.
• Um * no final, com um espaço antes dele, também corresponde ao comando simples. Bash(ls *) corresponde a ls, e Bash(git log *) corresponde a git log. Isso vale apenas quando o * à direita é o único caractere curinga da regra: Bash(* --help *) corresponde a npm --help x mas não a npm --help.
• O espaço antes de um * à direita faz parte da regra. Bash(ls *) requer um espaço após ls, portanto lsof não corresponde. Bash(ls*) não tem espaço, portanto também corresponde a lsof.

O sufixo :* é uma maneira equivalente de escrever um caractere curinga à direita, portanto Bash(ls:*) corresponde aos mesmos comandos que Bash(ls *).

O diálogo de permissão escreve a forma separada por espaço quando você seleciona "Sim, não pergunte novamente" para um prefixo de comando. A forma :* é reconhecida apenas no final de um padrão. Em um padrão como Bash(git:* push), o dois-pontos é tratado como um caractere literal e não corresponderá a comandos git.

Caracteres curinga no nome da ferramenta

As regras de negação e pergunta também aceitam padrões glob na posição do nome da ferramenta. O padrão deve corresponder ao nome completo da ferramenta: "*" corresponde a todas as ferramentas, e "mcp__*" corresponde a todas as ferramentas MCP em todos os servidores. Uma ferramenta correspondida por uma regra de negação glob com nome simples é removida do contexto do Claude, o mesmo que um nome de ferramenta simples, incluindo a exceção EndConversation: uma negação glob não pode removê-la enquanto qualquer outra ferramenta permanecer, e uma pergunta glob nunca a solicita. Esta configuração nega todas as ferramentas MCP:

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

As regras de permissão aceitam globs de nome de ferramenta apenas após um prefixo literal mcp__<server>__. O segmento do servidor deve estar livre de glob para que a regra nomeie um servidor específico que você configurou. mcp__puppeteer__* corresponde a todas as ferramentas do servidor puppeteer, e mcp__github__get_* corresponde às suas ferramentas get_. Um glob de permissão desancorado como "*", "B*" ou "mcp__*" é ignorado com um aviso e não aprova automaticamente nada.

Uma regra de negação ou pergunta cujo nome de ferramenta não corresponde a nenhuma ferramenta conhecida produz um aviso de inicialização para detectar erros de digitação. Nomes de ferramentas contendo _ ou * estão isentos da verificação.

O rótulo mostrado para uma ferramenta na transcrição e diálogo de permissão pode diferir do seu nome canônico. Por exemplo, a ferramenta rotulada Stop Task na transcrição tem o nome canônico TaskStop. As regras de permissão e correspondências de hook não correspondem ao rótulo, portanto uma regra escrita como Stop Task não corresponde. Para regras de negação e pergunta, o aviso de inicialização acima detecta a incompatibilidade. Use os nomes canônicos listados na referência de ferramentas.

Regras de permissão específicas da ferramenta

Bash

As regras Bash correspondem ao texto do comando inteiro, com * representando qualquer texto. Padrões com caracteres curinga mostra quais comandos cada forma de regra corresponde e onde colocar o *. O resto desta seção cobre como Claude Code corresponde a comandos compostos e wrappers, o que uma regra não corresponde, comandos somente leitura e redirecionamentos.

Comandos compostos

As regras deny e ask se aplicam quando qualquer subcomando as corresponde, incluindo um comando aninhado dentro de um subshell, uma substituição de comando ou um corpo de fluxo de controle como um loop for. Uma regra ask como Bash(git clean *) ainda solicita para cd /tmp && git clean -f ou echo "$(git clean -f)", mesmo em modo auto.

Quando && ou || não tem nada depois, como em npm test &&, Claude Code trata o comando como não analisável e não o divide em subcomandos para correspondência de regra allow, portanto uma regra como Bash(npm *) não o aprova.

Quando você aprova um comando composto com "Sim, não pergunte novamente", Claude Code salva uma regra separada para cada subcomando que requer aprovação, em vez de uma única regra para a string completa. Por exemplo, aprovar git status && npm test salva uma regra para npm test, portanto futuras invocações de npm test são reconhecidas independentemente do que precede o &&. Subcomandos como cd em um subdiretório geram sua própria regra Read para esse caminho. Até 5 regras podem ser salvas para um único comando composto.

Wrappers

Antes de corresponder regras Bash, Claude Code remove um conjunto fixo de wrappers, portanto uma regra como Bash(npm test *) também corresponde a timeout 30 npm test. Os wrappers removidos são timeout, time, nice, nohup e stdbuf, mais os shell builtins command e builtin, e noglob do zsh. Cada um executa seu argumento como o comando real. Duas formas relacionadas não são removidas: a forma de consulta command -v, que procura um comando em vez de executá-lo, e nocorrect do zsh.

Claude Code também remove uma atribuição inicial de certas variáveis de ambiente conhecidas como seguras, portanto Bash(npm test *) corresponde a NODE_ENV=test npm test. Uma regra allow não corresponderá além de uma atribuição de qualquer outra variável. Uma regra deny ou ask corresponde além de qualquer atribuição inicial, portanto Bash(rm *) em deny ainda corresponde a FOO=bar rm -rf tmp/.

xargs simples também é removido, portanto Bash(grep *) corresponde a xargs grep pattern. A remoção se aplica apenas quando xargs não tem flags: uma invocação como xargs -n1 grep pattern é correspondida como um comando xargs, portanto regras escritas para o comando interno não a cobrem.

Esta lista de wrapper é integrada e não é configurável. Executores de ambiente de desenvolvimento como direnv exec, devbox run, mise exec, npx e docker exec não estão na lista. Porque essas ferramentas executam seus argumentos como um comando, uma regra como Bash(devbox run *) corresponde a tudo que vem após run, incluindo devbox run rm -rf .. Para aprovar trabalho dentro de um executor de ambiente, escreva uma regra específica que inclua tanto o executor quanto o comando interno, como Bash(devbox run npm test). Adicione uma regra por comando interno que você quer permitir.

Wrappers exec como watch, setsid, ionice e flock não podem ser auto-aprovados por uma regra de prefixo como Bash(watch *), portanto em modo Manual sempre solicitam. O mesmo se aplica a find com -exec ou -delete: uma regra Bash(find *) não cobre essas formas. Para aprovar uma invocação específica, escreva uma regra de correspondência exata para a string de comando completa.

O que uma regra Bash não corresponde

Uma regra Bash corresponde ao texto do comando que Claude escreve, após Claude Code dividir comandos compostos e remover wrappers. Ela não corresponde ao mesmo programa invocado de uma forma diferente, portanto uma regra deny ou ask cobre a invocação que Claude geralmente produz e não é um limite de segurança ao redor do programa. Estas regras em deny ou ask param a primeira forma e não as outras:

Suas outras regras e o modo de permissão decidem os comandos na última coluna.

Para imposição de sistema de arquivos e rede que não depende do texto do comando, use sandboxing. Para inspecionar o texto do comando completo com sua própria lógica antes de ser executado, use um hook PreToolUse.

Comandos somente leitura

Claude Code reconhece um conjunto integrado de comandos Bash como somente leitura e os executa sem um prompt de permissão em cada modo, exceto por um caminho que permissions.blockReadsOutsideWorkingDirectories protege. O conjunto inclui ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd e formas somente leitura de git. O conjunto não é configurável; para exigir um prompt para um desses comandos, adicione uma regra ask ou deny para ele.

Um redirecionamento como ls > out.txt adiciona uma verificação no alvo. Veja Redirecionamentos.

Padrões glob sem aspas são permitidos para comandos cujas todas as flags são somente leitura, portanto ls *.ts e wc -l src/*.py são executados sem um prompt.

Em modo Manual, comandos deste conjunto ainda solicitam nestes casos:

• Globs sem aspas para comandos com flags capazes de escrita: comandos com flags capazes de escrita ou execução, como find, sort, sed e git, solicitam quando um glob sem aspas está presente, porque o glob poderia expandir para uma flag como -delete.
• docker apontado para outro daemon: formas somente leitura de docker solicitam quando o comando carrega uma flag que seleciona um daemon diferente, como -H, --context ou --url e --connection do Podman.
• file com flags de abertura de caminho: file solicita quando passa -m/--magic-file ou -f/--files-from, porque essas flags fazem file abrir os caminhos nomeados no valor da flag.
• Caminhos de rede no Windows: um comando cujos argumentos incluem um caminho de rede (UNC), como \\server\share\file, solicita porque acessar um caminho de rede pode enviar suas credenciais do Windows para o host que ele nomeia. A mesma verificação se aplica a comandos da ferramenta PowerShell.
• Comandos que a análise não consegue analisar: quando Claude Code não consegue analisar completamente um comando, solicita aprovação em vez de tratar o comando como somente leitura. Comandos mais longos que 10.000 caracteres sempre solicitam porque excedem o que a análise analisa.

Um cd em um caminho dentro do seu diretório de trabalho ou um diretório adicional também é somente leitura, e um comando composto como cd packages/api && ls é executado sem um prompt quando cada parte se qualifica por conta própria. Estas combinações solicitam mesmo quando cada parte é somente leitura:

• cd com git: solicita quando o cd muda para um diretório diferente, já que executar git em um novo diretório pode executar os hooks desse diretório. Um cd cujo alvo se resolve para o diretório de trabalho atual é uma no-op e não dispara o prompt.
• cd com um redirecionamento: solicita quando Claude Code não consegue determinar para qual diretório o alvo de redirecionamento se resolve após o cd ser executado. Um comando cujo único alvo de redirecionamento é /dev/null, como cd app; grep -r pattern . 2>/dev/null, não solicita, porque /dev/null não depende do diretório de trabalho.

Redirecionamentos

Quando um comando redireciona saída ou entrada, Claude Code verifica o alvo de redirecionamento contra suas regras de arquivo como se Claude tivesse escrito ou lido esse arquivo diretamente:

• Redirecionamentos de saída: para > file, >> file ou 2> file, a verificação cobre suas regras allow e deny Edit, caminhos protegidos e os diretórios de trabalho. Uma regra como Bash(git commit *) permite o comando, não o alvo. Um alvo que começa com ~ ou contém um caractere curinga precisa de sua aprovação.
• Redirecionamentos de entrada: para < file, a verificação cobre suas regras allow e deny Read e os diretórios de trabalho. Um alvo fora dos diretórios de trabalho precisa de sua aprovação a menos que uma regra allow o cubra. Um alvo que contém um padrão glob ou um caminho relativo que segue um cd no mesmo comando precisa de sua aprovação mesmo quando uma regra allow o cobre. Claude Code verifica alvos de entrada em v2.1.257 e posterior.

Alvos sem arquivo atrás deles não são verificados: /dev/null, formas de descritor de arquivo como 2>&1 e <&3, e here-docs e here-strings.

PowerShell

As regras de permissão PowerShell usam a mesma forma que as regras Bash. Caracteres curinga com * correspondem em qualquer posição, o sufixo :* é equivalente a um * final, e um PowerShell simples ou PowerShell(*) corresponde a cada comando. Esta configuração permite comandos Get-ChildItem e git commit enquanto bloqueia Remove-Item:

{
  "permissions": {
    "allow": [
      "PowerShell(Get-ChildItem *)",
      "PowerShell(git commit *)"
    ],
    "deny": [
      "PowerShell(Remove-Item *)"
    ]
  }
}

Aliases comuns são canonicalizados antes da correspondência. Uma regra escrita para o nome do cmdlet também corresponde a seus aliases, portanto PowerShell(Get-ChildItem *) corresponde a gci, ls e dir também. A correspondência é insensível a maiúsculas e minúsculas.

Claude Code analisa o AST do PowerShell e verifica cada comando em um comando composto independentemente. Os operadores de pipeline |, separadores de instrução ; e nos operadores de cadeia PowerShell 7+ && e || dividem um comando composto em subcomandos. Uma regra deve corresponder a cada subcomando para que o comando composto seja permitido.

Read e Edit

Para bloquear as ferramentas de arquivo do Claude de ler um arquivo ou diretório, adicione uma regra deny Read para seu caminho, como Read(./.env) ou Read(./secrets/**). Excluir arquivos sensíveis tem um exemplo pronto para colar.

As regras Edit se aplicam a todas as ferramentas integradas que editam arquivos. Claude faz uma tentativa de melhor esforço para aplicar regras Read a todas as ferramentas integradas que leem arquivos como Grep e Glob, a menções @file em seus prompts, e à seleção e contexto de arquivo aberto que um IDE conectado compartilha com Claude.

Uma regra deny Read também bloqueia as ferramentas Edit e Write no mesmo caminho, incluindo criar um novo arquivo lá. NotebookEdit não é coberto, portanto adicione uma regra deny Edit para caminhos que nenhuma ferramenta pode alterar. A verificação requer Claude Code v2.1.208 ou posterior em edições, e v2.1.228 ou posterior em escritas.

Claude Code verifica permissões de arquivo apenas contra regras Edit(path) e Read(path). Se você escrever uma regra de caminho para Write, NotebookEdit, Glob ou a ferramenta legada MultiEdit em vez disso, Claude Code aceita a regra mas nunca a consulta, e avisa na inicialização, exceto por uma regra Glob passada em --allowedTools. Use Edit(docs/**) no lugar de Write(docs/**), NotebookEdit(docs/**) ou MultiEdit(docs/**), e Read(docs/**) no lugar de Glob(docs/**). Claude Code não avisa sobre uma regra de nome de ferramenta sem caminho, como uma regra deny para Write; ela corresponde a essa regra no nível de ferramenta em todos os lugares. Requer Claude Code v2.1.210 ou posterior.

As regras Read e Edit usam sintaxe de padrão gitignore com quatro tipos de padrão distintos; para padrões de diretório de segmento único, a profundidade de correspondência também depende do tipo de regra, descrito mais adiante nesta seção:

Um padrão /path ancora em um diretório associado à fonte de configurações que o define, portanto a mesma regra corresponde a locais diferentes dependendo de onde você a coloca:

Uma regra que você adiciona através de /permissions segue a linha para o arquivo de configurações que você a salva.

As regras de configurações locais ancoram no diretório de trabalho primário da sessão, não na raiz do repositório onde Claude Code armazena o arquivo em v2.1.211 e posterior. Em uma sessão iniciada na raiz do repositório, os dois diretórios são os mesmos; em uma sessão de worktree, uma regra compartilhada como Edit(/src/**) corresponde ao diretório src/ próprio dessa worktree.

Uma regra deny como Read(/secrets/**) em configurações de usuário bloqueia ~/.claude/secrets/**, não um diretório secrets em seu projeto. Para escrever uma regra em configurações de usuário que se aplique dentro de cada projeto, use um caminho absoluto // ou um caminho relativo à home ~/ em vez disso.

No Windows, os caminhos são normalizados para forma POSIX antes da correspondência. C:\Users\alice se torna /c/Users/alice, portanto use //c/**/.env para corresponder arquivos .env em qualquer lugar nessa unidade. Para corresponder em todas as unidades, use //**/.env.

Exemplos:

• Edit(/docs/**): edita em <diretório de trabalho primário>/docs/, não /docs/ ou <diretório de trabalho primário>/.claude/docs/
• Read(~/.zshrc): lê o .zshrc do seu diretório home
• Edit(//tmp/scratch.txt): edita o caminho absoluto /tmp/scratch.txt
• Read(src/**): como uma regra allow, lê de <diretório-atual>/src/ apenas; como uma regra deny ou ask, corresponde a um diretório src em qualquer profundidade sob o diretório atual

Uma regra só corresponde a arquivos sob sua âncora; dentro desse limite, a profundidade de correspondência depende da forma do padrão e, para padrões de diretório de segmento único, do tipo de regra, descrito abaixo. Nomes de arquivo simples seguem semântica gitignore e correspondem em qualquer profundidade, portanto Read(.env) e Read(**/.env) são equivalentes:

Um padrão relativo com um segmento de diretório único, como src/**, corresponde em profundidades diferentes dependendo do tipo de regra:

• Regras allow: Edit(src/**) corresponde apenas a <cwd>/src e aos arquivos sob ele. Para permitir um nome de diretório em qualquer profundidade, escreva Edit(**/src/**).
• Regras deny e ask: Read(secrets/**) corresponde a um diretório nomeado secrets em qualquer profundidade sob o diretório atual, portanto a regra também se aplica a cópias aninhadas.

Toda outra forma de padrão corresponde na mesma profundidade em cada tipo de regra: Edit(/src/**) e Edit(src/components/**) correspondem apenas em sua localização ancorada, enquanto Edit(**/src/**) corresponde em qualquer profundidade.

O exemplo a seguir mostra cada forma de padrão contra um projeto com um diretório src/ de nível superior e uma cópia aninhada sob vendor/:

<diretório-atual>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js

Quando você aprova um caminho de arquivo com "Sim, não pergunte novamente", Claude Code escapa caracteres de padrão gitignore nesse caminho, como [, ] e *, portanto a regra gerada corresponde apenas ao caminho literal que você aprovou. Regras que você escreve você mesmo não são escapadas. Antes de v2.1.202, Claude Code salvava o caminho não escapado, portanto uma regra gerada para um diretório nomeado [2024-06] Reports poderia falhar em corresponder seu próprio caminho ou corresponder diretórios irmãos não intencionais.

Você não precisa escapar parênteses em um caminho, portanto Edit(./Finance (2024)/**) corresponde à pasta Finance (2024) conforme escrito.

Uma regra deny ou ask cujo caminho não é utilizável como um padrão gitignore ainda protege esse caminho exato. Uma regra allow com um padrão não utilizável não aprova nada.

Quando Claude acessa um symlink, as regras de permissão verificam dois caminhos: o próprio symlink e o arquivo para o qual ele se resolve. As regras allow e deny tratam esse par de forma diferente: as regras allow voltam a solicitar, enquanto as regras deny bloqueiam imediatamente.

• Regras allow: se aplicam apenas quando tanto o caminho do symlink quanto seu alvo correspondem. Um symlink dentro de um diretório permitido que aponta para fora dele ainda solicita.
• Regras deny: se aplicam quando o caminho do symlink ou seu alvo correspondem. Um symlink que aponta para um arquivo negado é ele próprio negado.

Por exemplo, com Read(./project/**) permitido e Read(~/.ssh/**) negado, um symlink em ./project/key apontando para ~/.ssh/id_rsa é bloqueado: o alvo falha na regra allow e corresponde à regra deny.

Quando uma ferramenta abre um arquivo aprovado, Claude Code confirma que o caminho ainda se resolve para a localização que a verificação de permissão aprovou.

Grep e Glob pesquisam o diretório para o qual o argumento path se resolve. Claude Code aplica regras deny Read a esse diretório.

WebFetch

As regras WebFetch usam um prefixo domain: e correspondem ao hostname da URL solicitada. A correspondência é insensível a maiúsculas e minúsculas, suporta caracteres curinga * e remove um . final tanto da regra quanto do hostname para que example.com. e example.com sejam tratados da mesma forma.

• WebFetch(domain:example.com) corresponde a solicitações para example.com
• WebFetch(domain:*.example.com) corresponde a qualquer subdomínio em qualquer profundidade, como api.example.com ou a.b.example.com, mas não a example.com em si
• WebFetch(domain:*) corresponde a cada domínio. Não é o mesmo que uma regra WebFetch simples; veja Permitir ou negar cada fetch

Em qualquer posição que não seja um *. inicial ou um * simples, o caractere curinga corresponde apenas ao texto entre dois pontos. WebFetch(domain:example.*) corresponde a example.org, onde * se torna org, mas não a example.evil.com, onde * teria que se tornar evil.com e cruzar um ponto. Isso impede que um caractere curinga final corresponda a domínios que um atacante poderia registrar.

Caracteres curinga em regras WebFetch requerem Claude Code v2.1.172 ou posterior para corresponder fetches.

Permitir ou negar cada fetch

Uma regra WebFetch simples é o nome da ferramenta sem uma parte domain:, como "deny": ["WebFetch"]. Tanto ela quanto WebFetch(domain:*) cobrem cada URL, mas Claude Code as aplica de forma diferente, e apenas a forma domain: também adiciona seu domínio à lista de domínios permitidos ou negados do sandbox. Essa seção lista as formas com caracteres curinga que o sandbox honra e a versão que adicionou * simples.

Cada linha mostra o que uma regra faz na lista allow e na lista deny:

Para deixar Claude fazer fetch livremente enquanto mantém a lista de permissões do sandbox como está, use a forma simples. Este settings.json faz isso:

{
  "permissions": {
    "allow": ["WebFetch"]
  }
}

Quando você pede a Claude para fazer fetch de uma página, ele faz fetch sem um prompt. Quando você pede a ele para executar um curl em sandbox contra um host fora da lista de permissões do sandbox, Claude Code ainda solicita você para esse host, ou em modo auto envia a solicitação para o classificador, porque a regra simples não adicionou o host à lista de permissões.

MCP

As regras MCP usam o nome do servidor conforme configurado em Claude Code, opcionalmente seguido pelo nome de uma ferramenta desse servidor.

• mcp__puppeteer corresponde a qualquer ferramenta fornecida pelo servidor puppeteer
• mcp__puppeteer__* usa sintaxe com caracteres curinga e também corresponde a todas as ferramentas do servidor puppeteer
• mcp__puppeteer__puppeteer_navigate corresponde à ferramenta puppeteer_navigate fornecida pelo servidor puppeteer

Se sua organização definiu uma ferramenta conector claude.ai como ask e essa configuração chega a Claude Code em sua sessão, as regras allow para essa ferramenta não entram em vigor: Claude Code solicita em cada chamada, mesmo em modos auto e bypassPermissions. No modo dontAsk, que nunca solicita, Claude Code nega a chamada em vez disso. As ferramentas de conector que Claude Code busca por si próprio aparecem como mcp__claude_ai_<server>__<tool>.

Em uma sessão de Cowork no aplicativo Claude Desktop, Claude executa comandos de shell através da ferramenta mcp__workspace__bash do Cowork em vez da ferramenta Bash integrada, e Cowork igualmente fornece mcp__workspace__web_fetch para web fetches. Claude Code também aplica regras deny que nomeiam a ferramenta inteira Bash ou WebFetch a essas ferramentas Cowork, portanto uma regra deny Bash gerenciada impede Claude de executar comandos de shell em Cowork. Quando Claude Code bloqueia tal chamada, a mensagem nomeia a ferramenta Cowork: Permission to use mcp__workspace__bash has been denied. As regras allow não se transferem: Claude Code nunca aplica uma regra allow Bash a mcp__workspace__bash.

Agent (subagents)

Use regras Agent(AgentName) para controlar quais subagents Claude pode usar:

• Agent(Explore) corresponde ao subagent Explore
• Agent(Plan) corresponde ao subagent Plan
• Agent(my-custom-agent) corresponde a um subagent personalizado nomeado my-custom-agent

Adicione essas regras ao array deny em suas configurações ou use a flag CLI --disallowedTools para desabilitar agentes específicos. Para desabilitar o agente Explore:

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

Cd

As regras Cd controlam para quais diretórios o comando /cd pode mover a sessão. Cd não é uma ferramenta invocável pelo modelo: Claude não pode chamá-la, e as regras se aplicam apenas quando você executa /cd você mesmo.

Uma regra deny Cd simples desabilita /cd inteiramente. Uma regra deny Cd(<path-pattern>) bloqueia alvos correspondentes. As regras deny verificam cada grafia do alvo, incluindo cada salto de symlink que ele se resolve através, portanto uma regra escrita para um caminho também bloqueia alvos que se resolvem para ele.

Adicionar qualquer regra allow Cd muda /cd para modo de lista de permissões: o diretório alvo resolvido deve corresponder a uma de suas regras allow, ou /cd recusa. Sem regras Cd configuradas, /cd mantém seu comportamento padrão e solicita que você confie em um diretório desconhecido.

Os padrões de caminho compartilham as âncoras //, ~/ e / das regras Read e Edit, mas a correspondência é ancorada ao caminho do diretório inteiro em vez de estilo gitignore. * corresponde a exatamente um segmento de caminho e ** corresponde entre segmentos. Um /** final também corresponde à sua raiz nomeada.

Estender permissões com hooks

Os hooks do Claude Code permitem registrar comandos de shell personalizados que avaliam permissões em tempo de execução. Quando Claude Code faz uma chamada de ferramenta, os hooks PreToolUse são executados antes do prompt de permissão, para todas as ferramentas exceto EndConversation. A saída do hook pode negar a chamada de ferramenta, forçar um prompt ou pular o prompt para deixar a chamada prosseguir.

As decisões do hook não contornam as regras de permissão. Claude Code avalia regras deny e ask independentemente do que um hook PreToolUse retorna: uma regra deny correspondente bloqueia a chamada, e uma regra ask correspondente ainda solicita mesmo quando o hook retornou "allow" ou "ask". Isto preserva a precedência deny-first descrita em Gerenciar permissões, incluindo regras deny definidas em configurações gerenciadas.

As ferramentas MCP marcadas como requiresUserInteraction também ainda solicitam quando um hook retorna "allow", assim como as ferramentas connector que sua organização definiu como ask em sessões onde essa configuração chega ao Claude Code.

Um hook de bloqueio também tem precedência sobre regras allow. Um hook que sai com código 2 interrompe a chamada de ferramenta antes das regras de permissão serem avaliadas, portanto o bloqueio se aplica mesmo quando uma regra allow permitiria a chamada. Para executar todos os comandos Bash sem prompts exceto por alguns que você quer bloqueados, adicione "Bash" à sua lista allow e registre um hook PreToolUse que rejeita esses comandos específicos. Veja Bloquear edições em arquivos protegidos para um script de hook que você pode adaptar.

Diretórios de trabalho

Por padrão, Claude tem acesso a arquivos no diretório onde você o iniciou. Esse diretório é o diretório de trabalho primário da sessão até que você mova a sessão com /cd. Você pode estender este acesso:

• Durante a inicialização: use o argumento CLI --add-dir <path>
• Durante a sessão: use o comando /add-dir
• Configuração persistente: adicione a additionalDirectories em arquivos de configuração

Arquivos em diretórios adicionais seguem as mesmas regras de permissão do diretório de trabalho original: eles se tornam legíveis sem prompts, e as permissões de edição de arquivo seguem o modo de permissão atual.

Você não pode adicionar a maioria dos caminhos de rede, como o compartilhamento UNC \\server\share, como diretórios de trabalho, porque procurar um pode entrar em contato com o host que ele nomeia. No Windows, mapeie o compartilhamento para uma letra de unidade e passe a unidade com --add-dir na inicialização.

Defina permissions.blockReadsOutsideWorkingDirectories para fazer com que as ferramentas de arquivo recusem os caminhos que ele delimita em cada modo de permissão. No modo automático, Claude Code oferece ativá-lo na primeira vez que Claude lê fora dos diretórios de trabalho.

Em sessões em segundo plano no macOS, o host da sessão solicita acesso a pastas protegidas como ~/Desktop, ~/Documents e ~/Downloads separadamente do seu terminal quando Claude precisa ler ou escrever arquivos lá; se as leituras falharem com Operation not permitted, consulte como conceder acesso a pastas para sessões em segundo plano.

Mover a sessão para outro diretório

Para mover a sessão para um diretório de trabalho primário diferente, em vez de adicionar um diretório ao lado do atual, execute /cd <path>. Claude Code mantém a conversa, carrega o CLAUDE.md do novo diretório e solicita que você confie no workspace se você não tiver trabalhado nele antes. Depois, Claude Code encontra a sessão movida quando você executa --resume do novo diretório.

Assim que você se move, Claude Code aplica a configuração do projeto do novo diretório:

• Suas configurações de projeto, incluindo suas regras de permissão e hooks
• Seus servidores .mcp.json, sujeitos à mesma aprovação de servidor que na inicialização, e os servidores MCP local-scope que você registrou nele
• Os plugins que suas configurações habilitam, suas skills e seus subagentes
• Seus valores env, aplicados sobre as variáveis de ambiente das configurações do diretório anterior, que permanecem em vigor

Claude Code também desconecta os servidores MCP local-scope do projeto do diretório anterior e os servidores dos plugins que não estão mais habilitados após a mudança. Ele pega diretórios adicionais das configurações do novo diretório em vez do anterior, e mantém os diretórios que você adicionou com --add-dir ou /add-dir. Hooks que a mudança ativa ainda recebem ${CLAUDE_PROJECT_DIR} definido para a raiz do projeto onde a sessão começou.

Quando o novo diretório ainda não é confiável, Claude Code lista no prompt de confiança as regras de permissão, diretórios adicionais, hooks e comandos auxiliares que as configurações do diretório ativariam, para que você possa revisá-los antes de aceitar. Se você recusar, a sessão permanece onde está. Antes da v2.1.246, /cd não aplicava as configurações, hooks, servidores MCP ou skills do novo diretório até que você retomasse a sessão, e seu prompt de confiança não listava o que as configurações do diretório ativariam.

Restrinja ou desabilite destinos /cd com regras de permissão Cd.

Diretórios adicionais concedem acesso a arquivos, não configuração

Adicionar um diretório estende onde Claude pode ler e editar arquivos. Não faz desse diretório uma raiz de configuração completa: a maioria da configuração .claude/ não é descoberta de diretórios adicionais, embora alguns tipos sejam carregados como exceções.

Essas exceções se aplicam apenas a diretórios adicionados com o sinalizador --add-dir ou o comando /add-dir, incluindo diretórios que o Agent SDK adiciona através do sinalizador. Diretórios listados em permissions.additionalDirectories em um arquivo de configuração concedem apenas acesso a arquivos e não carregam nenhuma das configurações abaixo.

O additionalDirectories do Agent SDK em TypeScript e a opção add_dirs em Python recebem as exceções também, mesmo que a opção TypeScript compartilhe seu nome com a chave de configurações. O SDK passa cada entrada para Claude Code como --add-dir, para que esses diretórios se comportem como diretórios adicionados por sinalizador. Skills, comandos e subagentes de qualquer diretório adicionado por sinalizador carregam através da fonte de configuração project, então eles não carregam quando você exclui essa fonte com --setting-sources na CLI ou settingSources no SDK, e bare mode pula os comandos e subagentes entre eles.

Os seguintes tipos de configuração são carregados de diretórios --add-dir:

Para carregar as skills, comandos e subagentes de um subdiretório do seu diretório de trabalho primário no meio da sessão, execute /add-dir com o caminho desse subdiretório. Claude Code os carrega pelo resto da sessão sem solicitá-lo ou adicionar um diretório de trabalho, porque o subdiretório já é legível. Isso requer Claude Code v2.1.257 ou posterior.

Claude Code descobre estilos de saída do diretório de trabalho atual e seus pais, seu diretório de usuário em ~/.claude/ e configurações gerenciadas. Hooks e outras chaves .claude/settings.json carregam da pasta .claude/ do diretório de trabalho atual sem fallback de diretório pai, juntamente com seu ~/.claude/settings.json de usuário e configurações gerenciadas. .claude/settings.local.json carrega da raiz do repositório git, mesmo quando você inicia Claude Code em um subdiretório, exceto nos casos em que Claude Code não usa a raiz do repositório, como no Windows; antes da v2.1.211, ele também carregava apenas do diretório de trabalho atual. Sessões do Agent SDK o carregam do diretório de trabalho em todas as versões.

Para compartilhar essa configuração entre projetos, use uma destas abordagens:

• Configuração em nível de usuário: coloque arquivos em ~/.claude/agents/, ~/.claude/output-styles/ ou ~/.claude/settings.json para torná-los disponíveis em cada projeto
• Plugins: empacote e distribua configuração como um plugin que as equipes podem instalar
• Inicie do diretório de configuração: execute Claude Code do diretório contendo a configuração .claude/ que você deseja

Como as permissões interagem com sandboxing

Permissões e sandboxing são camadas de segurança complementares:

• Permissões controlam quais ferramentas Claude Code pode usar e quais arquivos ou domínios pode acessar. Elas se aplicam a Bash, Read, Edit, WebFetch, MCP e todas as outras ferramentas, exceto que uma regra deny ou ask não pode bloquear EndConversation enquanto qualquer outra ferramenta permanecer.
• Sandboxing fornece imposição em nível de SO que restringe o acesso do Bash à rede e sistema de arquivos. Aplica-se apenas a comandos Bash e seus processos filhos.

Use ambos para defesa em profundidade, já que as restrições de sandbox ainda se aplicam mesmo se uma injeção de prompt contornar a tomada de decisão de Claude. Caminhos e domínios das configurações de sandbox e regras de permissão são mesclados na configuração final de sandbox.

Quando você ativa sandboxing e deixa autoAllowBashIfSandboxed em seu padrão de true, comandos Bash em sandbox são executados sem solicitar mesmo se suas permissões incluem uma regra ask simples Bash, ou o formulário equivalente Bash(*): o limite do sandbox substitui esse prompt de ferramenta inteira.

Em plan mode, Claude Code pula essa substituição. Sem uma regra ask, os comandos somente leitura integrados ainda são executados sem solicitar, e qualquer outro comando shell passa pelo fluxo de permissão regular enquanto você ainda está planejando; veja plan mode para como Claude Code controla comandos lá. Com uma regra ask simples Bash, cada comando Bash solicita, incluindo comandos somente leitura em sandbox, o mesmo que fora do sandboxing. Antes da v2.1.212, a substituição se aplicava em plan mode também.

Estas verificações ainda se aplicam:

• Regras ask com escopo de conteúdo como Bash(git push *) ainda forçam um prompt
• Regras deny explícitas ainda se aplicam
• Comandos rm ou rmdir que visam um caminho crítico ainda passam pelo fluxo de permissão regular

Comandos que não serão executados em sandbox, como comandos excluídos, respeitam a regra ask simples Bash como de costume. Veja modos de sandbox para alterar este comportamento.