​

Permisos del SDK

​

Resumen

1. Modos de Permisos - Configuraciones globales de comportamiento de permisos que afectan todas las herramientas
2. callback canUseTool - Manejador de permisos en tiempo de ejecución para casos no cubiertos por otras reglas
3. Hooks - Control granular sobre cada ejecución de herramienta con lógica personalizada
4. Reglas de permisos (settings.json) - Reglas declarativas de permitir/denegar con análisis integrado de comandos bash

• Modos de permisos - Establecer comportamiento general de permisos (planificación, auto-aceptar ediciones, omitir verificaciones)
• canUseTool - Aprobación dinámica para casos no cubiertos, solicita permiso al usuario
• Hooks - Control programático sobre todas las ejecuciones de herramientas
• Reglas de permisos - Políticas estáticas con análisis inteligente de comandos bash

​

Diagrama de Flujo de Permisos

​

Modos de Permisos

​

Modos Disponibles

​

Establecer Modo de Permisos

​

1. Configuración Inicial

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

const result = await query({
  prompt: "Ayúdame a refactorizar este código",
  options: {
    permissionMode: 'default'  // Modo de permisos estándar
  }
});

​

2. Cambios Dinámicos de Modo (Solo Streaming)

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

// Crear un generador asíncrono para entrada de streaming
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Comencemos con permisos predeterminados" 
    }
  };
  
  // Más tarde en la conversación...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Ahora aceleremos el desarrollo"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // Comenzar en modo predeterminado
  }
});

// Cambiar modo dinámicamente
await q.setPermissionMode('acceptEdits');

// Procesar mensajes
for await (const message of q) {
  console.log(message);
}

​

Comportamientos Específicos del Modo

​

Modo Aceptar Ediciones (acceptEdits)

• Todas las ediciones de archivos se aprueban automáticamente
• Las operaciones del sistema de archivos (mkdir, touch, rm, etc.) se auto-aprueban
• Otras herramientas aún requieren permisos normales
• Acelera el desarrollo cuando confías en las ediciones de Claude
• Útil para prototipado rápido e iteraciones

• Ediciones de archivos (herramientas Edit, Write)
• Comandos bash del sistema de archivos (mkdir, touch, rm, mv, cp)
• Creación y eliminación de archivos

​

Modo Omitir Permisos (bypassPermissions)

• TODOS los usos de herramientas se aprueban automáticamente
• No aparecen solicitudes de permisos
• Los hooks aún se ejecutan (pueden bloquear operaciones)
• Usar con extrema precaución - Claude tiene acceso completo al sistema
• Recomendado solo para entornos controlados

​

Prioridad del Modo en el Flujo de Permisos

1. Los hooks se ejecutan primero - Pueden permitir, denegar, preguntar o continuar
2. Se verifican las reglas de denegación - Bloquean herramientas independientemente del modo
3. Se verifican las reglas de permiso - Permiten herramientas si coinciden
4. Se verifican las reglas de pregunta - Solicitan permiso si coinciden
5. Se evalúa el modo de permisos:
   • Modo bypassPermissions - Si está activo, permite todas las herramientas restantes
   • Otros modos - Delegan al callback canUseTool
6. Callback canUseTool - Maneja los casos restantes

• Los hooks siempre pueden controlar el uso de herramientas, incluso en modo bypassPermissions
• Las reglas de denegación explícitas anulan todos los modos de permisos
• Las reglas de pregunta se evalúan antes que los modos de permisos
• El modo bypassPermissions anula el callback canUseTool para herramientas no coincidentes

​

Mejores Prácticas

1. Usar modo predeterminado para ejecución controlada con verificaciones normales de permisos
2. Usar modo acceptEdits cuando trabajas en archivos o directorios aislados
3. Evitar bypassPermissions en producción o en sistemas con datos sensibles
4. Combinar modos con hooks para control granular
5. Cambiar modos dinámicamente basado en el progreso de la tarea y la confianza

// Comenzar en modo predeterminado para ejecución controlada
permissionMode: 'default'

// Cambiar a acceptEdits para iteración 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🔧 Solicitud de Herramienta:");
  console.log(`   Herramienta: ${toolName}`);
  
  // Mostrar parámetros de la herramienta
  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}`);
    }
  }
  
  // Obtener aprobación del usuario (reemplazar con tu lógica de UI)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Aprobado\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Denegado\n");
    return {
      behavior: "deny",
      message: "El usuario denegó el permiso para esta herramienta"
    };
  }
}

// Usar el callback de permisos
const result = await query({
  prompt: "Ayúdame a analizar esta base de código",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

​

Recursos Relacionados

• Guía de Hooks - Aprende cómo implementar hooks para control granular sobre la ejecución de herramientas
• Configuraciones: Reglas de Permisos - Configura reglas declarativas de permitir/denegar con análisis de comandos bash