Configurar permisos

Sistema de permisos

Agregue un comentario cuando responda a un mensaje de permiso

• Enter: envía su respuesta con el comentario adjunto. Si deja el campo vacío, Claude Code envía la respuesta sin un comentario.
• Tab: cierra el campo sin responder. Claude Code mantiene el texto que escribió y aún lo envía si responde con esa opción.
• Shift+Tab: en un mensaje de archivo, como un mensaje de Edit o Write, cierra el campo igual que Tab. Antes de v2.1.235, presionar Shift+Tab dentro del campo en su lugar seleccionaba la opción que permite la acción para el resto de la sesión, por lo que Claude Code aprobaba la acción para el resto de la sesión y descartaba el comentario.

• Sí: Claude Code ejecuta la acción, luego envía su comentario a Claude después del resultado.
• No: Claude Code envía su comentario a Claude como la razón de la denegación, y Claude continúa trabajando. Si selecciona No sin un comentario en un mensaje de la conversación principal, Claude Code detiene el turno.

Administrar permisos

• Las reglas Allow permiten que Claude Code use la herramienta especificada sin aprobación manual.
• Las reglas Ask solicitan confirmación cada vez que Claude Code intenta usar la herramienta especificada.
• Las reglas Deny impiden que Claude Code use la herramienta especificada.

Modos de permisos

Sintaxis de reglas de permisos

Coincidir con todos los usos de una herramienta

Usar especificadores para control granular

Coincidir por parámetro de entrada

• El nombre del parámetro debe ser un campo directo de la entrada de la herramienta, como model en la herramienta Agent. Los campos anidados dentro de un objeto o matriz no son coincidentes
• Cada regla nombra un parámetro. Para controlar tanto model como isolation, escriba dos reglas, Agent(model:opus) y Agent(isolation:worktree), en lugar de combinarlas en una regla
• El valor admite * como un comodín que coincide con cualquier secuencia de caracteres, por lo que Agent(isolation:*) coincide con cualquier valor de aislamiento explícito. Sin * la coincidencia es exacta
• Un parámetro que el modelo omite nunca se coincide, por lo que Agent(model:*) no coincide con una llamada que deja model sin establecer
• El valor se compara con la entrada literal que Claude envía, antes de cualquier normalización. Agent(model:opus) coincide con el alias opus pero no con un ID de modelo completo
• Una regla de denegación Skill(skill:<name>) en su lugar coincide con la habilidad bajo cualquiera de sus nombres, como su alias o nombre para mostrar
• Ejecute con --verbose para ver los nombres y valores exactos de los parámetros en cada llamada de herramienta
• Se ignora el espacio en blanco alrededor de los dos puntos

Patrones de comodín

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

• El * representa cualquier texto que esté en su lugar. En Bash(git * main), representa el subcomando, por lo que Claude Code coincide con todos los subcomandos git y todas las opciones anteriores. Esto incluye -c, que hace que git ejecute un programa que usted nombre. En Bash(* --version), el * representa el programa, por lo que cualquier programa coincide.
• Un * al final, con un espacio antes, también coincide con el comando desnudo. Bash(ls *) coincide con ls, y Bash(git log *) coincide con git log. Esto se mantiene solo cuando el * final es el único comodín de la regla: Bash(* --help *) coincide con npm --help x pero no con npm --help.
• El espacio antes de un * final es parte de la regla. Bash(ls *) requiere un espacio después de ls, por lo que lsof no coincide. Bash(ls*) no tiene espacio, por lo que también coincide con lsof.

Comodines de nombre de herramienta

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

Reglas de permisos específicas de herramientas

Bash

Comandos compuestos

Envoltorios

Envoltorios Exec y acciones de find

• Envoltorios Exec: como watch, setsid, ionice y flock
• find: con una acción que ejecuta comandos, elimina archivos o escribe archivos, como -exec, -delete, -rm o -fprint, o con -files0-from, que toma de un archivo las rutas en las que buscar

Con qué no coincide una regla de Bash

Comandos de solo lectura

