Configurar permissões

Controle como seu agente usa ferramentas com modos de permissão, hooks e regras declarativas de permissão/negação.

O Claude Agent SDK fornece controles de permissão para gerenciar como Claude usa ferramentas. Use modos de permissão e regras para definir o que é permitido automaticamente, e o callback canUseTool para lidar com tudo mais em tempo de execução.

Como as permissões são avaliadas

[!NOTE]

Se você carregar um plugin que contém um mod, consulte onde as decisões de um mod se encaixam entre regras e hooks.

Quando Claude solicita uma ferramenta, Claude Code verifica a chamada nestas etapas. Cada etapa pode decidir a chamada, enviá-la para seu callback canUseTool ou passá-la adiante:

1. Hooks

Execute hooks. Um hook pode negar a chamada completamente ou passá-la adiante. Um hook que retorna allow não ignora as etapas de regras de negação e de regras de pergunta, que são avaliadas independentemente do resultado do hook.

Um hook PreToolUse que retorna allow também não pode aprovar um comando rm ou rmdir cujo alvo Claude Code reconhece como um caminho crítico, como rm -rf ~. Para saber o que esse allow faz no modo de planejamento, consulte Aprovações de hooks no modo de planejamento.

2. Regras de negação

Se uma regra de negação de disallowed_tools ou de um arquivo de configurações que o SDK carrega corresponder, a chamada é negada e canUseTool não é chamado. A chamada é negada dessa forma mesmo no modo bypassPermissions e quando um hook retornou allow.

No SDK TypeScript, se você definir a permission_policy de uma ferramenta personalizada como always_deny, uma chamada a essa ferramenta é negada nesta etapa.

3. Regras de pergunta

Verifique as regras ask de settings.json. Se uma regra de pergunta corresponder, a chamada passa para seu callback canUseTool para confirmação, mesmo no modo bypassPermissions.

Ferramentas que requerem interação do usuário se comportam da mesma forma. AskUserQuestion e ferramentas MCP cujo servidor define _meta["anthropic/requiresUserInteraction"] passam para o callback, mesmo quando uma regra de permissão corresponde. No modo dontAsk ambos os casos são negados, porque esse modo transforma cada prompt em uma negação. A anotação MCP requer Claude Code v2.1.199 ou posterior.

Ferramentas do conector claude.ai que sua organização definiu como ask também saem do fluxo nesta etapa. Cada chamada passa para o callback, mesmo no modo bypassPermissions e mesmo quando uma regra de permissão corresponde. O callback recebe o motivo Your organization requires approval for this tool. No modo dontAsk a chamada é negada, porque esse modo nunca solicita.

No SDK TypeScript, se você definir a permission_policy de uma ferramenta personalizada como always_ask, nenhuma regra de permissão aprova suas chamadas, nem mesmo uma entrada allowedTools. No modo dontAsk, Claude Code nega essas chamadas, e nos modos auto, plan ou bypassPermissions ele pode aprová-las antes de seu callback ser executado.

4. Modo de permissão

Aplique o modo de permissão ativo:

• No modo bypassPermissions, Claude Code aprova cada chamada que chega a esta etapa, a menos que seja uma das ações que nenhum modo aprova automaticamente. Para saber quais dessas ações vão para seu callback canUseTool, consulte Modo bypass permissions.
• No modo acceptEdits, Claude Code aprova as operações de arquivo listadas em Modo Accept edits.
• No modo plan, algumas chamadas chegam ao seu callback e, quando o modo auto está disponível, outras vão para o classificador dele. Para mais informações, consulte Modo de planejamento.
• Nos modos default e dontAsk, a chamada segue para as regras de permissão.
• Para o modo auto, consulte Modo auto.

5. Regras de permissão

Verifique as regras allow (de allowed_tools e settings.json). Se uma regra corresponder, a ferramenta é aprovada. Uma chamada que a ferramenta aprova por conta própria é resolvida nesta etapa também, sem necessidade de regra: por exemplo uma leitura de arquivo dentro de seus diretórios de trabalho ou um comando Bash somente leitura.

