Configurar permissões
Controle como seu agente usa ferramentas com modos de permissão, hooks e regras declarativas de permitir/negar.
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:
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. Um hook PreToolUse allow também não pode aprovar uma remoção rm ou rmdir direcionada a um caminho crítico.
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. Regras 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.
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"] sempre passam para o callback, mesmo quando uma regra de permitir corresponde. No modo dontAsk ambos os casos são negados, porque esse modo nunca solicita. 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 neste passo. Cada chamada passa para o callback, mesmo no modo bypassPermissions e mesmo quando uma regra de permitir corresponde. O callback recebe o motivo Sua organização requer aprovação para esta ferramenta. No modo dontAsk a chamada é negada, porque esse modo nunca solicita.
Modo de permissão
Aplique o modo de permissão ativo:
- No modo
bypassPermissions, Claude Code aprova tudo que chega a este passo, exceto remoçõesrmermdirdirecionadas a um caminho crítico, que passam adiante. - No modo
acceptEdits, Claude Code aprova as operações de arquivo listadas em Modo Accept edits. - No modo
plan, Claude Code envia ferramentas de edição de arquivo e escrita de shell para seu callbackcanUseToolindependentemente das regras de permitir, portanto operações de escrita não podem ser aprovadas automaticamente durante o planejamento. - Em outros modos, a solicitação passa adiante.
Regras de permitir
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 neste passo 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 rm e rmdir direcionadas a um caminho crítico nunca são aprovadas por uma regra de permitir: elas chegam ao seu callback nos modos que solicitam, vão para o classificador no modo auto no Claude Code v2.1.218 ou posterior, e são negadas no modo dontAsk.
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.
No SDK TypeScript, se você definir permissionPrompts: 'none', seu callback não é chamado neste passo. Um hook PermissionRequest ainda tem a chance de decidir, e se não o fizer, 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', que aprova automaticamente cada chamada que chega ao passo do modo de permissão, exceto pelas ações que nenhum modo aprova automaticamente- Cada entrada
allowedToolssimples 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 permitir 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 em vez disso.
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, quando nenhum passo anterior resolver a chamada. 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. Se você nomear uma das ferramentas de rastreamento de tarefas em allowed_tools, Claude Code também opta 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. 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. Outras ferramentas não listadas aqui ainda existem, e chamadas a elas que precisam de aprovação 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 * conforme escrito são negadas em todos os modos de permissão, incluindo bypassPermissions. Outras chamadas de Bash, incluindo /bin/rm, passam para o modo de permissão. |
disallowed_tools=["*"] |
Toda definição de ferramenta é removida da solicitação. Globs de nome de ferramenta são suportados em regras de negar: "*" corresponde a todas as ferramentas e "mcp__*" corresponde a todas as ferramentas MCP em todos os servidores. |
Regras de permitir 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 auto-aprova nada.
Regras com escopo para Read e Edit usam um padrão de caminho. 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 negar de Edit(//secrets/**) bloqueia escritas em qualquer lugar sob /secrets no disco. Com uma única barra inicial, Edit(/secrets/**) ancora na fonte da regra em vez disso. 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. Consulte Regras de Read e Edit para as quatro formas de âncora e como regras de arquivos de configuração são resolvidas.
Para um agente bloqueado, combine allowedTools com permissionMode: "dontAsk":
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};
Ferramentas listadas são aprovadas, exceto pelas ações que nenhum modo auto-aprova, e toda outra chamada que solicitaria é negada em vez disso. 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 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 baseadas em modo; chamadas que precisam de aprovação e não correspondem a nenhuma regra de permissão acionam seu callback canUseTool |
dontAsk |
Negar em vez de solicitar | Qualquer chamada que de outra forma solicitaria é negada. Chamadas aprovadas por allowed_tools ou regras são executadas, 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 sua organização definida como ask e ferramentas que requerem interação do usuário são negadas mesmo se você as pré-aprovou, assim como remoções de rm e rmdir direcionadas a um caminho crítico. 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 verificações de permissão | As ferramentas são executadas sem solicitações de permissão, exceto pelas ações que nenhum modo auto-aprova. Use com cuidado |
plan |
Modo de planejamento | Claude explora e planeja sem editar seus arquivos de origem; edições de arquivo nunca são auto-aprovadas e solicitam através de seu callback canUseTool |
auto |
Aprovações classificadas por modelo | Um classificador de modelo aprova ou nega solicitações de permissão. Consulte Auto mode para disponibilidade |
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.
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())
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();
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())
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`)
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. No modo acceptEdits, Claude Code não auto-aprova a solicitação quando Claude:
- Trabalha em um caminho fora desse escopo
- Escreve em um caminho protegido
- Remove um caminho crítico com
rmourmdir
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, 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 sua organização definida como ask, ferramentas que requerem interação do usuário e remoções de rm e rmdir direcionadas a um caminho crítico são negadas mesmo quando uma regra de permissão corresponde. Um allow de hook PreToolUse não limpa uma remoção de caminho crítico.
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 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.
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 no modo de permissão default.
Edições de arquivo nunca são auto-aprovadas no modo plano, mesmo quando uma regra de permissão corresponde. Elas solicitam através de seu callback canUseTool em vez disso. 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.
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