• Globs sin comillas para comandos con flags capaces de escribir: los comandos con flags capaces de escribir o ejecutar, como find, sort, sed y git, piden confirmación cuando hay un glob sin comillas, porque el glob podría expandirse a un flag como -delete.
• docker apuntando a otro daemon: las formas de solo lectura de docker piden confirmación cuando el comando lleva un flag que selecciona un daemon diferente, como -H, --context o --url y --connection de Podman.
• file con flags que abren rutas: file pide confirmación cuando pasa -m/--magic-file o -f/--files-from, porque esos flags hacen que file abra las rutas indicadas en el valor del flag.
• ps que podría imprimir variables de entorno: ps pide confirmación cuando uno de sus argumentos podría actuar como la opción e, como en ps auxe o ps aux -e, porque esa opción imprime las variables de entorno de los procesos. ps aux y ps -ef se ejecutan sin pedir confirmación. La verificación de las formas con guion como ps aux -e requiere Claude Code v2.1.290 o posterior.
• which con flags más allá de la búsqueda y la visualización: which pide confirmación cuando pasa un flag como -i/--read-alias o --read-functions. which node y which -a node se ejecutan sin pedir confirmación.
• Rutas de red en Windows: un comando cuyos argumentos incluyen una ruta de red (UNC), como \\server\share\file, pide confirmación porque acceder a una ruta de red puede enviar tus credenciales de Windows al host que nombra. La misma verificación se aplica a los comandos de la herramienta PowerShell.
• Escrituras en variables especiales del shell: un comando que establece, elimina o itera sobre ciertas variables especiales del shell, como PATH o IFS, pide confirmación incluso cuando el resto del comando es de solo lectura.
• Comandos que el análisis no puede procesar: cuando Claude Code no puede analizar completamente un comando, pide aprobación en lugar de tratarlo como de solo lectura. Los comandos de más de 10,000 caracteres siempre piden confirmación porque exceden lo que el análisis procesa.

• cd con git: pide confirmación cuando el cd cambia a un directorio diferente, ya que ejecutar git en un nuevo directorio puede ejecutar los hooks de ese directorio. Un cd cuyo destino se resuelve al directorio de trabajo actual no tiene efecto y no activa la solicitud.
• cd con una redirección: pide confirmación cuando Claude Code no puede determinar respecto a qué directorio se resuelve el destino de la redirección después de que se ejecuta el cd. Un comando cuyo único destino de redirección es /dev/null, como cd app; grep -r pattern . 2>/dev/null, no pide confirmación, porque /dev/null no depende del directorio de trabajo.

Redirecciones

• Redirecciones de salida: para > file, >> file o 2> file, la verificación cubre tus reglas Edit de permiso y negación, las rutas protegidas y los directorios de trabajo. Una regla como Bash(git commit *) permite el comando, no el destino. Un destino que comienza con ~ o contiene un carácter glob necesita tu aprobación.
• Redirecciones de entrada: para < file, la verificación cubre tus reglas Read de permiso y negación y los directorios de trabajo. Un destino fuera de los directorios de trabajo necesita tu aprobación a menos que una regla de permiso lo cubra. Un destino que contiene un patrón glob, o una ruta relativa que sigue a un cd en el mismo comando, necesita tu aprobación incluso cuando una regla de permiso lo cubre. Claude Code verifica los destinos de entrada en v2.1.257 y posteriores.

PowerShell

{
  "permissions": {
    "allow": [
      "PowerShell(Get-ChildItem *)",
      "PowerShell(git commit *)"
    ],
    "deny": [
      "PowerShell(Remove-Item *)"
    ]
  }
}

Read y Edit

Qué cubren las reglas Read y Edit

• Ruta de imagen: cuando pegas la ruta de una imagen o arrastras un archivo de imagen a tu prompt en la terminal y la regla coincide con esa ruta, Claude Code no adjunta la imagen. Si lo que pegaste no contiene ninguna otra imagen, la ruta permanece en tu prompt como texto.
• Directorio: el listado que recibe Claude omite los nombres de archivos y directorios con los que coincide la regla.

Las reglas Write(path), Glob(path) y Grep(path) no coinciden