Remoções de caminho crítico reconhecidas não são aprovadas por uma regra de permissão, e comandos sinalizados com Dangerous rm operation not ruled out não são aprovados por uma regra Bash ou Bash(*). Se eles então chegarem ao seu callback depende do modo de permissão: em uma sessão do Agent SDK no modo auto, por exemplo, Claude Code os nega por padrão sem chamá-lo. A tabela de modos de Caminhos críticos lista o que cada modo faz com eles.

Uma regra de permissão não aprova uma leitura de um caminho de rede.

6. Callback canUseTool

Se nenhuma etapa anterior resolver a requisição, chame seu callback canUseTool para uma decisão. No modo dontAsk, esta etapa é ignorada e a ferramenta é negada, embora um mod que você instalou ainda possa aprovar algumas dessas chamadas.

No SDK TypeScript, se você definir permissionPrompts: 'none', seu callback não é chamado nesta etapa. Um hook PermissionRequest ainda tem a chance de decidir, e se não decidir, Claude Code nega a chamada. A opção requer Claude Code v2.1.259 ou posterior.

Se você passar um callback canUseTool em uma configuração onde o SDK TypeScript espera que a ordem de avaliação aprove automaticamente as chamadas antes do callback ser consultado, o SDK emite um aviso de processo Node.js uma vez quando a consulta é construída. O código do aviso é CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Duas configurações o acionam:

• permissionMode: 'bypassPermissions': o texto do aviso começa com canUseTool will not be invoked: permissionMode 'bypassPermissions'. As chamadas de ferramenta são aprovadas antes de canUseTool ser consultado, então seu callback é executado apenas para algumas chamadas, como as chamadas listadas em Modo bypass permissions. Para verificar também as chamadas aprovadas, coloque as verificações do seu callback em um hook PreToolUse
• Uma entrada allowedTools que é apenas um nome de ferramenta, como "Read": o aviso lista cada entrada desse tipo após canUseTool will not be invoked for:. Chamadas a uma ferramenta listada são aprovadas antes de canUseTool ser consultado, exceto pelas chamadas que uma regra de permissão nunca aprova. Para que seu callback seja executado para as chamadas de uma ferramenta listada que precisam de aprovação, remova a entrada dessa ferramenta de allowedTools

Entradas com um especificador como Bash(ls *) e o modo acceptEdits não o acionam, e regras de permissão provenientes de arquivos de configuração não são visíveis para a verificação.

O aviso não bloqueia nenhuma chamada nem altera nenhuma opção. Se seu callback já recebe todas as chamadas que você deseja verificar, deixe sua configuração como está. Para registrar o aviso em log, ouça com process.on('warning', ...) e corresponda ao código CLAUDE_SDK_CAN_USE_TOOL_SHADOWED.

Esta página se concentra em regras de permissão e negação e modos de permissão. Para as outras etapas:

• Hooks: execute código personalizado para permitir, negar ou modificar solicitações de ferramenta. Veja Controlar execução com hooks.
• Callback canUseTool: solicite aprovação dos usuários em tempo de execução, quando nenhuma etapa anterior resolver a chamada. Veja Lidar com aprovações e entrada do usuário.

Regras de permissão e negação

Quando você define allowedTools e disallowedTools (TypeScript) ou allowed_tools e disallowed_tools (Python), Claude Code adiciona suas entradas às listas de regras de permissão e negação no fluxo de avaliação de permissões. Qualquer outra ferramenta não listada em allowed_tools ainda está disponível para Claude, e uma chamada a ela que precisa de aprovação passa para o modo de permissão.

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_. Uma entrada não ancorada como allowed_tools=["*"] ou allowed_tools=["mcp__*"] é ignorada e não aprova automaticamente nada.

[!WARNING]

Ferramentas aprovadas automaticamente nunca chegam a canUseTool. Uma chamada de ferramenta aprovada em qualquer etapa anterior, por acceptEdits ou bypassPermissions, ou por uma regra de permissão, ignora seu callback canUseTool, portanto as verificações de permissão que você coloca lá são silenciosamente ignoradas para essa ferramenta.

