SpyBara
Go Premium

agent-sdk/permissions.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 48 additions and 46 deletions.

2026
Thu 1 23:59 Fri 9 23:02 Sat 10 23:01 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Mon 26 22:57 Tue 27 22:59 Fri 30 23:01

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:

1. Hooks

Execute hooks primeiro. Um hook pode negar a chamada completamente ou deixá-la passar. Um hook que retorna allow não ignora as regras de negação e pergunta abaixo; essas 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

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 de negação 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 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"] sempre passam para o callback, mesmo quando uma regra de permissão 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 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.

4. Modo de permissão

Aplique o modo de permissão ativo:

  • No modo bypassPermissions, Claude Code aprova tudo que chega a esta etapa, exceto remoções de caminho crítico reconhecidas, que passam para a próxima etapa.
  • 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 callback canUseTool independentemente das regras de permissão, para que operações de escrita não possam ser aprovadas automaticamente durante o planejamento.
  • Em outros modos, a solicitação passa para a próxima etapa.

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. Se elas 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 as nega por padrão sem chamá-lo. A tabela de modos de Caminhos críticos lista o que cada modo faz com elas.

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

6. Callback canUseTool

Se não for resolvido por nenhum dos anteriores, 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.

Diagrama do fluxo de avaliação de permissões em seis etapas correspondendo às etapas acima: uma solicitação de ferramenta passa por hooks, regras de negação, regras de pergunta, modo de permissão, regras de permissão e canUseTool. Hooks, regras de negação e canUseTool podem rotear para Bloqueado; bypass do modo de permissão, regras de permissão e canUseTool podem rotear para Executar; regras de pergunta rotear para canUseTool.

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:

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:

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 as habilita na 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.

Opção Efeito
allowed_tools=["Read", "Grep"] Read e Grep são aprovadas automaticamente, exceto por leituras de caminhos de rede. 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 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 negação: "*" corresponde a todas as ferramentas e "mcp__*" corresponde a todas as ferramentas MCP em todos os servidores.

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.

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.

[!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.

Nenhuma regra de permissão aprova automaticamente AskUserQuestion, ferramentas MCP marcadas _meta["anthropic/requiresUserInteraction"], ferramentas de conector que sua organização definiu como ask, ou remoções de caminho crítico reconhecidas com rm e rmdir. No modo dontAsk Claude Code nega essas chamadas sem invocar o callback. Em outros modos os três primeiros chegam ao callback. A tabela de modos de caminhos críticos lista o que cada modo faz com uma remoção de caminho crítico. A verificação que reconhece essas remoções pode deixar passar alguns comandos.

A cobertura depende da forma da entrada: um nome simples como Read ou mcp__github__get_issue aprova automaticamente todas as chamadas a essa ferramenta, exceto essas exceções e leituras de caminhos de rede, enquanto uma regra com escopo como Bash(npm test *) aprova automaticamente apenas chamadas correspondentes, e outras chamadas Bash que precisam de aprovação ainda passam para o callback. Para verificações que devem ser executadas em todas as chamadas de ferramenta, use um hook PreToolUse: hooks são executados antes de qualquer outra etapa, e 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 ferramentas listadas 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 remover uma ferramenta completamente da requisição, adicione seu nome simples a disallowedTools.

[!WARNING]

allowed_tools não restringe bypassPermissions. allowed_tools aprova previamente as ferramentas que você lista. Outras ferramentas não listadas não são correspondidas por nenhuma regra de permissão 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 ferramentas específicas bloqueadas, use disallowed_tools.

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.

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:

Modo Descrição Comportamento da ferramenta
default Comportamento de permissão padrão Sem aprovações automáticas 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 sem chamar canUseTool, embora um mod que você instalou ainda possa aprovar algumas dessas chamadas. Chamadas aprovadas por allowed_tools ou por regras de permissão em settings.json são executadas, assim como chamadas que não precisam de aprovação no modo default. Algumas chamadas, como leituras de caminhos de rede, são negadas mesmo quando allowed_tools ou uma regra de permissão corresponde a elas. Para a lista, consulte Modo não perguntar
acceptEdits Aceitar automaticamente edições de arquivo Edições de arquivo e operações do sistema de arquivos (mkdir, rm, mv, etc.) são automaticamente aprovadas
bypassPermissions Contornar verificações de permissão As ferramentas são executadas sem prompts de permissão, exceto pelas ações que nenhum modo aprova automaticamente. Use com cuidado
plan Modo de planejamento Claude explora e planeja sem editar seus arquivos de origem; edições de arquivo nunca são aprovadas automaticamente e solicitam através de seu callback canUseTool
auto Aprovações classificadas pelo modelo Um classificador de modelo revisa ações como comandos shell e solicitações de rede, permitindo ou bloqueando cada uma que revisa. Consulte Modo Auto para disponibilidade e a ordem de decisã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.

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

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 (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 com rm ou rmdir um caminho que Claude Code reconhece como um caminho crítico

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.

Ferramentas de conector que sua organização definiu como ask, ferramentas que exigem interação do usuário, leituras de caminhos de rede e remoções de caminhos críticos reconhecidas são negadas mesmo quando uma regra de permissão corresponde. Uma permissão de hook PreToolUse também não libera uma remoção de caminho crítico reconhecida nem uma leitura de um caminho de rede. A verificação que reconhece essas remoções pode deixar passar alguns comandos.

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.

[!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. Cada ferramenta é aprovada, não apenas as que você listou. Estes controles ainda se aplicam:

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 de planejamento, mesmo quando uma regra de permissão corresponde ou um hook PreToolUse retorna allow. 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.

No SDK TypeScript, 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.

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: