Permisos del SDK

El SDK del Agente Claude proporciona controles de permisos poderosos que te permiten gestionar cómo Claude usa las herramientas en tu aplicación.

Esta guía cubre cómo implementar sistemas de permisos usando el callback canUseTool, hooks y reglas de permisos de settings.json. Para documentación completa de la API, consulta la referencia del SDK de TypeScript.

Resumen

El SDK del Agente Claude proporciona cuatro formas complementarias de controlar el uso de herramientas:

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

Casos de uso para cada enfoque:

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

Orden de Procesamiento: Hook PreToolUse → Reglas de Denegación → Reglas de Permiso → Reglas de Pregunta → Verificación de Modo de Permisos → Callback canUseTool → Hook PostToolUse

Modos de Permisos

Los modos de permisos proporcionan control global sobre cómo Claude usa las herramientas. Puedes establecer el modo de permisos al llamar query() o cambiarlo dinámicamente durante sesiones de streaming.

Modos Disponibles

El SDK soporta cuatro modos de permisos, cada uno con comportamiento diferente:

Modo	Descripción	Comportamiento de Herramientas
`default`	Comportamiento estándar de permisos	Se aplican verificaciones normales de permisos
`plan`	Modo de planificación - sin ejecución	Claude solo puede usar herramientas de solo lectura; presenta un plan antes de la ejecución (Actualmente no soportado en el SDK)
`acceptEdits`	Auto-aceptar ediciones de archivos	Las ediciones de archivos y operaciones del sistema de archivos se aprueban automáticamente
`bypassPermissions`	Omitir todas las verificaciones de permisos	Todas las herramientas se ejecutan sin solicitudes de permisos (usar con precaución)

Establecer Modo de Permisos

Puedes establecer el modo de permisos de dos formas:

1. Configuración Inicial

Establece el modo al crear una consulta:

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)

Cambia el modo durante una sesión de streaming:

Comportamientos Específicos del Modo

Modo Aceptar Ediciones (`acceptEdits`)

En modo aceptar ediciones:

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

Operaciones auto-aprobadas:

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

En modo omitir permisos:

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

Los modos de permisos se evalúan en un punto específico del flujo de permisos:

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

Esto significa:

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

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

Ejemplo de progresión de modos:

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

// Cambiar a acceptEdits para iteración rápida
await q.setPermissionMode('acceptEdits')

canUseTool

El callback canUseTool se pasa como una opción al llamar la función query. Recibe el nombre de la herramienta y los parámetros de entrada, y debe devolver una decisión - ya sea permitir o denegar.

canUseTool se activa cuando Claude Code mostraría una solicitud de permiso a un usuario, por ejemplo, los hooks y las reglas de permisos no lo cubren y no está en modo acceptEdits.

Aquí hay un ejemplo completo que muestra cómo implementar aprobación interactiva de herramientas:

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

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

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

Manejo de Permisos

Manejo de Permisos

Permisos del SDK

Resumen

Diagrama de Flujo de Permisos

Modos de Permisos

Modos Disponibles

Establecer Modo de Permisos

1. Configuración Inicial

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

Comportamientos Específicos del Modo

Modo Aceptar Ediciones (`acceptEdits`)

Modo Omitir Permisos (`bypassPermissions`)

Prioridad del Modo en el Flujo de Permisos

Mejores Prácticas

canUseTool

Recursos Relacionados

Permisos del SDK

Resumen

Diagrama de Flujo de Permisos

Modos de Permisos

Modos Disponibles

Establecer Modo de Permisos

1. Configuración Inicial

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

Comportamientos Específicos del Modo

Modo Aceptar Ediciones (acceptEdits)

Modo Omitir Permisos (bypassPermissions)

Prioridad del Modo en el Flujo de Permisos

Mejores Prácticas

canUseTool

Recursos Relacionados

Modo Aceptar Ediciones (`acceptEdits`)

Modo Omitir Permisos (`bypassPermissions`)