Se chamadas a uma ferramenta em allowed_tools ainda chegarem ao seu callback canUseTool, ou forem negadas no modo dontAsk, verifique se são leituras de caminhos de rede ou se estão entre as chamadas a seguir. Nenhuma regra de permissão aprova essas chamadas. No modo dontAsk, que nunca exibe prompts, Claude Code as nega sem chamar canUseTool, e nos outros modos de permissão você as trata conforme indicado em cada item:

• AskUserQuestion, ferramentas MCP marcadas _meta["anthropic/requiresUserInteraction"] e ferramentas de conector que sua organização definiu como ask: responda a elas no callback. Lidar com perguntas de esclarecimento mostra como responder a AskUserQuestion, e uma chamada de conector chega com o motivo Your organization requires approval for this tool

• Ferramentas personalizadas que sua aplicação marca como always_ask: decida a chamada no callback. Para impedir que essas chamadas cheguem, altere a política no meio da sessão. Nos modos auto, plan e bypassPermissions, a chamada pode, em vez disso, ser aprovada antes do callback, nos casos listados em Modos de permissão que podem aprovar uma chamada always_ask

• Remoções de caminho crítico reconhecidas com rm e rmdir: nos modos default, acceptEdits e bypassPermissions, permita ou negue a remoção no callback, onde decisionReason começa com Dangerous rm. Para os modos auto e plan, veja Remoções de caminho crítico em cada modo de permissão

• Nome simples: uma entrada como Read ou mcp__github__get_issue aprova automaticamente todas as chamadas a essa ferramenta, exceto as ações que nenhum modo aprova automaticamente e as leituras de caminhos de rede.

• Regra com escopo: uma entrada como Bash(npm test *) aprova automaticamente as chamadas correspondentes a ela, e outras chamadas Bash que precisam de aprovação passam para o modo de permissão.

Para verificar chamadas que uma regra de permissão, acceptEdits ou bypassPermissions aprova, use um hook PreToolUse, que também é executado para essas chamadas. Uma negação de hook se aplica mesmo no modo bypassPermissions.

Para um agente bloqueado, combine allowedTools com permissionMode: "dontAsk":

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

As chamadas listadas de Read, Glob e Grep são aprovadas, exceto pelas ações que nenhum modo aprova automaticamente e pelas leituras de caminhos de rede. Todas as outras chamadas que exibiriam um prompt são negadas em vez disso, embora um mod que você instalou ainda possa aprovar algumas dessas chamadas.

Chamadas que não precisam de aprovação no modo default são executadas independentemente de você listá-las. Elas incluem comandos Bash somente leitura, ferramentas como Agent que não solicitam aprovação antes de executar, e leituras de arquivo dentro de seus diretórios de trabalho. Para ocultar completamente uma ferramenta integrada de Claude em vez de negar suas chamadas, adicione seu nome simples a disallowedTools.

[!WARNING]

allowed_tools não restringe bypassPermissions. allowed_tools aprova previamente as ferramentas que você lista. No modo bypassPermissions, Claude Code aprova uma chamada a uma ferramenta não listada, a menos que seja uma das ações que nenhum modo aprova automaticamente.

Se você definir allowed_tools=["Read"] com permission_mode="bypassPermissions", Claude Code ainda aprova chamadas a ferramentas como Bash, Write e Edit. Se você precisar de bypassPermissions mas quiser ferramentas específicas bloqueadas, use disallowed_tools. Para as chamadas que ainda chegam ao seu callback canUseTool nesse modo, veja Modo de bypass de permissões.

Você também pode configurar regras de permissão, negação e solicitação de forma declarativa em .claude/settings.json. Essas regras são lidas quando a fonte de configuração project está habilitada, o que é o padrão para opções query(). Se você definir setting_sources (TypeScript: settingSources) explicitamente, inclua "project" para que se apliquem. Veja Configurações de permissão para a sintaxe das regras.

Para saber quando as regras de permissão no .claude/settings.json de um projeto se aplicam, veja Regras de permissão do projeto e confiança do workspace.

