​

Permisos del SDK

​

Descripción General

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 son automáticamente aprobadas
• Las operaciones del sistema de archivos (mkdir, touch, rm, etc.) son auto-aprobadas
• 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, MultiEdit, 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 son automáticamente aprobados
• No aparecen solicitudes de permisos
• Los hooks aún se ejecutan (pueden seguir bloqueando 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 anular cualquier modo
2. Se verifican las reglas de denegación - Bloquean herramientas independientemente del modo
3. Modo bypassPermissions - Si está activo, permite todas las herramientas restantes
4. Se verifican las reglas de permitir
5. Otros modos afectan comportamientos específicos de herramientas
6. Callback canUseTool - Maneja casos restantes

• Los hooks siempre pueden bloquear el uso de herramientas, incluso en modo bypassPermissions
• Las reglas explícitas de denegación anulan todos los modos de permisos
• El modo bypassPermissions anula las reglas de permitir y canUseTool

​

Mejores Prácticas

1. Usa el modo predeterminado para ejecución controlada con verificaciones normales de permisos
2. Usa el modo acceptEdits cuando trabajas en archivos o directorios aislados
3. Evita bypassPermissions en producción o en sistemas con datos sensibles
4. Combina modos con hooks para control granular
5. Cambia 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: "Usuario denegó 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);
    }
  }
});

​

Usar Hooks para Control de Herramientas

​

Implementación de Hooks

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

const result = await query({
  prompt: "Ayúdame a refactorizar este código",
  options: {
    hooks: {
      PreToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Solicitud de herramienta: ${input.tool_name}`);
          
          // Analizar y validar entrada de herramienta tú mismo
          if (input.tool_name === "Bash") {
            const command = input.tool_input.command;
            if (command.startsWith("rm -rf")) {
              return {
                decision: "block",
                reason: "Comando peligroso bloqueado"
              };
            }
          }
          
          return { continue: true };
        }]
      }],
      PostToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Herramienta completada: ${input.tool_name}`);
          // Registrar o auditar resultados de herramientas
          return { continue: true };
        }]
      }]
    }
  }
});

​

Diferencias Clave de canUseTool

• Alcance: Los hooks se llaman para todos los usos de herramientas; canUseTool maneja casos no cubiertos por reglas de permisos
• Control: Los hooks requieren analizar y validar entradas tú mismo
• Eventos: Los hooks soportan múltiples eventos (PreToolUse, PostToolUse, etc.) para diferentes etapas

​

Usar Reglas de Permisos (settings.json)

​

Estructura de Configuración

{
  "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/**)"
    ]
  }
}

​

Sintaxis de Reglas

• Reglas Bash: Usan coincidencia de prefijo (no regex). Ejemplo: Bash(npm:*) coincide con cualquier comando que comience con “npm”
• Reglas de archivos: Soportan patrones glob. Ejemplo: Read(./src/**/*.ts) coincide con archivos TypeScript en src
• Reglas solo de herramientas: Omite paréntesis para controlar herramientas completas. Ejemplo: WebFetch bloquea todas las búsquedas web

​

Usar con SDK

​

Orden de Evaluación de Permisos

1. Las reglas de denegación se verifican primero - si coinciden, el uso de herramientas se bloquea
2. Las reglas de permitir se verifican después - si coinciden, el uso de herramientas se permite
3. Las reglas de preguntar se verifican - si coinciden, se solicita al usuario
4. El callback canUseTool se invoca para cualquier caso restante

​

Análisis de Comandos Bash

• Maneja pipes, redirecciones y sustitución de comandos
• Reconoce patrones peligrosos como rm -rf o curl | sh
• Soporta comodines y coincidencia de prefijos

• Bash(git:*) - Coincide con cualquier comando git
• Bash(npm run test)- Coincide con comando exacto
• Bash(npm run test:*) - Coincide con comandos Bash que comienzan con npm run test como npm run test anyFile.test.ts

​

Mejores Prácticas

1. Comienza con modo predeterminado para verificaciones estándar de permisos
2. Usa reglas de permisos para políticas estáticas, especialmente comandos bash (consulta configuraciones de permisos)
3. Usa hooks para registrar, auditar o transformar todos los usos de herramientas (consulta tipos de hooks)
4. Usa canUseTool para decisiones dinámicas en casos no cubiertos (consulta tipo CanUseTool)
5. Estratifica defensas combinando modos, reglas, hooks y callbacks para aplicaciones críticas