Guias

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.

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, que podem permitir, negar ou continuar para a próxima etapa
Regras de permissão
Verifique as regras definidas em settings.json nesta ordem: regras deny primeiro (bloquear independentemente de outras regras), depois regras allow (permitir se correspondidas), depois regras ask (solicitar aprovação). Essas regras declarativas permitem que você pré-aprove, bloqueie ou exija aprovação para ferramentas específicas sem escrever código.
Modo de permissão
Aplique o modo de permissão ativo (bypassPermissions, acceptEdits, dontAsk, etc.)
Callback canUseTool
Se não for resolvido por regras ou modos, chame seu callback canUseTool para uma decisão

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

Esta página se concentra em modos de permissão (etapa 3), a configuração estática que controla o comportamento padrão. Para as outras etapas:

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

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 aprovações automáticas; ferramentas não correspondidas acionam seu callback `canUseTool`
`acceptEdits`	Aceitar automaticamente edições de arquivo	Edições de arquivo e operações do sistema de arquivos (`mkdir`, `rm`, `mv`, etc.) são aprovadas automaticamente
`bypassPermissions`	Ignorar todas as verificações de permissão	Todas as ferramentas são executadas sem prompts de permissão (use com cuidado)
`plan`	Modo de planejamento	Sem execução de ferramentas; Claude planeja sem fazer alterações

Herança de subagentos: Ao usar bypassPermissions, todos os subagentos herdam este modo e ele não pode ser substituído. Os subagentos podem ter prompts de sistema diferentes e comportamento menos restrito do que seu agente principal. Ativar 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.

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 (ferramentas Edit, Write)
Comandos do sistema de arquivos: mkdir, touch, rm, mv, cp

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

Modo ignorar permissões (`bypassPermissions`)

Aprova automaticamente todos os usos de ferramentas sem prompts. Os 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.

Modo plano (`plan`)

Impede a execução de ferramentas completamente. Claude pode analisar código e criar planos, mas não pode fazer alterações. 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 esses prompts.

Use quando: você deseja que Claude proponha alterações sem executá-las, como durante revisão de código ou quando você precisa aprovar alterações antes que sejam feitas.

Recursos relacionados

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

Lidar com aprovações e entrada do usuário: prompts de aprovação interativos 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 permissão/negação em settings.json

Was this page helpful?

Guias

Configurar permissões

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

Como as permissões são avaliadas

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

Hooks
Execute hooks primeiro, que podem permitir, negar ou continuar para a próxima etapa
Regras de permissão
Verifique as regras definidas em settings.json nesta ordem: regras deny primeiro (bloquear independentemente de outras regras), depois regras allow (permitir se correspondidas), depois regras ask (solicitar aprovação). Essas regras declarativas permitem que você pré-aprove, bloqueie ou exija aprovação para ferramentas específicas sem escrever código.
Modo de permissão
Aplique o modo de permissão ativo (bypassPermissions, acceptEdits, dontAsk, etc.)
Callback canUseTool
Se não for resolvido por regras ou modos, chame seu callback canUseTool para uma decisão

Esta página se concentra em modos de permissão (etapa 3), a configuração estática que controla o comportamento padrão. Para as outras etapas:

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

Modos de permissão

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 aprovações automáticas; ferramentas não correspondidas acionam seu callback `canUseTool`
`acceptEdits`	Aceitar automaticamente edições de arquivo	Edições de arquivo e operações do sistema de arquivos (`mkdir`, `rm`, `mv`, etc.) são aprovadas automaticamente
`bypassPermissions`	Ignorar todas as verificações de permissão	Todas as ferramentas são executadas sem prompts de permissão (use com cuidado)
`plan`	Modo de planejamento	Sem execução de ferramentas; Claude planeja sem fazer alterações

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.

Detalhes do modo

Modo aceitar edições (`acceptEdits`)

Operações aprovadas automaticamente:

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

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

Modo ignorar permissões (`bypassPermissions`)

Aprova automaticamente todos os usos de ferramentas sem prompts. Os 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.

Modo plano (`plan`)

Use quando: você deseja que Claude proponha alterações sem executá-las, como durante revisão de código ou quando você precisa aprovar alterações antes que sejam feitas.

Recursos relacionados

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

Lidar com aprovações e entrada do usuário: prompts de aprovação interativos 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 permissão/negação em settings.json

Was this page helpful?

Como as permissões são avaliadas

Modos de permissão

Modos disponíveis

Definir modo de permissão

Detalhes do modo

Modo aceitar edições (acceptEdits)

Modo ignorar permissões (bypassPermissions)

Modo plano (plan)

Recursos relacionados

Como as permissões são avaliadas

Modos de permissão

Modos disponíveis

Definir modo de permissão

Detalhes do modo

Modo aceitar edições (acceptEdits)

Modo ignorar permissões (bypassPermissions)

Modo plano (plan)

Recursos relacionados

Modo aceitar edições (`acceptEdits`)

Modo ignorar permissões (`bypassPermissions`)

Modo plano (`plan`)

Modo aceitar edições (`acceptEdits`)

Modo ignorar permissões (`bypassPermissions`)

Modo plano (`plan`)