Padrões de caminho em regras

As regras com escopo para Read e Edit usam um padrão de caminho. As regras Edit(path) governam todas as ferramentas integradas que escrevem arquivos, incluindo Write e NotebookEdit, portanto escreva uma regra de caminho para qualquer uma delas como Edit(path). Se você escrever uma regra de caminho como Write(path) ou NotebookEdit(path), ela não corresponde a nenhuma chamada e não tem efeito.

Em allowed_tools e disallowed_tools, inicie um padrão de caminho com // para um caminho absoluto, ou com uma única / para um caminho dentro do diretório de trabalho da sessão:

• //path: com uma regra de negação de Edit(//secrets/**), Claude Code bloqueia escritas sob /secrets no disco feitas pelas ferramentas de arquivo de Claude e por comandos Bash como tee e redirecionamento > file. Um script que Claude executa e que abre arquivos por conta própria ainda pode escrever sob /secrets. Para imposição pelo sistema operacional, veja Configurar a ferramenta Bash em sandbox.
• /path: Edit(/secrets/**) corresponde ao diretório secrets dentro do diretório de trabalho.

Para outras formas de iniciar um padrão de caminho, veja Regras Read e Edit.

Modos de permissão

Os modos de permissão fornecem controle global sobre como Claude usa ferramentas. Você pode definir o modo de permissão ao chamar query() ou alterá-lo dinamicamente durante sessões de streaming.

Com Claude Code v2.1.302 ou posterior, sua aplicação inicia no modo default, a menos que você defina um modo de permissão ou ela obtenha um de permissions.defaultMode em seus arquivos de configuração. No modo default, Claude Code nega qualquer chamada de ferramenta que precise de aprovação, a menos que você a aprove por meio de uma regra de permissão, hook, callback canUseTool ou ferramenta de prompt de permissão. Se chamadas de ferramenta forem negadas, consulte Chamadas de ferramenta negadas em execuções de claude -p e do Agent SDK.

Modos disponíveis

O SDK suporta estes modos de permissão:

[!WARNING]

Herança de subagente: Se sua sessão principal estiver no modo de planejamento, um subagente cuja AgentDefinition define permissionMode: "acceptEdits" ainda é executado no modo de planejamento. As chamadas Edit e Write desse subagente em seus arquivos de origem ainda vão para seu callback canUseTool. O modo de planejamento também vale para os subagentes que você define, para que delegar trabalho a um deles não contorne a revisão prévia do plano.

O subagente herda plan, acceptEdits, auto ou bypassPermissions da sessão principal e, sob uma sessão principal em modo default ou dontAsk, é executado no modo que você definiu. Mesmo assim, Claude Code nunca aplica um valor "bypassPermissions" e aplica um valor "auto" somente quando o modo auto está disponível para esse subagente. A exceção bypassPermissions requer Claude Code v2.1.267 ou posterior.

Subagentes podem ter prompts de sistema diferentes e comportamento menos restrito do que seu agente principal, portanto herdar bypassPermissions concede a eles acesso completo e autônomo ao sistema. As ações que nenhum modo aprova automaticamente ainda se aplicam.

Definir modo de permissão

Você pode definir o modo de permissão uma vez ao iniciar uma consulta, ou alterá-lo dinamicamente enquanto a sessão está ativa.

[tab] No momento da consulta

Passe permission_mode (Python) ou permissionMode (TypeScript) ao criar uma consulta.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
    async for message in query(
        prompt="Help me refactor this code",
        options=ClaudeAgentOptions(
            permission_mode="default",  # Set the mode here
        ),
    ):
        if hasattr(message, "result"):
            print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  for await (const message of query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Set the mode here
    }
  })) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

[tab] Durante streaming

Chame set_permission_mode() (Python) ou setPermissionMode() (TypeScript) para alterar o modo durante a sessão. O novo modo entra em vigor imediatamente para todas as solicitações de ferramenta subsequentes. Isso permite que você comece restritivo e afrouxe as permissões conforme a confiança aumenta, por exemplo, alternando para acceptEdits após revisar a abordagem inicial de Claude.

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
    async with ClaudeSDKClient(
        options=ClaudeAgentOptions(
            permission_mode="default",  # Start in default mode
        )
    ) as client:
        await client.query("Help me refactor this code")

        # Change mode dynamically mid-session
        await client.set_permission_mode("acceptEdits")

        # Process messages with the new permission mode
        async for message in client.receive_response():
            if hasattr(message, "result"):
                print(message.result)


asyncio.run(main())

import { query } from "@anthropic-ai/claude-agent-sdk";

async function main() {
  const q = query({
    prompt: "Help me refactor this code",
    options: {
      permissionMode: "default" // Start in default mode
    }
  });

  // Change mode dynamically mid-session
  await q.setPermissionMode("acceptEdits");

  // Process messages with the new permission mode
  for await (const message of q) {
    if ("result" in message) {
      console.log(message.result);
    }
  }
}

main();

Detalhes do modo

Modo aceitar edições (acceptEdits)

Aprova automaticamente operações de arquivo para que Claude possa editar código sem solicitar. Outras ferramentas (como comandos Bash que não são operações do sistema de arquivos) ainda exigem permissões normais.

Operações aprovadas automaticamente:

• Edições de arquivo com as ferramentas Edit, Write e NotebookEdit
• Comandos do sistema de arquivos: mkdir, touch, rm, rmdir, mv, cp, sed

Ambos se aplicam a caminhos dentro do diretório de trabalho ou de um diretório que você adiciona. Em Python, adicione um com add_dirs e, em TypeScript, com additionalDirectories. No modo acceptEdits, Claude Code não aprova automaticamente a solicitação quando Claude:

• Trabalha em um caminho fora desse escopo
• Escreve em um caminho protegido
• Remove com rm ou rmdir um caminho que Claude Code reconhece como um caminho crítico
• Executa touch com, por exemplo, uma opção, um glob ou um prefixo timeout 5 ou LANG=C

Use quando: você confia nas edições de Claude e deseja iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado.

Modo não perguntar (dontAsk)

Converte qualquer prompt de permissão em uma negação, sem chamar canUseTool, embora um mod que você instalou ainda possa aprovar algumas dessas chamadas. Ferramentas pré-aprovadas por allowed_tools, regras de permissão em settings.json ou um hook são executadas normalmente. Chamadas que não precisam de aprovação no modo default também são executadas, como leituras de arquivo dentro de seus diretórios de trabalho e chamadas para Agent.

Estas chamadas são negadas mesmo quando uma regra de permissão corresponde:

• Ferramentas de conector que sua organização definiu como ask
• Ferramentas que exigem interação do usuário, como AskUserQuestion e ferramentas MCP cujo servidor define _meta["anthropic/requiresUserInteraction"]
• Ferramentas personalizadas cuja permission_policy sua aplicação define como always_ask
• Leituras de caminhos de rede
• Remoções de caminhos críticos reconhecidas

Se seu hook PreToolUse retornar allow para uma remoção de caminho crítico reconhecida, uma leitura de um caminho de rede ou uma chamada a uma ferramenta marcada como always_ask, a chamada ainda é negada. A verificação que reconhece essas remoções pode deixar passar alguns comandos.

Use quando: você executa um agente sem interface e deseja uma negação definitiva para cada chamada que de outra forma solicitaria.

Modo contornar permissões (bypassPermissions)

Aprova automaticamente usos de ferramentas sem solicitar, exceto as ações que nenhum modo aprova automaticamente. Hooks ainda são executados e podem bloquear operações se necessário. No Linux e macOS, Claude Code recusa iniciar neste modo como root ou sob sudo fora de um sandbox reconhecido, e a consulta falha antes do primeiro turno.

[!WARNING]

Use com extrema cautela. Claude tem acesso completo ao sistema neste modo. Use apenas em ambientes controlados onde você confia em todas as operações possíveis.

allowed_tools não restringe este modo, e chamadas a ferramentas que você não listou também são aprovadas. Estes controles ainda se aplicam:

• Regras de negação, regras explícitas ask e hooks são avaliados antes da verificação de modo e ainda podem bloquear uma ferramenta.
• Ferramentas de conector que sua organização definiu como ask, ferramentas que exigem interação do usuário, remoções de caminhos críticos reconhecidas e comandos Bash sinalizados com Dangerous rm operation not ruled out ainda caem para seu callback canUseTool. A verificação que reconhece remoções de caminhos críticos pode deixar passar alguns comandos, e você pode desativar o prompt de remoção de caminho crítico. Fora de uma sessão na nuvem, chamadas a ferramentas personalizadas que sua aplicação marca como always_ask também caem para o callback.
• Os salvaguardas de mensagens entre sessões ainda se aplicam.

Modo plano (plan)

Claude explora a base de código e produz um plano. Durante o planejamento, edições feitas com as ferramentas de arquivo de Claude fora de caminhos protegidos chegam ao seu callback canUseTool, mesmo quando uma regra de permissão corresponde ou um hook PreToolUse retorna allow. Chamadas a AskUserQuestion também chegam ao seu callback, mesmo quando uma regra de permissão nomeia a ferramenta.

Quando o modo auto está disponível, Claude Code envia estas chamadas durante o planejamento ao classificador do modo auto para revisão, em vez de ao seu callback, quando nenhuma regra de permissão as aprova:

• Comandos shell
• Buscas na web
• Pesquisas na web
• Chamadas a ferramentas MCP que seu servidor marca como somente leitura

Essa revisão vem ativada por padrão. Para desativá-la, defina useAutoModeDuringPlan como false na opção settings que você passa para query(), ou nas suas configurações de usuário. Enquanto a revisão estiver desativada, pesquisas na web e chamadas a ferramentas MCP marcadas como somente leitura chegam ao seu callback.

Para comandos shell e buscas na web, a tabela mostra se cada chamada chega ao seu callback:

Para saber o que acontece depois que o classificador recusa várias chamadas seguidas, consulte Limites de bloqueios repetidos.

[!NOTE]

No SDK TypeScript, se você definir allowDangerouslySkipPermissions: true junto com permissionMode: 'plan', edições de arquivo ainda chegam ao seu callback canUseTool. Para alternar mais tarde uma sessão que inicia no modo de planejamento para bypassPermissions com setPermissionMode(), você precisa ter allowDangerouslySkipPermissions definido desde o início.

Use quando: você deseja que Claude produza um plano primeiro, como durante revisão de código ou antes de uma grande alteração.

Modo auto (auto)

Um modelo classificador revisa ações como comandos shell e requisições de rede antes que sejam executadas, e permite ou bloqueia cada uma que revisa. Para os modelos e provedores que o modo auto exige e a ordem em que ele avalia as ações, consulte Eliminar prompts de permissão com o modo auto.

Se você alternar uma sessão que está em modo auto para um modelo que o modo auto não suporta, usando set_model(), setModel() ou applyFlagSettings(), a sessão muda para o modo default:

• O que você vê: uma mensagem system com subtipo status e permissionMode definido como "default", que o TypeScript SDK tipa como SDKStatusMessage. A partir daí, chamadas que precisam de aprovação e não correspondem a nenhuma regra de permissão chegam ao seu callback canUseTool.
• Para retornar ao modo auto: alterne para um modelo suportado e, em seguida, chame set_permission_mode("auto") ou setPermissionMode("auto"). Se você alternar o modelo de volta sem fazer essa chamada, a sessão permanece no modo default. Enquanto o modelo não suportado estiver ativo, a chamada falha com Cannot set permission mode to auto: auto mode unavailable for this model.

A mudança para o modo default após uma chamada set_model(), setModel() ou applyFlagSettings() requer Claude Code v2.1.299 ou posterior.

Recursos relacionados

Para as outras etapas no fluxo de avaliação de permissões:

• Lidar com aprovações e entrada do usuário: prompts de aprovação interativa e perguntas de esclarecimento
• Guia de hooks: executar código personalizado em pontos-chave do ciclo de vida do agente
• Regras de permissão: regras declarativas de permissão/negação em settings.json