Permissões do SDK

O Claude Agent SDK fornece controles de permissão poderosos que permitem gerenciar como Claude usa ferramentas em sua aplicação.

Este guia aborda como implementar sistemas de permissão usando o callback canUseTool, hooks e regras de permissão settings.json. Para documentação completa da API, consulte a referência do SDK TypeScript.

Visão Geral

O Claude Agent SDK fornece quatro maneiras complementares de controlar o uso de ferramentas:

1. Modos de Permissão - Configurações de comportamento de permissão global que afetam todas as ferramentas
2. Callback canUseTool - Manipulador de permissão em tempo de execução para casos não cobertos por outras regras
3. Hooks - Controle refinado sobre cada execução de ferramenta com lógica personalizada
4. Regras de permissão (settings.json) - Regras declarativas de permissão/negação com análise integrada de comandos bash

Casos de uso para cada abordagem:

• Modos de permissão - Definir comportamento geral de permissão (planejamento, aceitação automática de edições, bypass de verificações)
• canUseTool - Aprovação dinâmica para casos não cobertos, solicita permissão ao usuário
• Hooks - Controle programático sobre todas as execuções de ferramentas
• Regras de permissão - Políticas estáticas com análise inteligente de comandos bash

Diagrama de Fluxo de Permissão

Ordem de Processamento: PreToolUse Hook → Regras de Negação → Regras de Permissão → Regras de Solicitação → Verificação de Modo de Permissão → Callback canUseTool → PostToolUse Hook

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 quatro modos de permissão, cada um com comportamento diferente:

Definindo o Modo de Permissão

Você pode definir o modo de permissão de duas maneiras:

1. Configuração Inicial

Defina o modo ao criar uma consulta:

import { query } from "@anthropic-ai/claude-agent-sdk";

const result = await query({
  prompt: "Help me refactor this code",
  options: {
    permissionMode: 'default'  // Standard permission mode
  }
});

2. Alterações Dinâmicas de Modo (Apenas Streaming)

Altere o modo durante uma sessão de streaming:

Comportamentos Específicos do Modo

Modo Aceitar Edições (acceptEdits)

No modo aceitar edições:

• Todas as edições de arquivo são aprovadas automaticamente
• Operações do sistema de arquivos (mkdir, touch, rm, etc.) são auto-aprovadas
• Outras ferramentas ainda requerem permissões normais
• Acelera o desenvolvimento quando você confia nas edições do Claude
• Útil para prototipagem rápida e iterações

Operações auto-aprovadas:

• Edições de arquivo (ferramentas Edit, Write)
• Comandos bash do sistema de arquivos (mkdir, touch, rm, mv, cp)
• Criação e exclusão de arquivo

Modo Bypass de Permissões (bypassPermissions)

No modo bypass de permissões:

• TODOS os usos de ferramentas são aprovados automaticamente
• Nenhum prompt de permissão aparece
• Hooks ainda são executados (ainda podem bloquear operações)
• Use com extremo cuidado - Claude tem acesso total ao sistema
• Recomendado apenas para ambientes controlados

Prioridade do Modo no Fluxo de Permissão

Os modos de permissão são avaliados em um ponto específico no fluxo de permissão:

1. Hooks são executados primeiro - Podem permitir, negar, solicitar ou continuar
2. Regras de negação são verificadas - Bloqueiam ferramentas independentemente do modo
3. Regras de permissão são verificadas - Permitem ferramentas se correspondidas
4. Regras de solicitação são verificadas - Solicitam permissão se correspondidas
5. Modo de permissão é avaliado:
   • Modo bypassPermissions - Se ativo, permite todas as ferramentas restantes
   • Outros modos - Adiam para o callback canUseTool
6. Callback canUseTool - Manipula casos restantes

Isso significa:

• Hooks podem sempre controlar o uso de ferramentas, mesmo no modo bypassPermissions
• Regras de negação explícitas substituem todos os modos de permissão
• Regras de solicitação são avaliadas antes dos modos de permissão
• O modo bypassPermissions substitui o callback canUseTool para ferramentas não correspondidas

Melhores Práticas

1. Use o modo padrão para execução controlada com verificações de permissão normais
2. Use o modo acceptEdits ao trabalhar em arquivos ou diretórios isolados
3. Evite bypassPermissions em produção ou em sistemas com dados sensíveis
4. Combine modos com hooks para controle refinado
5. Alterne modos dinamicamente com base no progresso da tarefa e confiança

Exemplo de progressão de modo:

// Start in default mode for controlled execution
permissionMode: 'default'

// Switch to acceptEdits for rapid iteration
await q.setPermissionMode('acceptEdits')

canUseTool

O callback canUseTool é passado como uma opção ao chamar a função query. Ele recebe o nome da ferramenta e os parâmetros de entrada, e deve retornar uma decisão - permitir ou negar.

canUseTool dispara sempre que Claude Code mostraria um prompt de permissão a um usuário, por exemplo, hooks e regras de permissão não cobrem e não está no modo acceptEdits.

Aqui está um exemplo completo mostrando como implementar aprovação interativa de ferramentas:

Tratamento da Ferramenta AskUserQuestion

A ferramenta AskUserQuestion permite que Claude faça perguntas de esclarecimento ao usuário durante uma conversa. Quando esta ferramenta é chamada, seu callback canUseTool recebe as perguntas e deve retornar as respostas do usuário.

Estrutura de Entrada

Quando canUseTool é chamado com toolName: "AskUserQuestion", a entrada contém:

{
  questions: [
    {
      question: "Which database should we use?",
      header: "Database",
      options: [
        { label: "PostgreSQL", description: "Relational, ACID compliant" },
        { label: "MongoDB", description: "Document-based, flexible schema" }
      ],
      multiSelect: false
    },
    {
      question: "Which features should we enable?",
      header: "Features",
      options: [
        { label: "Authentication", description: "User login and sessions" },
        { label: "Logging", description: "Request and error logging" },
        { label: "Caching", description: "Redis-based response caching" }
      ],
      multiSelect: true
    }
  ]
}

Retornando Respostas

Retorne as respostas em updatedInput.answers como um registro mapeando texto de pergunta para o(s) rótulo(s) de opção selecionada(s):

return {
  behavior: "allow",
  updatedInput: {
    questions: input.questions,  // Pass through original questions
    answers: {
      "Which database should we use?": "PostgreSQL",
      "Which features should we enable?": "Authentication, Caching"
    }
  }
}

Recursos Relacionados

• Guia de Hooks - Aprenda como implementar hooks para controle refinado sobre a execução de ferramentas
• Configurações: Regras de Permissão - Configure regras declarativas de permissão/negação com análise de comandos bash