Las reglas de permisos en Claude Code son ejecutadas por el entorno de ejecución del agente, no por el modelo en sí. Esa distinción importa más de lo que parece. Las instrucciones en tu prompt o CLAUDE.md determinan qué intenta hacer Claude, pero no cambian lo que Claude Code realmente permite, como aclara la documentación oficial de permisos. Para otorgar o revocar acceso usas /permissions, los archivos de configuración descritos a continuación, un modo de permisos o un hook PreToolUse. Este artículo recorre cada capa: elegir un modo, entender la precedencia, escribir un archivo de política que funcione, probarlo y saber dónde el sistema completo no puede ayudarte.
Elige un Modo de Permisos
El modo que elijas establece la línea base para todo lo demás. Hay cinco.
Manual detiene Claude Code antes de la mayoría de ediciones de archivos, comandos de shell y llamadas de red. Tú confirmas cada una. Lento, pero nada te sorprende.
Auto otorga aprobación a un modelo clasificador que revisa las acciones en tu nombre. En planes Pro, Max y Team este es el modo inicial incorporado, según la documentación de modos de permisos. El clasificador tiene sus propias reglas sobre qué acciones revisa y cuáles omite, así que auto no es lo mismo que "aprobar todo".
Accept Edits aprueba automáticamente operaciones de archivos pero aún solicita confirmación para comandos de shell. Un punto medio razonable para trabajo en solitario en una base de código que posees y comprendes.
Plan bloquea ediciones de archivos y escrituras de shell completamente. Claude puede leer, razonar y generar un plan, pero no puede actuar. Bueno para revisiones en etapas tempranas cuando quieres ver el enfoque antes de que nada cambie.
dontAsk niega automáticamente cualquier herramienta que no esté en tu lista de permitidas explícita. Sin solicitud, solo una negación silenciosa. Este es el modo correcto para canalizaciones CI/CD donde nadie está monitoreando.
bypassPermissions omite todas las verificaciones. Claude ejecuta lo que quiera. Útil en entornos descartables aislados; no algo para ejecutar contra un repositorio de producción.
Para fijar el modo inicial en VS Code, establece claudeCode.initialPermissionMode en tus configuraciones de usuario a default, manual, acceptEdits, plan o bypassPermissions. Nota: la configuración no acepta auto. Para comenzar en Auto, déjalo sin establecer y selecciónalo una vez desde el indicador de modo; la extensión recuerda esa opción para conversaciones posteriores.
Para sesiones de terminal, establece permissions.defaultMode en ~/.claude/settings.json o en configuración gestionada. Ese valor se aplica en planes Pro, Max y Team cuando la obtención de banderas de características está disponible.
Un caso límite que vale la pena conocer: si tu organización ha establecido una herramienta conectora claude.ai en ask, las reglas de permitidas para esa herramienta no surten efecto ni en modos auto ni bypassPermissions. Claude Code solicita en cada llamada. En modo dontAsk, deniega la llamada en su lugar.
Cómo Funciona la Precedencia de Reglas y Configuración
Cinco capas, evaluadas de arriba a abajo. Una capa superior gana.
- Configuración gestionada (
managed-settings.json): implementada por TI, no se puede anular. Si tu organización bloquea SSH aquí, eso es definitivo. - Configuración local (
.claude/settings.local.json): por máquina, ignorada por git de forma predeterminada. Las anulaciones personales o sensibles a la seguridad van aquí. - Configuración del proyecto (
.claude/settings.json): confirmada en el repositorio. Compartida en todo el equipo para ese proyecto. - Configuración del usuario (
~/.claude/settings.json): valores predeterminados globales, aplicados a cada proyecto a menos que una capa superior los anule. - Indicadores de sesión:
--dangerously-skip-permissionsy argumentos de tiempo de ejecución similares.
La documentación de configuración del administrador añade dos controles de bloqueo que vale la pena conocer: allowManagedPermissionRulesOnly (hace que la configuración gestionada sea la única fuente de reglas de permisos, ignorando archivos de usuario y proyecto) y permissions.disableBypassPermissionsMode (elimina la opción de bypass por completo). Si ejecutas una agencia con contratistas accediendo a repositorios de clientes, esas dos configuraciones juntas te dan un techo máximo que ningún desarrollador puede deshacer silenciosamente.
Cada capa acepta tres tipos de regla: allow, deny y ask. Dentro de una capa, deny gana sobre allow. Se admite coincidencia de patrones tipo shell (por ejemplo Bash(git *)), pero sé preciso: un patrón que parece hermético en pruebas a menudo tiene grietas cuando las cadenas de comando reales difieren de lo que esperabas.
Una cosa que los documentos señalan explícitamente: denegar WebFetch bloquea la herramienta fetch de Claude, pero si Bash está permitido, curl y wget aún pueden alcanzar cualquier URL. El aislamiento (vía /sandbox) cierra esa brecha con una lista de permitidos de dominio reforzada a nivel del SO. Los permisos y el aislamiento cubren capas diferentes y generalmente quieres ambos para cualquier cosa seria.
Un Ejemplo de Política de Repositorio de Cliente
Aquí hay un .claude/settings.json ilustrativo para un proyecto cliente donde el equipo puede ejecutar compilaciones y leer la base de datos pero no debería tocar scripts de implementación o secretos. Esta es una estructura representativa, no una política de producción lista para copiar y pegar.
{
"permissions": {
"defaultMode": "auto",
"allow": [
"Bash(npm run build)",
"Bash(npm run test*)",
"Bash(git log*)",
"Bash(git diff*)",
"Bash(git status)",
"Read(**)"
],
"deny": [
"Bash(rm -rf*)",
"Bash(git push*)",
"Bash(kubectl*)",
"Edit(.env*)",
"Edit(deploy/**)"
]
}
}
Junto con esto, un ~/.claude/settings.json en la máquina de cada desarrollador maneja la confianza global personal, como permitir curl para uso general. Las credenciales sensibles o rutas específicas de la máquina van en .claude/settings.local.json, que git no va a confirmar.
Para el lado CLAUDE.md, donde estableces convenciones y contexto del proyecto en lugar de reglas de ejecución, la guía de agencia para CLAUDE.md cubre el flujo de trabajo de autoría en detalle.
Prueba la Política con Comandos Realistas
Coloca la política en un repositorio desechable (un git init desnudo en un directorio temporal funciona bien), luego ejecuta un puñado de comandos que ejerciten las tres categorías de reglas. El objetivo es ver cuáles generan avisos, cuáles se ejecutan silenciosamente y cuáles se deniegan sin un aviso.
Una secuencia de prueba representativa:
npm run build(debería aprobarse automáticamente, está en la lista de permitidos)git diff HEAD~1(debería aprobarse automáticamente)git push origin main(debería denegarse)rm -rf node_modules(debería denegarse)- Editar un archivo dentro de
deploy/(debería denegarse) - Editar
src/index.js(sin regla de denegación, sin permitir explícitamente: el comportamiento depende del modo) - Una llamada
curla una URL externa (prueba cómo interactúan las reglas de permitirBashy el aislamiento)
Observa específicamente el caso 6. En modo auto el clasificador lo revisa. En modo dontAsk se deniega silenciosamente porque no está en la lista de permitidos. Esa diferencia sorprenderá a los desarrolladores que prueben en un modo e implementen en otro.
Si estás añadiendo automatización a nivel de evento encima de esto (ejecutar linters al guardar archivos, disparar notificaciones en llamadas de herramienta específicas), eso es más una cuestión de hooks que de permisos. La guía de hooks cubre PreToolUse y PostToolUse en profundidad.
Para equipos que necesitan ejecuciones desatendidas o integración de CI, considera usar la configuración de agencia de Claude Code para obtener la línea base de configuración correcta desde el principio.
Configuración administrada y trabajos desatendidos
Cuando no hay un humano presente para hacer clic en "aprobar", el modelo de permisos debe estar completamente predeclarado. Eso apunta al modo dontAsk con una lista de permisos explícita en la configuración administrada.
Los documentos de configuración del administrador te dan permissions.defaultMode como la clave administrada para esto. Establécelo en dontAsk, luego enumera exactamente lo que el trabajo necesita en permissions.allow. Lo que no esté listado se niega silenciosamente. Eso es lo que quieres en una canalización.
Algunas cosas que los documentos oficiales señalan para escenarios de equipo de agentes (donde una sesión de líder genera compañeros de equipo):
- Los compañeros de equipo comienzan con la configuración de permisos del líder. Si el líder se ejecuta con
--dangerously-skip-permissions, todos los compañeros de equipo también lo hacen. - Puedes cambiar modos de compañeros de equipo individuales después de generarlos, pero no en el momento de la generación.
- Los avisos de permiso de compañeros de equipo aparecen en la sesión del líder. Las aprobaciones de planes son la excepción diseñada: el líder las otorga sin un aviso separado.
Managed Agents (el servicio de orquestación a nivel de plataforma) está actualmente en beta según la descripción general de Managed Agents. No arquitectures canalizaciones de producción alrededor de características en beta sin una alternativa.
Para el indicador permissions.disableAutoMode: configurarlo elimina el modo automático como opción para los desarrolladores en esa organización. Útil cuando quieres que todas las sesiones permanezcan en un modo donde un humano o una lista de permisos explícita esté tomando cada decisión, en lugar de un clasificador.
Lo que los permisos no pueden garantizar
Respuesta honesta: bastante.
Las reglas de negación con patrón de shell no son un límite de seguridad. Coinciden con la cadena de comando que Claude Code construye, pero una inyección de aviso suficientemente creativa o una reformulación inteligente de un comando shell pueden producir cadenas que tus patrones no capten. La documentación de permisos es explícita: las reglas de negación y el aislamiento cubren capas diferentes. Necesitas ambas, e incluso entonces estás reduciendo riesgo, no eliminándolo.
El modo bypassPermissions no hace que el código permitido sea inofensivo. Si Claude ejecuta código que contiene un error o hace algo inesperado, omitir las comprobaciones de permisos significa que no había una puerta entre "Claude decidió hacerlo" y "sucedió".
Los permisos tampoco validan lo que hay dentro del código que Claude escribe o ejecuta. Una dependencia que instala, un script que ejecuta, el contenido de un archivo que crea: nada de eso es inspeccionado por el sistema de permisos. Esa es una preocupación separada, más cerca de la higiene de la cadena de suministro que de la política en tiempo de ejecución.
Y el modelo en sí no es la capa de cumplimiento. Puedes escribir instrucciones en CLAUDE.md que digan "nunca toques secretos de producción". Esas instrucciones moldean la intención de Claude. No previenen que una regla de permisos mal configurada lo permita de todas formas. El tiempo de ejecución es la capa de cumplimiento. Los archivos de configuración son cómo configuras el tiempo de ejecución. Tratalos en consecuencia.
FAQ
¿Se sincronizan automáticamente los ajustes de permisos entre máquinas?
No. Los ajustes de usuario (~/.claude/settings.json) son locales para cada máquina. Los ajustes del proyecto (.claude/settings.json) se sincronizan a través de git. Los ajustes administrados se distribuyen por tu infraestructura de TI. No hay sincronización integrada para archivos a nivel de usuario; cada desarrollador necesita configurar los suyos propios.
¿Pueden los desarrolladores anular los ajustes administrados?
Solo dentro de los límites que los ajustes administrados permiten. Si allowManagedPermissionRulesOnly está establecido, los ajustes de permisos de usuario y proyecto se ignoran completamente. Sin esa bandera, los ajustes de usuario y proyecto pueden agregar reglas de permisos, pero no pueden anular una negación administrada.
¿Qué sucede con los avisos de permisos en entornos sin interfaz o CI?
En modo dontAsk, lo que no esté en la lista de permisos se niega silenciosamente. No aparece ningún aviso porque no hay terminal para mostrarlo. Eso es por diseño. En modo auto en un entorno sin interfaz, el clasificador aún se ejecuta, pero si no puede resolver un aviso (sin TTY), el comportamiento depende de la configuración del ejecutor. Usa dontAsk con una lista de permisos explícita para trabajos desatendidos.
¿El modo de permisos se aplica a las herramientas MCP de la misma manera que a las herramientas integradas?
Mayormente, pero con diferencias. Las herramientas MCP obtenidas directamente por Claude Code aparecen como mcp__claude_ai_<server>__<tool>. Las reglas de permitir y denegar pueden dirigirse a ellas por ese nombre. Las herramientas de conectores que tu organización ha configurado para preguntar siempre generan un aviso, independientemente del modo, con la excepción del modo dontAsk, donde se deniegan en su lugar.
¿Es seguro confirmar `.claude/settings.json` en un repositorio público?
El archivo en sí es solo JSON con nombres de herramientas y patrones, sin secretos. Pero una lista pública de permitidos le dice a cualquiera que lea tu repositorio exactamente qué operaciones ejecutará Claude Code sin preguntar. Para proyectos de código abierto probablemente está bien. Para cualquier cosa propietaria, revisa qué estás confirmando. Los secretos y las claves API nunca deben aparecer en ningún archivo de configuración; pertenecen a variables de entorno fuera de la configuración de Claude Code.
Lo más importante que debes tener presente: las reglas de denegación y el aislamiento resuelven problemas diferentes, y ninguno sustituye al otro. Configura ambos si ejecutas Claude Code en cualquier entorno donde el costo de un error es real.