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

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

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', que aprova automaticamente cada chamada que chega à etapa do modo de permissão, exceto pelas ações que nenhum modo aprova automaticamente
• Cada entrada allowedTools simples como "Read", que aprova automaticamente essa ferramenta inteira antes do callback ser consultado, exceto pelas ações que nenhum modo aprova automaticamente

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.

Ouça com process.on('warning', ...) e corresponda o código para registrá-lo ou suprimi-lo. Para controlar cada chamada de ferramenta independentemente do modo e das regras, use um hook PreToolUse.

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

allowed_tools e disallowed_tools (TypeScript: allowedTools / disallowedTools) adicionam entradas às listas de regras de permissão e negação no fluxo de avaliação acima. Se você nomear uma das ferramentas de rastreamento de tarefas em allowed_tools, Claude Code também ativa a sessão. 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 negação se comportam de forma diferente dependendo se nomeiam uma ferramenta ou definem um padrão dentro de uma.

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 com um aviso de inicialização e não aprova automaticamente nada.

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; uma regra Write(path) nunca é correspondida pelas verificações de permissão de arquivo.

Use //path para um caminho absoluto do sistema de arquivos: uma regra de negação de Edit(//secrets/**) bloqueia escritas em qualquer lugar sob /secrets no disco. Com uma única barra inicial, Edit(/secrets/**) ancora na fonte da regra. Para regras passadas através de allowed_tools ou disallowed_tools, isso significa o diretório de trabalho da sessão, portanto a regra não bloqueia /secrets no disco. Veja Regras Read e Edit para as quatro formas de âncora e como as regras dos arquivos de configuração são resolvidas.

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

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

As ferramentas listadas são aprovadas, exceto pelas ações que nenhum modo aprova automaticamente, e todas as outras chamadas que solicitariam aprovação são negadas. Chamadas que não precisam de aprovação no modo default são executadas independentemente de você listá-las, como comandos Bash somente leitura, ferramentas como Agent que não solicitam antes de executar, e leituras de arquivo dentro de seus diretórios de trabalho. Para colocar uma ferramenta completamente fora do alcance de Claude, adicione seu nome simples a disallowedTools.

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.

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:

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.

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

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

Ambos se aplicam apenas a caminhos dentro do diretório de trabalho ou 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 um caminho crítico com rm ou rmdir

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. Ferramentas pré-aprovadas por allowed_tools, regras de permissão em settings.json ou um hook são executadas normalmente, assim como chamadas que não precisam de aprovação no modo default, como leituras de arquivo dentro de seus diretórios de trabalho e chamadas para Agent. Ferramentas de conector que sua organização definiu como ask, ferramentas que exigem interação do usuário e remoções rm e rmdir direcionadas a um caminho crítico são negadas mesmo quando uma regra de permissão corresponde. Uma permissão de hook PreToolUse também não limpa uma remoção de caminho crítico.

Use quando: você deseja uma superfície de ferramenta fixa e explícita para um agente sem interface e prefere uma negação definitiva em vez de depender silenciosamente de canUseTool estar ausente.

Modo contornar permissões (`bypassPermissions`)

Aprova automaticamente usos de ferramentas sem solicitar, exceto os casos listados no aviso abaixo. 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 uma sandbox reconhecida, e a consulta falha antes da primeira volta.

Modo plano (`plan`)

Claude explora a base de código e produz um plano sem editar seus arquivos de origem. Ferramentas somente leitura são executadas como fazem no modo de permissão default.

Edições de arquivo nunca são aprovadas automaticamente no modo plano, mesmo quando uma regra de permissão corresponde. Em vez disso, elas solicitam através de seu callback canUseTool. No Claude Code v2.1.212 ou posterior, comandos shell que modificam arquivos, como touch e rm, chegam ao seu callback canUseTool da mesma forma.

Se você definir allowDangerouslySkipPermissions: true junto com permissionMode: 'plan', edições de arquivo e comandos shell que modificam arquivos ainda chegam ao seu callback canUseTool. A opção permite que você alterne para bypassPermissions mais tarde com setPermissionMode().

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õ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