​

Permissões do SDK

​

Visão Geral

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

• 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

​

Modos de Permissão

​

Modos Disponíveis

​

Definindo o Modo de Permissão

​

1. Configuração Inicial

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)

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)

• 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

• 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)

• 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

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

• 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

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

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