• Write, NotebookEdit o la herramienta heredada MultiEdit: usa Edit(docs/**) en lugar de Write(docs/**).
• Glob o Grep: usa Read(docs/**) en lugar de Grep(docs/**). Como regla de solicitud, Read(docs/**) pide confirmación cuando Claude llama a Grep o Glob sobre una ruta que coincide, pero no cuando una búsqueda en un directorio de trabajo superior a ella devuelve archivos que coinciden.

Cómo coinciden los patrones de ruta

Dónde se ancla un patrón

• Edit(/docs/**): ediciones en <primary working directory>/docs/, no en /docs/ ni en <primary working directory>/.claude/docs/
• Read(~/.zshrc): lee el .zshrc de tu directorio home
• Edit(//tmp/scratch.txt): edita la ruta absoluta /tmp/scratch.txt
• Read(src/**): como regla de permiso, lee solo desde <current-directory>/src/; como regla de negación o solicitud, coincide con un directorio src a cualquier profundidad bajo el directorio actual

A qué profundidad coincide un patrón

• Reglas de permiso: Edit(src/**) coincide solo con <cwd>/src y los archivos que contiene. Para permitir un nombre de directorio a cualquier profundidad, escribe Edit(**/src/**).
• Reglas de negación y solicitud: Read(secrets/**) coincide con un directorio llamado secrets a cualquier profundidad bajo el directorio actual, por lo que la regla también se aplica a las copias anidadas.

<current-directory>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js

Caracteres especiales y negación con !

• Claude Code interpreta un patrón ! como relativo al directorio actual incluso cuando /, ~/ o // siguen al !, por lo que el patrón no puede alcanzar una regla anclada con uno de esos prefijos. Read(!~/notes/public/**) no excluye nada de Read(~/notes/**).
• Una exclusión no puede volver a habilitar un archivo dentro de un directorio que una regla bloquea por completo. Con Read(secrets/**) y Read(!secrets/public/**), Claude Code sigue bloqueando secrets/public junto con el resto de secrets.

Enlaces simbólicos

Cómo coinciden las reglas con una ruta que pasa por un enlace simbólico

• Reglas de permiso: se aplican solo cuando coinciden tanto la ruta solicitada como el archivo al que se resuelve. Una lectura a través de un enlace simbólico dentro de un directorio permitido que apunta fuera de él no coincide con la regla.
• Reglas de negación: se aplican cuando coincide la ruta solicitada o el archivo al que se resuelve. Un enlace simbólico que apunta a un archivo negado queda también negado. Por ejemplo, con Read(./project/**) permitido y Read(~/.ssh/**) negado, un enlace simbólico en ./project/key que apunta a ~/.ssh/id_rsa queda bloqueado: el destino no cumple la regla de permiso y coincide con la regla de negación.

Adjuntos a través de un enlace simbólico

• Menciones con @: un archivo o directorio que mencionas en tu prompt. Un archivo rechazado no deja nada en la conversación, y el listado de un directorio omite los nombres que cubre una regla.
• Imágenes pegadas: una imagen cuya ruta pegas o arrastras al prompt en la terminal
• Archivos modificados: un archivo que Claude Code vuelve a leer después de que cambia en el disco
• Contexto del IDE: la selección y el contexto de archivos abiertos que comparte un IDE conectado

Referenced <path> (not read: could not be examined)

Escrituras a través de un enlace simbólico

• Se resuelve fuera de los directorios de trabajo: cuando la ruta solicitada está dentro de tus directorios de trabajo y el archivo al que se resuelve no lo está, la escritura no se aprueba automáticamente en modo acceptEdits. En modo automático, a menos que una regla de permiso apruebe la escritura, se te pide confirmación en lugar de que decida el clasificador. La solicitud nombra la ruta a la que se resuelve la escritura.
• Se resuelve a una ruta protegida que la ruta solicitada no nombra: la tabla de rutas protegidas indica el resultado para cada modo de permisos, excepto que, donde la tabla envía la escritura al clasificador, esta escritura te pide confirmación en su lugar.

Rutas que no se pueden resolver o que cambian

Rutas de red

• Reglas de permiso: una regla no aprueba de antemano la lectura, incluida una regla para toda la herramienta, como Read
• Hooks PreToolUse: un hook que devuelve "allow" no omite la solicitud
• Modo automático: la solicitud te llega a ti, y el clasificador no decide sobre la lectura

• Windows: asigna el recurso compartido a una letra de unidad y pasa la unidad con --add-dir al iniciar Claude Code, como se describe en Directorios de trabajo. Para un recurso compartido asignado a Z:, ejecuta claude --add-dir Z:\ en PowerShell.
• macOS y Linux: monta el recurso compartido en una ruta local, como un directorio bajo /mnt o /Volumes, y lee los archivos desde allí, como se describe en El directorio de trabajo es una ruta de red

WebFetch

• WebFetch(domain:example.com) coincide solo con las solicitudes a example.com. Para cubrir también subdominios como api.example.com, agrega una regla WebFetch(domain:*.example.com)
• WebFetch(domain:*.example.com) coincide con cualquier subdominio a cualquier profundidad, como api.example.com o a.b.example.com, pero no con example.com en sí
• WebFetch(domain:*) coincide con todos los dominios. No es lo mismo que una regla WebFetch sin argumentos; consulta Permitir o negar todas las obtenciones

Permitir o negar todas las obtenciones

{
  "permissions": {
    "allow": ["WebFetch"]
  }
}

MCP

• mcp__puppeteer coincide con cualquier herramienta proporcionada por el servidor puppeteer
• mcp__puppeteer__* usa sintaxis de comodín y también coincide con todas las herramientas del servidor puppeteer
• mcp__puppeteer__puppeteer_navigate coincide con la herramienta puppeteer_navigate proporcionada por el servidor puppeteer

• Nombres con caracteres como . o espacios: esos caracteres se convierten en _, así que para un servidor que configuraste como my.server, escribe mcp__my_server__*
• Servidores que proporciona un plugin: <server> toma la forma con ámbito de plugin, así que para el servidor database-tools de un plugin llamado my-plugin, escribe mcp__plugin_my-plugin_database-tools__*
• Un <server> que contiene __ o termina en _: escribe la forma con comodín, mcp__<server>__*, con el nombre completo. Para un servidor llamado reports__v2, escribe mcp__reports__v2__*. El mcp__reports__v2 sin comodín y el más corto mcp__reports no coinciden con sus herramientas como reglas de permiso, porque Claude Code interpreta ambos como reglas para un servidor llamado reports. Sin embargo, como regla de negación o solicitud, cada uno de esos dos nombres también cubre todas las herramientas del servidor reports__v2. Para cubrir solo un servidor llamado reports, escribe una regla por herramienta con la forma mcp__reports__<tool>, o cambia el nombre de uno de los servidores.

Agent (subagentes)

• Agent(Explore) coincide con el subagente Explore
• Agent(Plan) coincide con el subagente Plan
• Agent(my-custom-agent) coincide con un subagente personalizado llamado my-custom-agent

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

Cd

Extender permisos con hooks

Precedencia entre reglas, hooks y mods

• Una llamada que una regla de negación rechaza sigue rechazada.
• Una llamada para la que una regla de solicitud pediría confirmación te sigue pidiendo confirmación.
• Una llamada para la que un hook PreToolUse o permissions.blockReadsOutsideWorkingDirectories pediría confirmación te sigue pidiendo confirmación.
• Una llamada que un hook PreToolUse bloqueó sigue bloqueada, sin importar de qué archivo de configuración provenga el hook.
• Una llamada sobre la que se consultaría a tu --permission-prompt-tool o a tu callback canUseTool del Agent SDK se sigue sometiendo a esa herramienta o callback.

• Modo automático: una llamada que el mod aprueba se ejecuta sin una verificación del clasificador, excepto donde el mod no puede omitir tu herramienta de solicitud de permisos o el callback de permisos del Agent SDK. Ahí el clasificador verifica la llamada primero.
• Modo plan: el mod no puede aprobar una llamada que no sea de solo lectura, como una edición de archivo o un comando de shell que escribe.
• Modo dontAsk: el mod puede aprobar una llamada que solo el modo denegaría.

Aprobaciones de hooks en modo plan

Directorios de trabajo

• Durante el inicio: usa el argumento de CLI --add-dir <path>
• Durante la sesión: usa el comando /add-dir
• Configuración persistente: agrégalo a additionalDirectories en los archivos de configuración

Bloquear las lecturas y escrituras de las herramientas de archivos fuera de los directorios de trabajo

• permissions.blockReadsOutsideWorkingDirectories: las herramientas de archivos rechazan las lecturas allí, salvo los archivos que el propio Claude Code necesita. En modo automático, Claude Code ofrece activarlo la primera vez que Claude lee fuera de los directorios de trabajo.
• permissions.blockWritesOutsideWorkingDirectories: las herramientas Write, Edit y NotebookEdit rechazan las escrituras allí, salvo algunos de los archivos propios de Claude Code, como los archivos de plan. La clave no limita los comandos de shell, las herramientas MCP ni los programas que ejecutan los hooks, así que usa sandboxing para limitar dónde escriben los comandos de shell. Requiere Claude Code v2.1.314 o posterior.

Mover la sesión a otro directorio

• Su configuración de proyecto, incluidas sus reglas de permisos y sus hooks
• Sus servidores de .mcp.json, sujetos a la misma aprobación de servidores que al inicio, y los servidores MCP de alcance local que registraste en él
• Los plugins que habilita su configuración, sus skills y sus subagentes
• Sus valores de env, aplicados sobre las variables de entorno de la configuración del directorio anterior, que siguen vigentes

Los directorios adicionales otorgan acceso a archivos, no configuración

Desde dónde se cargan los estilos de salida, los hooks y la configuración local

• Configuración a nivel de usuario: coloca archivos en ~/.claude/agents/, ~/.claude/output-styles/ o ~/.claude/settings.json para que estén disponibles en todos los proyectos
• Plugins: empaqueta y distribuye la configuración como un plugin que los equipos pueden instalar
• Inicia desde el directorio de configuración: ejecuta Claude Code desde el directorio que contiene la configuración de .claude/ que quieres

Cómo interactúan los permisos con el sandboxing

• Permisos controlan qué herramientas puede usar Claude Code y qué archivos o dominios puede acceder. Se aplican a Bash, Read, Edit, WebFetch, MCP y todas las demás herramientas, excepto que una regla de negación o ask no puede bloquear EndConversation mientras cualquier otra herramienta permanezca.
• Sandboxing proporciona aplicación a nivel del SO que restringe el acceso del sistema de archivos y red de los comandos Bash, PowerShell y Monitor y sus procesos secundarios.

• Las reglas ask con alcance de contenido como Bash(git push *) aún fuerzan un aviso
• Otros comandos en el sandbox también pueden pasar por el flujo de permisos regular, como se describe en modo Auto-allow

Configuración administrada

Precedencia de configuración

Reglas allow del proyecto y confianza del espacio de trabajo

• En un repositorio, Claude Code asocia la confianza a la raíz del repositorio de git, por lo que la confianza cubre todo el repositorio excepto cualquier repositorio de git anidado dentro de él, como un submódulo. En un worktree, utiliza la raíz del checkout principal, como lo hace para las reglas guardadas.
• Fuera de un repositorio, Claude Code asocia la confianza al directorio desde el que lo iniciaste, y la confianza cubre cualquier subdirectorio de ese directorio excepto un repositorio de git anidado dentro de él, como un clon. Cada subdirectorio cubierto cuenta entonces como una carpeta cuyo padre marcaste como confiable.
• Cuando inicias en tu directorio home, Claude Code mantiene la confianza solo para la sesión actual y no la escribe en el disco; consulta la nota sobre salvaguardas adicionales.

Cuándo tu archivo de configuración local necesita confianza

• En tu directorio de configuración personal: Claude Code aplica el .claude/settings.local.json de esa carpeta de inmediato sin ejecutar git. Tu directorio de configuración personal es tu directorio home, o un directorio cuyo subdirectorio .claude has establecido como CLAUDE_CONFIG_DIR. Si ese directorio CLAUDE_CONFIG_DIR se encuentra dentro de un repositorio de git y Claude Code mantiene tu configuración local en la raíz del repositorio en su lugar, retiene las reglas sin aplicarlas, como en cualquier otro lugar.
• En cualquier otro lugar: Claude Code retiene las reglas del archivo sin aplicarlas, como las de la configuración del proyecto. Una vez que la verificación se ha ejecutado, Claude Code aplica las reglas de un archivo sin rastrear, o de un archivo en un directorio fuera de cualquier repositorio de git, aunque no hayas confiado en esa carpeta exacta.

Lo que se ejecuta antes de confiar en una carpeta

• Pasa --setting-sources user, o establece el settingSources del SDK sin la configuración del proyecto, para que Claude Code no lea ni los archivos de configuración del proyecto ni su .mcp.json
• Inicia con --bare para que Claude Code no lea hooks, skills, comandos personalizados, subagentes, plugins ni servidores de .mcp.json del proyecto. El bloque env del proyecto y auxiliares como awsAuthRefresh en sus archivos de configuración aún se aplican, y Claude Code lee apiKeyHelper solo desde --settings
• Pasa --settings '{"disableAllHooks": true}' para desactivar los hooks en esa ejecución. Establecerlo solo en tu configuración de usuario no es suficiente, porque la configuración del proyecto del repositorio tiene prioridad sobre la tuya y puede volver a establecerlo en false
• Agrega una entrada disabledMcpjsonServers para rechazar un servidor de .mcp.json por nombre en todos los tipos de sesión

Configuraciones de ejemplo

Ver también

• Todos los ajustes: cada clave de configuración, incluyendo las claves de permisos
• Configurar modo auto: indique al clasificador del modo auto qué infraestructura confía su organización
• Sandboxing: aislamiento del sistema de archivos y red a nivel del SO para comandos Bash
• Autenticación: configure el acceso de usuario a Claude Code
• Seguridad: salvaguardas de seguridad y mejores prácticas
• Hooks: automatice flujos de trabajo y extienda la evaluación de permisos