​

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 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";

// Criar 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, MultiEdit, 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 total ao sistema
• Recomendado apenas para ambientes controlados

​

Prioridade do Modo no Fluxo de Permissões

1. Hooks executam primeiro - Podem sobrescrever qualquer modo
2. Regras de negação são verificadas - Bloqueiam ferramentas independentemente do modo
3. Modo bypassPermissions - Se ativo, permite todas as ferramentas restantes
4. Regras de permissão são verificadas
5. Outros modos afetam comportamentos específicos de ferramentas
6. Callback canUseTool - Lida com casos restantes

• Hooks sempre podem bloquear o uso de ferramentas, mesmo no modo bypassPermissions
• Regras explícitas de negação sobrescrevem todos os modos de permissão
• Modo bypassPermissions sobrescreve regras de permissão e canUseTool

​

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'

// Mudar 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"
    };
  }
}

// Usar 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);
    }
  }
});

​

Usando Hooks para Controle de Ferramentas

​

Implementação de Hook

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

const result = await query({
  prompt: "Me ajude a refatorar este código",
  options: {
    hooks: {
      PreToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Solicitação de ferramenta: ${input.tool_name}`);
          
          // Analisar e validar entrada da ferramenta você mesmo
          if (input.tool_name === "Bash") {
            const command = input.tool_input.command;
            if (command.startsWith("rm -rf")) {
              return {
                decision: "block",
                reason: "Comando perigoso bloqueado"
              };
            }
          }
          
          return { continue: true };
        }]
      }],
      PostToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Ferramenta concluída: ${input.tool_name}`);
          // Registrar ou auditar resultados da ferramenta
          return { continue: true };
        }]
      }]
    }
  }
});

​

Principais Diferenças do canUseTool

• Escopo: Hooks são chamados para todos os usos de ferramentas; canUseTool lida com casos não cobertos por regras de permissão
• Controle: Hooks requerem análise e validação de entradas você mesmo
• Eventos: Hooks suportam múltiplos eventos (PreToolUse, PostToolUse, etc.) para diferentes estágios

​

Usando Regras de Permissão (settings.json)

​

Estrutura de Configuração

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push:*)",
      "Write(./production/**)"
    ]
  }
}

​

Sintaxe de Regras

• Regras Bash: Usam correspondência de prefixo (não regex). Exemplo: Bash(npm:*) corresponde a qualquer comando começando com “npm”
• Regras de arquivo: Suportam padrões glob. Exemplo: Read(./src/**/*.ts) corresponde a arquivos TypeScript em src
• Regras apenas de ferramenta: Omitir parênteses para controlar ferramentas inteiras. Exemplo: WebFetch bloqueia todas as buscas web

​

Usando com SDK

​

Ordem de Avaliação de Permissões

1. Regras de negação são verificadas primeiro - se corresponderem, o uso da ferramenta é bloqueado
2. Regras de permissão são verificadas em seguida - se corresponderem, o uso da ferramenta é permitido
3. Regras de pergunta são verificadas - se corresponderem, o usuário é solicitado
4. Callback canUseTool é invocado para quaisquer casos restantes

​

Análise de Comandos Bash

• Lida com pipes, redirecionamentos e substituição de comandos
• Reconhece padrões perigosos como rm -rf ou curl | sh
• Suporta wildcards e correspondência de prefixo

• Bash(git:*) - Corresponde a qualquer comando git
• Bash(npm run test) - Corresponde ao comando exato
• Bash(npm run test:*) - Corresponde a comandos Bash começando com npm run test como npm run test anyFile.test.ts

​

Melhores Práticas

1. Comece com o modo padrão para verificações padrão de permissão
2. Use regras de permissão para políticas estáticas, especialmente comandos bash (consulte configurações de permissão)
3. Use hooks para registrar, auditar ou transformar todos os usos de ferramentas (consulte tipos de hook)
4. Use canUseTool para decisões dinâmicas em casos não cobertos (consulte tipo CanUseTool)
5. Camadas de defesa combinando modos, regras, hooks e callbacks para aplicações críticas