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:

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

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

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

    PreHook -->|  Permitir  | Execute(Ejecutar Herramienta)
    PreHook -->|  Denegar  | Denied(Denegado)
    PreHook -->|  Preguntar  | Callback(Callback canUseTool)
    PreHook -->|  Continuar  | Deny(Verificar Reglas de Denegación)

    Deny -->|  Coincidencia  | Denied
    Deny -->|  Sin Coincidencia  | Allow(Verificar Reglas de Permiso)

    Allow -->|  Coincidencia  | Execute
    Allow -->|  Sin Coincidencia  | Ask(Verificar Reglas de Pregunta)

    Ask -->|  Coincidencia  | Callback
    Ask -->|  Sin Coincidencia  | Mode{¿Modo de Permisos?}

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

    Callback -->|  Permitir  | Execute
    Callback -->|  Denegar  | Denied

    Denied --> DeniedResponse([Retroalimentación al agente])

    Execute --> PostHook(Hook PostToolUse)
    PostHook --> Done([Respuesta de Herramienta])

    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

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:

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:

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)

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:

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

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

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

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:

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