Configurar permissões - Claude Code Docs

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.

Esta página cobre modos de permissão e regras. Para construir fluxos de aprovação interativos onde os usuários aprovam ou negam solicitações de ferramentas em tempo de execução, consulte Lidar com aprovações e entrada do usuário.

Como as permissões são avaliadas

Quando Claude solicita uma ferramenta, o SDK verifica as permissões nesta ordem:

Hooks

Execute hooks primeiro. Um hook pode negar a chamada completamente ou passá-la adiante. Um hook que retorna allow não ignora as regras de negar e perguntar abaixo; essas são avaliadas independentemente do resultado do hook.

Regras de negação

Verifique as regras deny (de disallowed_tools e settings.json). Se uma regra de negação corresponder, a ferramenta é bloqueada, mesmo no modo bypassPermissions. Entradas com nome simples como Bash removem a ferramenta do contexto do Claude antes desta avaliação começar, portanto apenas regras com escopo como Bash(rm *) são verificadas neste passo.

Modo de permissão

Aplique o modo de permissão ativo. bypassPermissions aprova tudo que chega a este passo. acceptEdits aprova operações de arquivo. Outros modos passam adiante.

Regras de permissão

Verifique as regras allow (de allowed_tools e settings.json). Se uma regra corresponder, a ferramenta é aprovada.

Callback canUseTool

Se não for resolvido por nenhum dos anteriores, chame seu callback canUseTool para uma decisão. No modo dontAsk, este passo é ignorado e a ferramenta é negada.

Diagrama de fluxo de avaliação de permissões

Esta página se concentra em regras de permitir e negar e modos de permissão. Para os outros passos:

Hooks: execute código personalizado para permitir, negar ou modificar solicitações de ferramentas. Consulte Controlar execução com hooks.
Callback canUseTool: solicite aprovação dos usuários em tempo de execução. Consulte Lidar com aprovações e entrada do usuário.

Regras de permitir e negar

allowed_tools e disallowed_tools (TypeScript: allowedTools / disallowedTools) adicionam entradas às listas de regras de permitir e negar no fluxo de avaliação acima. Regras de permitir afetam apenas a aprovação: uma ferramenta não listada em allowed_tools ainda está disponível para Claude e passa para o modo de permissão. Regras de negar se comportam de forma diferente dependendo se nomeiam uma ferramenta ou definem um padrão dentro de uma.

Opção	Efeito
`allowed_tools=["Read", "Grep"]`	`Read` e `Grep` são auto-aprovadas. Ferramentas não listadas aqui ainda existem e passam para o modo de permissão e `canUseTool`.
`disallowed_tools=["Bash"]`	A definição da ferramenta `Bash` é removida da solicitação. Claude não vê a ferramenta e não pode tentar usá-la.
`disallowed_tools=["Bash(rm *)"]`	`Bash` permanece disponível. Chamadas correspondentes a `rm *` são negadas em todos os modos de permissão, incluindo `bypassPermissions`. Outras chamadas de `Bash` passam para o modo de permissão.

Para um agente bloqueado, combine allowedTools com permissionMode: "dontAsk". Ferramentas listadas são aprovadas; qualquer outra coisa é negada completamente em vez de solicitar:

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

allowed_tools não restringe bypassPermissions. allowed_tools apenas pré-aprova as ferramentas que você lista. Ferramentas não listadas não são correspondidas por nenhuma regra de permitir e passam para o modo de permissão, onde bypassPermissions as aprova. Definir allowed_tools=["Read"] junto com permission_mode="bypassPermissions" ainda aprova todas as ferramentas, incluindo Bash, Write e Edit. Se você precisar de bypassPermissions mas quiser que ferramentas específicas sejam bloqueadas, use disallowed_tools.

Você também pode configurar regras de permitir, negar e perguntar declarativamente 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. Consulte Configurações de permissão para a sintaxe das regras.

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.

Modos disponíveis

O SDK suporta estes modos de permissão:

