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 do 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 globais de comportamento de permissão 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 permitir/negar 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, contornar verificações)
• canUseTool - Aprovação dinâmica para casos não cobertos, solicita permissão do 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ões

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D"}, "flowchart": {"edgeLabelMarginX": 12, "edgeLabelMarginY": 8}}}%%
flowchart TD
    Start([Solicitação de ferramenta]) --> PreHook(Hook PreToolUse)

    PreHook -->|  Permitir  | Execute(Executar Ferramenta)
    PreHook -->|  Negar  | Denied(Negado)
    PreHook -->|  Perguntar  | Callback(Callback canUseTool)
    PreHook -->|  Continuar  | Deny(Verificar Regras de Negação)

    Deny -->|  Corresponde  | Denied
    Deny -->|  Não Corresponde  | Allow(Verificar Regras de Permissão)

    Allow -->|  Corresponde  | Execute
    Allow -->|  Não Corresponde  | Ask(Verificar Regras de Pergunta)

    Ask -->|  Corresponde  | Callback
    Ask -->|  Não Corresponde  | Mode{Modo de Permissão?}

    Mode -->|  bypassPermissions  | Execute
    Mode -->|  Outros modos  | Callback

    Callback -->|  Permitir  | Execute
    Callback -->|  Negar  | Denied

    Denied --> DeniedResponse([Feedback para o agente])

    Execute --> PostHook(Hook PostToolUse)
    PostHook --> Done([Resposta da Ferramenta])

    style Start fill:#F0F0EB,stroke:#D9D8D5,color:#191919

    style Denied fill:#BF4D43,color:#fff
    style DeniedResponse fill:#BF4D43,color:#fff
    style Execute fill:#DAAF91,color:#191919
    style Done fill:#DAAF91,color:#191919

    classDef hookClass fill:#CC785C,color:#fff
    class PreHook,PostHook hookClass

    classDef ruleClass fill:#EBDBBC,color:#191919
    class Deny,Allow,Ask ruleClass

    classDef modeClass fill:#A8DAEF,color:#191919
    class Mode modeClass

    classDef callbackClass fill:#D4A27F,color:#191919
    class Callback callbackClass

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

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: "Me ajude a refatorar este código",
  options: {
    permissionMode: 'default'  // Modo de permissão padrão
  }
});

2. Mudanças Dinâmicas de Modo (Apenas Streaming)

Altere o modo durante uma sessão de streaming:

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

// Crie um gerador assíncrono para entrada de streaming
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Vamos começar com permissões padrão" 
    }
  };
  
  // Mais tarde na conversa...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Agora vamos acelerar o desenvolvimento"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // Começar no modo padrão
  }
});

// Alterar modo dinamicamente
await q.setPermissionMode('acceptEdits');

// Processar mensagens
for await (const message of q) {
  console.log(message);
}

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 aprovadas automaticamente
• 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 aprovadas automaticamente:

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

Modo Contornar Permissões (bypassPermissions)

No modo contornar permissões:

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

Prioridade do Modo no Fluxo de Permissões

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

1. Hooks executam primeiro - Podem permitir, negar, perguntar 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 corresponderem
4. Regras de pergunta são verificadas - Solicitam permissão se corresponderem
5. Modo de permissão é avaliado:
   • Modo bypassPermissions - Se ativo, permite todas as ferramentas restantes
   • Outros modos - Deferem para o callback canUseTool
6. Callback canUseTool - Lida com casos restantes

Isso significa:

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

Melhores Práticas

1. Use o modo padrão para execução controlada com verificações normais de permissão
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 baseado no progresso da tarefa e confiança

Exemplo de progressão de modo:

// Começar no modo padrão para execução controlada
permissionMode: 'default'

// Alternar para acceptEdits para iteração rápida
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 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 para um usuário, por exemplo, hooks e regras de permissão não o cobrem e não está no modo acceptEdits.

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

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

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 Solicitação de Ferramenta:");
  console.log(`   Ferramenta: ${toolName}`);
  
  // Exibir parâmetros da ferramenta
  if (input && Object.keys(input).length > 0) {
    console.log("   Parâmetros:");
    for (const [key, value] of Object.entries(input)) {
      let displayValue = value;
      if (typeof value === 'string' && value.length > 100) {
        displayValue = value.substring(0, 100) + "...";
      } else if (typeof value === 'object') {
        displayValue = JSON.stringify(value, null, 2);
      }
      console.log(`     ${key}: ${displayValue}`);
    }
  }
  
  // Obter aprovação do usuário (substitua pela sua lógica de UI)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Aprovado\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Negado\n");
    return {
      behavior: "deny",
      message: "Usuário negou permissão para esta ferramenta"
    };
  }
}

// Use o callback de permissão
const result = await query({
  prompt: "Me ajude a analisar esta base de código",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

Recursos Relacionados

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