Modelo de permisos

Sistema de permisos por niveles

Claude Code clasifica cada herramienta en uno de tres niveles de aprobación según el riesgo que implica su ejecución. Este modelo garantiza que las operaciones seguras se ejecuten sin fricción mientras las potencialmente destructivas requieran confirmación explícita.

| Tipo de herramienta | Ejemplo | Aprobación | Persistencia | |---|---|---|---| | Solo lectura | Read, Grep, Glob, LS | No requiere | N/A | | Modificación de archivos | Edit, Write, MultiEdit | Requiere | Hasta el final de la sesión | | Comandos de terminal | Bash | Requiere | Permanente por proyecto y comando |

Las herramientas de solo lectura nunca solicitan permiso. Claude puede leer archivos, buscar patrones y listar directorios libremente, ya que estas operaciones no alteran el estado del proyecto.

Las herramientas de modificación de archivos requieren aprobación la primera vez que se utilizan en una sesión. Una vez que el usuario acepta una edición, Claude puede seguir editando archivos sin pedir permiso hasta que la sesión termine.

Los comandos Bash requieren aprobación individual. Cuando el usuario acepta un comando, esa aprobación se almacena de forma permanente para ese proyecto y ese patrón de comando. Si se aprueba npm test, Claude podrá ejecutarlo en futuras sesiones sin volver a preguntar.

La persistencia de los permisos de Bash es deliberada: un comando aprobado una vez se considera seguro para ese proyecto de forma indefinida. Esta decisión prioriza la productividad a largo plazo, pero exige revisar cada aprobación con cuidado.

flowchart TD
    A["Claude invoca herramienta"] --> B{"Tipo de herramienta?"}
    B -->|Solo lectura| C["Ejecuta sin aprobación"]
    B -->|Modificación| D{"Aprobada en esta sesión?"}
    B -->|Bash| E{"Aprobada en este proyecto?"}
    D -->|Sí| C
    D -->|No| F["Solicita aprobación"]
    E -->|Sí| C
    E -->|No| F
    F -->|Acepta| G["Ejecuta y almacena"]
    F -->|Rechaza| H["Operación cancelada"]

Reglas de permisos

Las reglas de permisos permiten preconfigurar qué herramientas puede o no puede usar Claude Code, sin depender de la aprobación interactiva durante la sesión. Se definen en los archivos settings.json y aplican tres tipos de reglas:

• allow: herramientas que Claude puede ejecutar sin pedir permiso.
• ask: herramientas que requieren confirmación antes de cada ejecución.
• deny: herramientas bloqueadas por completo. Claude no puede usarlas bajo ninguna circunstancia.

Las reglas se evalúan en orden de prioridad: deny primero, ask después, allow último. La primera regla que coincida con la acción gana. Esto significa que si una herramienta aparece tanto en allow como en deny, queda bloqueada.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git log *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(rm -rf *)",
      "Bash(git push *)",
      "Read(./.env)"
    ]
  }
}

En este ejemplo, Claude puede ejecutar scripts npm y consultar el historial de Git sin aprobación, pero tiene bloqueados los comandos destructivos, los push y la lectura de archivos .env.

Sintaxis de reglas

Cada regla sigue el formato Herramienta o Herramienta(especificador). El nombre de la herramienta sin paréntesis coincide con todos los usos de esa herramienta. El especificador entre paréntesis restringe la coincidencia a usos concretos.

Reglas de Bash

Las reglas de Bash soportan patrones con comodín (*) que pueden aparecer en cualquier posición del comando:

| Regla | Coincide con | |---|---| | Bash | Todos los comandos Bash | | Bash(npm run build) | Exactamente npm run build | | Bash(npm run *) | Cualquier comando que empiece por npm run | | Bash(git * main) | Comandos como git checkout main, git merge main | | Bash(* --version) | Cualquier comando terminado en --version |

El espacio antes de * importa. Bash(ls *) coincide con ls -la pero no con lsof. En cambio, Bash(ls*) sin espacio coincide con ambos, porque no impone separación de palabras.

Claude Code es consciente de los operadores de shell como && y ||. Una regla como Bash(safe-cmd *) no da permiso para ejecutar safe-cmd && rm -rf /, ya que Claude detecta el encadenamiento de comandos.

Reglas de Read y Edit

Las reglas de lectura y edición de archivos siguen la especificación gitignore para los patrones de ruta:

| Patrón | Significado | Ejemplo | |---|---|---| | //ruta | Ruta absoluta desde la raíz del sistema | Read(//Users/dev/secrets/**) | | ~/ruta | Ruta desde el directorio home | Read(~/.ssh/*) | | /ruta | Ruta relativa a la raíz del proyecto | Edit(/src/**/*.ts) | | ruta o ./ruta | Ruta relativa al directorio actual | Read(./.env) |