Modo	Descrição	Comportamento da ferramenta
`default`	Comportamento de permissão padrão	Sem auto-aprovações; ferramentas não correspondidas acionam seu callback `canUseTool`
`dontAsk`	Negar em vez de solicitar	Qualquer coisa não pré-aprovada por `allowed_tools` ou regras é negada; `canUseTool` nunca é chamado
`acceptEdits`	Auto-aceitar edições de arquivo	Edições de arquivo e operações de sistema de arquivos (`mkdir`, `rm`, `mv`, etc.) são automaticamente aprovadas
`bypassPermissions`	Ignorar todas as verificações de permissão	Todas as ferramentas são executadas sem solicitações de permissão (use com cuidado)
`plan`	Modo de planejamento	Ferramentas somente leitura são executadas; Claude analisa e planeja sem editar seus arquivos de origem
`auto` (Apenas TypeScript)	Aprovações classificadas por modelo	Um classificador de modelo aprova ou nega cada chamada de ferramenta. Consulte Modo Auto para disponibilidade

Herança de subagentos: Quando o pai usa bypassPermissions, acceptEdits ou auto, todos os subagentos herdam esse modo e ele não pode ser substituído por subagentos. Subagentos 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 sem nenhum prompt de aprovação.

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.

No momento da consulta
Durante streaming

Passe permission_mode (Python) ou permissionMode (TypeScript) ao criar uma consulta. Este modo se aplica para toda a sessão, a menos que seja alterado dinamicamente.

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())

Chame set_permission_mode() (Python) ou setPermissionMode() (TypeScript) para alterar o modo no meio da sessão. O novo modo entra em vigor imediatamente para todas as solicitações de ferramentas 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())

Detalhes do modo

Modo aceitar edições (`acceptEdits`)

Auto-aprova 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 de sistema de arquivos) ainda requerem permissões normais. Operações auto-aprovadas:

Edições de arquivo (ferramentas Edit, Write)
Comandos de sistema de arquivos: mkdir, touch, rm, rmdir, mv, cp, sed

Ambos se aplicam apenas a caminhos dentro do diretório de trabalho ou additionalDirectories. Caminhos fora desse escopo e gravações em caminhos protegidos ainda solicitam. Use quando: você confia nas edições de Claude e quer iteração mais rápida, como durante prototipagem ou ao trabalhar em um diretório isolado.

Modo não perguntar (`dontAsk`)

Converte qualquer solicitação de permissão em uma negação. Ferramentas pré-aprovadas por allowed_tools, regras de permitir em settings.json ou um hook são executadas normalmente. Tudo mais é negado sem chamar canUseTool. Use quando: você quer uma superfície de ferramenta fixa e explícita para um agente sem cabeça e prefere uma negação dura sobre confiança silenciosa em canUseTool estar ausente.

Modo ignorar permissões (`bypassPermissions`)

Auto-aprova todos os usos de ferramentas sem solicitações. Hooks ainda são executados e podem bloquear operações se necessário.

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. Todas as ferramentas são aprovadas, não apenas as que você listou. Regras de negação (disallowed_tools), regras explícitas de ask e hooks são avaliados antes da verificação do modo e ainda podem bloquear uma ferramenta.

Modo plano (`plan`)

Restringe Claude a ferramentas somente leitura. Claude pode ler arquivos e executar comandos shell somente leitura para explorar a base de código, mas não edita seus arquivos de origem. Claude pode usar AskUserQuestion para esclarecer requisitos antes de finalizar o plano. Consulte Lidar com aprovações e entrada do usuário para lidar com essas solicitações. Use quando: você quer que Claude proponha mudanças sem executá-las, como durante revisão de código ou quando você precisa aprovar mudanças antes que sejam feitas.

Recursos relacionados

Para os outros passos no fluxo de avaliação de permissões:

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

​Como as permissões são avaliadas

​Regras de permitir e negar

​Modos de permissão

​Modos disponíveis

​Definir modo de permissão

​Detalhes do modo

​Modo aceitar edições (acceptEdits)

​Modo não perguntar (dontAsk)

​Modo ignorar permissões (bypassPermissions)

​Modo plano (plan)

​Recursos relacionados

Como as permissões são avaliadas

Regras de permitir e negar

Modos de permissão

Modos disponíveis

Definir modo de permissão

Detalhes do modo

Modo aceitar edições (`acceptEdits`)

Modo não perguntar (`dontAsk`)

Modo ignorar permissões (`bypassPermissions`)

Modo plano (`plan`)

Recursos relacionados