El comodín * coincide con archivos en un solo directorio, mientras que ** coincide de forma recursiva entre directorios. Por ejemplo, Read(src/**) permite leer cualquier archivo bajo src/, sin importar la profundidad.

Un patrón como /Users/alice/file no es una ruta absoluta: se interpreta como relativa a la raíz del proyecto. Para rutas absolutas del sistema, se necesita el prefijo doble //Users/alice/file.

Reglas de WebFetch y MCP

Las herramientas web y MCP tienen sus propios formatos de especificador:

• WebFetch: usa el prefijo domain: para restringir por dominio. Por ejemplo, WebFetch(domain:github.com) permite peticiones solo a GitHub.

• MCP: usa el formato mcp__servidor__herramienta. El comodín mcp__servidor__* permite todas las herramientas de un servidor. La forma abreviada mcp__servidor sin nombre de herramienta también coincide con todas las herramientas del servidor.

{
  "permissions": {
    "allow": [
      "WebFetch(domain:docs.python.org)",
      "mcp__github__*"
    ],
    "deny": [
      "WebFetch(domain:evil.com)",
      "mcp__puppeteer__puppeteer_navigate"
    ]
  }
}

Reglas de subagentes

Los subagentes se controlan con la sintaxis Agent(nombre):

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

Esta regla impide que Claude lance el subagente Explore. Se puede combinar con allow para permitir solo ciertos subagentes.

Modos de permisos

Los modos de permisos establecen el comportamiento general de aprobación para toda la sesión. Se configuran con la propiedad defaultMode en settings.json o con el flag --permission-mode al iniciar Claude Code.

| Modo | Comportamiento | |---|---| | default | Pide aprobación en el primer uso de cada tipo de herramienta | | acceptEdits | Acepta automáticamente las ediciones de archivos durante la sesión | | plan | Claude puede analizar pero no modificar archivos ni ejecutar comandos | | dontAsk | Rechaza automáticamente cualquier herramienta que no esté preaprobada | | bypassPermissions | Omite todas las comprobaciones de permisos |

El modo plan resulta especialmente útil para sesiones de exploración donde se quiere que Claude investigue y proponga un plan sin riesgo de que ejecute cambios. El modo dontAsk es adecuado para entornos de CI/CD donde las herramientas permitidas se predefinen y cualquier otra debe rechazarse automáticamente.

El modo bypassPermissions desactiva todas las comprobaciones de seguridad. Solo debe usarse en entornos aislados como contenedores o máquinas virtuales donde Claude Code no pueda causar daños. Los administradores pueden desactivar este modo completamente mediante configuración managed.

Durante una sesión interactiva, el atajo Shift+Tab permite alternar entre los modos Normal, Plan y Auto-Accept sin salir de la conversación. El comando /permissions abre una interfaz que muestra todas las reglas activas y los archivos de configuración de los que provienen.

Configurar permisos en la práctica

Permisos a nivel de usuario

Los permisos de usuario se definen en ~/.claude/settings.json y aplican a todos los proyectos. Son adecuados para preferencias transversales como permitir siempre los comandos de consulta de versiones o bloquear comandos peligrosos a nivel global:

{
  "permissions": {
    "allow": [
      "Bash(* --version)",
      "Bash(* --help)"
    ],
    "deny": [
      "Bash(sudo *)",
      "Bash(rm -rf *)"
    ]
  }
}

Permisos a nivel de proyecto

Los permisos de proyecto se definen en .claude/settings.json dentro del repositorio y se comparten con el equipo mediante control de versiones. Son la forma más habitual de configurar permisos, ya que cada proyecto tiene sus propios comandos de build, test y despliegue:

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(npx jest *)",
      "Bash(git log *)",
      "Bash(git diff *)",
      "Bash(git status)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(git push --force *)"
    ],
    "defaultMode": "plan"
  }
}

Permisos locales

Los permisos locales en .claude/settings.local.json permiten ajustes personales que no se comparten con el equipo. Son útiles para conceder acceso a rutas específicas de tu máquina o habilitar herramientas que solo necesitas tú:

{
  "permissions": {
    "allow": [
      "Bash(docker compose *)",
      "Read(~/my-scripts/**)"
    ]
  }
}

Interacción con el sandbox

Claude Code incluye un sistema de sandbox que proporciona aislamiento a nivel de sistema operativo para los comandos Bash. El sandbox y los permisos son capas de seguridad complementarias:

• El sandbox restringe el acceso al sistema de archivos y la red para los comandos Bash y sus procesos hijo. Opera a nivel de sistema operativo, lo que lo hace resistente a inyecciones en el prompt.

• Los permisos controlan qué herramientas puede usar Claude Code y qué archivos o dominios puede acceder. Aplican a todas las herramientas, no solo a Bash.

El sandbox utiliza mecanismos nativos del sistema operativo: en macOS emplea el framework Seatbelt (sandbox-exec) de Apple, mientras que en Linux utiliza bubblewrap para el aislamiento de procesos y socat para el proxy de red. Su disponibilidad y comportamiento dependen de la plataforma, y en Linux es necesario instalar estas herramientas antes de activar el sandbox.

Cuando el sandbox está activo con autoAllowBashIfSandboxed habilitado, Claude puede ejecutar comandos Bash sin solicitar aprobación, ya que las acciones están confinadas dentro de los límites definidos por el sandbox:

{
  "sandbox": {
    "enabled": true,
    "autoAllowBashIfSandboxed": true,
    "filesystem": {
      "allowWrite": ["//tmp/build"]
    },
    "network": {
      "allowedDomains": ["github.com", "*.npmjs.org"]
    }
  }
}

La combinación de permisos y sandbox proporciona defensa en profundidad. Los permisos impiden que Claude intente acceder a recursos restringidos. El sandbox impide que los comandos Bash accedan a recursos fuera de los límites definidos, incluso si una inyección de prompt engañara al agente.

Extender permisos con hooks

Los hooks de Claude Code permiten registrar scripts personalizados que se ejecutan antes de cada llamada a herramienta (PreToolUse). El script recibe información sobre la herramienta y sus parámetros, y puede devolver una decisión de aprobar o denegar la operación.

Este mecanismo complementa las reglas estáticas de settings.json con lógica dinámica. Por ejemplo, un hook puede validar que las URLs de los comandos curl pertenezcan a dominios permitidos, algo que las reglas de patrón estático no pueden garantizar de forma fiable.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "python .claude/hooks/validate-bash.py"
          }
        ]
      }
    ]
  }
}

Los hooks no reemplazan los permisos, sino que añaden una capa adicional de validación que resulta útil para políticas de seguridad que requieren inspección del contenido de los comandos antes de su ejecución.