SpyBara
Go Premium

permissions.md 2026-11-07 23:58 UTC to 2026-11-08 22:58 UTC

No changes for this document in this history range.

2026
Mon 2 23:57 Wed 4 23:59 Fri 6 23:01 Mon 9 23:02 Tue 10 21:57

Configurar permisos

Controla a qué puede acceder Claude Code y qué puede hacer con reglas de permisos granulares, modos y políticas administradas.

Claude Code admite permisos granulares para que pueda especificar exactamente qué puede hacer el agente y qué no puede hacer. La configuración de permisos se puede registrar en el control de versiones y distribuir a todos los desarrolladores de su organización, así como personalizarse por desarrolladores individuales.

Sistema de permisos

Claude Code utiliza un sistema de permisos escalonado para equilibrar potencia y seguridad. La tabla muestra, para cada tipo de herramienta, si el modo Manual solicita aprobación antes de que se ejecute la acción. Los otros modos de permisos cambian cuál de estos le solicita; en modo automático un clasificador revisa las acciones en lugar de usted, y cómo el clasificador evalúa las acciones enumera cuáles ve.

Tipo de herramienta Ejemplo Se requiere aprobación Comportamiento de "Sí, no preguntar de nuevo"
Solo lectura Lecturas de archivos, Grep No, dentro del directorio de trabajo y directorios adicionales N/A
Comandos Bash Ejecución de shell Sí, excepto un conjunto integrado de comandos de solo lectura Permanentemente por repositorio y comando
Modificación de archivos Editar/escribir archivos Sí Hasta el final de la sesión
Obtención web WebFetch Sí, excepto un conjunto integrado de dominios de documentación preaprobados Permanentemente por repositorio y dominio
Búsqueda web WebSearch Sí Permanentemente por repositorio

Una solicitud de permiso muestra lo que Claude está a punto de hacer, seguido de tus opciones. Este ejemplo es la solicitud para un comando Bash, de una sesión en modo Manual:

Una solicitud de permiso de Claude Code titulada Bash command. Debajo de un consejo sobre el modo automático, muestra la descripción 'Run the test suite', el comando npm test y la línea 'This command requires approval', y luego pregunta 'Do you want to proceed?' con cuatro opciones: Yes; Yes, and don't ask again for: npm test *; Yes, and switch to auto mode; y No. Un pie enumera dos teclas: Esc para cancelar y Tab para modificar.

La tercera opción, Sí, y cambiar al modo automático, no aparece en todas las solicitudes.

Cuando elige "Sí, no preguntar de nuevo" y la aprobación se guarda permanentemente, como para un comando Bash o un dominio WebFetch, Claude Code guarda la regla en .claude/settings.local.json en la raíz del repositorio de git, resuelto a través de worktrees al checkout principal. La regla se aplica a futuras sesiones en cualquier lugar de ese repositorio, incluidas las sesiones iniciadas en subdirectorios y en worktrees. Una aprobación de modificación de archivo no se guarda en el archivo: como muestra la tabla, dura hasta que termina la sesión. En algunos casos, como fuera de un repositorio de git o en Windows, Claude Code no utiliza la raíz del repositorio; Dónde Claude Code busca cada archivo enumera esos casos y dónde guarda la regla en su lugar.

A veces una solicitud de permiso ofrece solo una aprobación única, sin opción de "no preguntar de nuevo" y sin opción de permitir la acción para el resto de la sesión. Claude Code ofrece esas opciones solo cuando la solicitud puede mostrarte todo lo que permitirían, por lo que una regla que guardes desde una solicitud cubre solo lo que nombraba su opción. Cuando una solicitud ofrece solo la aprobación única, aprueba la acción una vez, o agrega la regla tú mismo en /permissions. Para dejar de recibir solicitudes para un comando que comienza con un exec wrapper como watch, o para un comando find con una acción como -delete, consulta Exec wrappers y acciones de find.

Agregue un comentario cuando responda a un mensaje de permiso

Puede adjuntar una nota a Claude cuando aprueba o deniega una única acción. En la mayoría de los mensajes de permiso, incluidos los mensajes de Bash, PowerShell, archivo y herramienta MCP, muévase a Sí o No y presione Tab para abrir un campo de comentario en esa opción. Los mensajes de WebFetch y navegador no ofrecen el campo. Las opciones que permiten la acción para el resto de la sesión o guardan una regla tampoco toman una.

Con el campo abierto, escriba el comentario y luego presione una de estas teclas:

  • 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.

Claude Code entrega el comentario de manera diferente según cómo haya respondido:

  • 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

Puede ver y administrar los permisos de herramientas de Claude Code con /permissions. Esta interfaz de usuario enumera todas las reglas de permisos y el archivo settings.json del que se obtienen. Puede abrir esta interfaz mientras Claude está trabajando: cuando agrega o elimina una regla, Claude Code aplica el cambio a partir de la siguiente llamada de herramienta de Claude en el mismo turno. Antes de v2.1.234, Claude Code ponía en cola el comando hasta que el turno finalizaba.

  • 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.

Las reglas se evalúan en orden: deny, luego ask, luego allow. La primera coincidencia en ese orden determina el resultado, y la especificidad de la regla no cambia el orden.

Una regla deny amplia como Bash(aws *) bloquea cada llamada coincidente, incluidas las llamadas que también coinciden con una regla allow más específica como Bash(aws s3 ls). Una regla allow no puede crear una excepción dentro de una regla deny. La misma precedencia se aplica entre ask y allow: una regla ask coincidente solicita confirmación incluso cuando una regla allow más específica también coincide con la misma llamada.

Las reglas deny se comportan de manera diferente dependiendo de si nombran una herramienta o delimitan un patrón dentro de una. Un nombre de herramienta simple como Bash elimina la herramienta del contexto de Claude por completo, por lo que Claude nunca la ve. Si agrega tal regla a mitad de sesión, Claude no puede llamar a la herramienta desde su siguiente llamada de herramienta en adelante; Denegar una herramienta completa cubre lo que sucede con una definición que Claude ya ha visto. Una regla delimitada como Bash(rm *) deja la herramienta disponible y bloquea las llamadas coincidentes cuando Claude intenta usarlas.

La eliminación de nombre simple se aplica a todas las herramientas excepto EndConversation: una regla deny no puede eliminarla mientras permanezca cualquier otra herramienta, y una regla ask nunca solicita confirmación para ella.

[!NOTE]

Las reglas de permisos se aplican mediante Claude Code, no por el modelo. Las instrucciones en su prompt o CLAUDE.md determinan lo que Claude intenta hacer, pero no cambian lo que Claude Code permite. Para otorgar o revocar acceso, use /permissions, las reglas descritas aquí, un modo de permisos, o un hook PreToolUse.

Cuando el modo automático está disponible para su sesión, la interfaz de usuario también incluye las reglas del clasificador de modo automático. Seleccione la pestaña Auto mode para verlas.

Modos de permisos

Claude Code admite varios modos de permisos que controlan cómo se aprueban las llamadas a herramientas. Consulta Modos de permisos para saber cuándo usar cada uno. Para cambiar el modo de permisos predeterminado de las sesiones nuevas, establece defaultMode en tus archivos de configuración. En qué modo comienza una sesión cubre el valor predeterminado integrado para cada plan y lo que lee la extensión de VS Code.

Modo Descripción
default Solicita permiso en el primer uso de cada herramienta. Etiquetado como Manual en la CLI, en las extensiones de VS Code y JetBrains, y en la aplicación de escritorio, y Claude Code acepta manual como un alias
acceptEdits Acepta automáticamente ediciones de archivos y comandos comunes del sistema de archivos como mkdir, touch, mv y cp para rutas en el directorio de trabajo o additionalDirectories
plan Claude lee archivos y ejecuta comandos de shell de solo lectura para explorar pero no edita sus archivos de origen; con modo automático disponible, los comandos aprobados por clasificador también se ejecutan. Etiquetado como Plan en la CLI y en la extensión de VS Code
auto Se ejecuta sin avisos rutinarios; antes de que se ejecuten acciones como comandos de shell y solicitudes de red, un clasificador en segundo plano verifica que se alineen con su solicitud
dontAsk Deniega automáticamente cada llamada que de otro modo pediría permiso, aunque un mod que instalaste aún puede aprobar algunas de esas llamadas. Las lecturas de archivos en tus directorios de trabajo y otras acciones que no necesitan aprobación aún se ejecutan, al igual que las herramientas preaprobadas a través de /permissions o reglas permissions.allow. AskUserQuestion, las herramientas MCP marcadas con requiresUserInteraction, las lecturas desde rutas de red y las herramientas de conector que tu organización configuró en ask en sesiones donde ese ajuste llega a Claude Code se deniegan incluso si las has permitido
bypassPermissions Omite avisos de permisos, excepto para las acciones que ningún modo auto-aprueba

[!WARNING]

En modo bypassPermissions, Claude Code omite avisos de permisos, incluyendo escrituras en rutas protegidas como .git y .claude. Las salvaguardas de mensajería entre sesiones aún se aplican. Use este modo solo en entornos aislados como contenedores o máquinas virtuales donde Claude Code no pueda causar daño.

Para evitar que se use el modo bypassPermissions o auto, establezca permissions.disableBypassPermissionsMode o permissions.disableAutoMode en "disable" en cualquier archivo de configuración. Estos son más útiles en configuración administrada donde no pueden ser anulados.

Sintaxis de reglas de permisos

Las reglas de permisos siguen el formato Tool o Tool(specifier). Los paréntesis dentro del especificador son literales, por lo que un comando o ruta que los contiene no necesita escape.

Coincidir con todos los usos de una herramienta

Para coincidir con todos los usos de una herramienta, use solo el nombre de la herramienta sin paréntesis:

Regla Efecto
Bash Coincide con todos los comandos Bash
WebFetch Coincide con todas las solicitudes de obtención web
Read Coincide con todas las lecturas de archivos

Bash(*) es equivalente a Bash y coincide con todos los comandos Bash. Como regla de denegación, ambas formas eliminan la herramienta del contexto de Claude.

La etiqueta mostrada para una herramienta en la transcripción y el diálogo de permisos puede diferir de su nombre canónico. Por ejemplo, la herramienta etiquetada como Stop Task en la transcripción tiene el nombre canónico TaskStop. Las reglas de permisos y los matchers de hooks no coinciden con la etiqueta, por lo que una regla escrita como Stop Task no coincide. Para reglas de denegación y solicitud, una advertencia de inicio lo indica. Usa los nombres canónicos enumerados en la referencia de herramientas.

Usar especificadores para control granular

Agregue un especificador entre paréntesis para coincidir con usos específicos de herramientas:

Regla Efecto
Bash(npm run build) Coincide con el comando exacto npm run build
Read(./.env) Coincide con la lectura del archivo .env en el directorio actual
WebFetch(domain:example.com) Coincide con solicitudes de obtención a example.com

Coincidir por parámetro de entrada

Las reglas de denegación y solicitud pueden coincidir con un parámetro de entrada de nivel superior en cualquier herramienta integrada con Tool(param:value).

Para coincidir con un parámetro en una herramienta MCP, pase una regla de denegación con --disallowedTools. Cuando Claude Code carga un archivo de configuración, omite cualquier regla mcp__ que tenga paréntesis. Claude Code enumera la regla omitida en el diálogo de configuración inválida cuando comienza una sesión interactiva, y en la salida de claude doctor.

Una regla de parámetro coincide cuando Claude llama a la herramienta con ese parámetro establecido en ese valor exacto. Una regla de permiso para un valor de parámetro no establecería que la llamada sea segura en general, por lo que las reglas de permiso continúan usando la sintaxis de especificador propia de cada herramienta. Esto funciona para cualquier parámetro escalar que acepte la herramienta:

Regla Coincide
Agent(model:opus) Llamadas de Agent que solicitan el nivel de modelo Opus
Agent(isolation:worktree) Llamadas de Agent que solicitan un git worktree
Bash(run_in_background:true) Llamadas de Bash que se ejecutan en segundo plano

La coincidencia de parámetros sigue estas reglas:

  • 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

No puede coincidir con el campo de contenido principal de una herramienta de esta manera: command para Bash y PowerShell, file_path para Read, Edit y Write, path para Grep y Glob, notebook_path para NotebookEdit, y url para WebFetch. Una regla como Bash(command:rm *) sería eludible por un comando compuesto, por lo que Claude Code la ignora y emite una advertencia de inicio. Use Bash(rm *), Read(./path), o WebFetch(domain:host) en su lugar.

Patrones de comodín

Un * en una regla de Bash coincide con cualquier texto, incluidos espacios, por lo que una regla cubre una familia de comandos. Una regla sin * coincide con un comando exacto.

[!WARNING]

Ponga el * después del subcomando. En git log --oneline main, git es el programa y log es el subcomando, la palabra que determina qué hace el programa. Claude Code coincide con todo lo anterior al primer * tal como está escrito, por lo que esas palabras son lo que limita la regla: Bash(git log *) permite solo comandos git log, y Bash(git *) permite todos los comandos git. Claude Code advierte al inicio sobre una regla de permiso con un * antes del subcomando, como Bash(git * main).

Escriba el comando que desea que Claude ejecute sin preguntar, y reemplace las partes que varían con *. Con esta configuración, Claude Code ejecuta scripts npm y confirmaciones git sin preguntar y rechaza comandos que comienzan con git push. Un push escrito de otra manera, como git -C . push, no coincide; vea lo que una regla de Bash no coincide.

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

Un * puede ir en cualquier lugar de la regla: al inicio, en el medio o al final. Cada fila muestra una regla, comandos que coincide, y comandos cercanos que no coincide:

Usted escribe Coincide No coincide
Bash(npm run build) npm run build npm run build --watch
Bash(npm run *) npm run build, npm run test --watch, npm run npm install
Bash(git log * main) git log --oneline main, git log -5 main, git log --output=<file> main git log main, git push origin main
Bash(git * main) git merge main, git push origin main, git -c core.fsmonitor=<script> diff main git log
Bash(* --version) node --version, bash -c 'echo hi' --version node -v
Bash(ls *) ls -la, ls lsof
Bash(ls*) ls -la, lsof
Bash(* --help *) npm --help x npm --help

Tres reglas de coincidencia producen esas filas:

  • 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.

El sufijo :* es una forma equivalente de escribir un comodín final, por lo que Bash(ls:*) coincide con los mismos comandos que Bash(ls *).

El diálogo de permisos escribe la forma separada por espacios cuando selecciona "Sí, no preguntar de nuevo" para un prefijo de comando. La forma :* solo se reconoce al final de un patrón. En un patrón como Bash(git:* push), los dos puntos se tratan como un carácter literal y no coincidirán con comandos git.

Comodines de nombre de herramienta

Las reglas de denegación y solicitud también aceptan patrones glob en la posición del nombre de la herramienta. El patrón debe coincidir con el nombre completo de la herramienta: "*" coincide con todas las herramientas, y "mcp__*" coincide con todas las herramientas MCP en todos los servidores. Una herramienta coincidida por una regla de denegación de nombre simple se elimina del contexto de Claude, igual que un nombre de herramienta simple, incluida la excepción EndConversation: una denegación glob no puede eliminarla mientras permanezca cualquier otra herramienta, y una solicitud glob nunca solicita por ella. Esta configuración deniega todas las herramientas MCP:

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

Las reglas de permiso aceptan comodines de nombre de herramienta solo después de un prefijo literal mcp__<server>__. El segmento del servidor debe estar libre de comodines para que la regla nombre un servidor específico que hayas configurado. mcp__puppeteer__* coincide con todas las herramientas del servidor puppeteer, y mcp__github__get_* coincide con sus herramientas get_. Un comodín de permiso sin ancla como "*", "B*", o "mcp__*" se omite y no aprueba automáticamente nada.

Una regla de denegación o solicitud cuyo nombre de herramienta no coincide con ninguna herramienta conocida produce una advertencia de inicio para detectar errores tipográficos. Los nombres de herramientas que contienen _ o * están exentos de la verificación, y también lo están los nombres de herramientas que Claude Code ha eliminado, como TaskOutput.

Reglas de permisos específicas de herramientas

Bash

Las reglas de Bash coinciden con el texto completo del comando, donde * representa cualquier texto. Patrones de comodín muestra qué comandos coinciden con cada forma de regla y dónde colocar el *. El resto de esta sección cubre cómo Claude Code hace coincidir comandos compuestos y envoltorios, qué envoltorios y acciones de find no puede aprobar una regla de prefijo, con qué no coincide una regla, los comandos de solo lectura y las redirecciones.

Comandos compuestos

[!TIP]

Claude Code es consciente de los operadores de shell, por lo que una regla como Bash(safe-cmd *) no le dará permiso para ejecutar el comando safe-cmd && other-cmd. Los separadores de comando reconocidos son &&, ||, ;, |, |&, & y saltos de línea. Cada subcomando debe estar permitido para que un comando compuesto se ejecute sin pedir confirmación, por ejemplo porque el subcomando coincide con una regla de permiso o es un comando de solo lectura.

Las reglas de negación y solicitud se aplican cuando cualquier subcomando coincide con ellas, incluido un comando anidado dentro de un subshell, una sustitución de comando o un cuerpo de flujo de control como un bucle for. Una regla de solicitud como Bash(git clean *) aún te pide aprobación para cd /tmp && git clean -f o echo "$(git clean -f)", incluso en modo automático.

Cuando && o || no tiene nada después, como en npm test &&, Claude Code trata el comando como no analizable y no lo divide en subcomandos para la coincidencia de reglas de permiso, por lo que una regla como Bash(npm *) no lo aprueba.

Cuando apruebas un comando compuesto con "Sí, y no vuelvas a preguntar", Claude Code guarda una regla separada para cada subcomando que requiere aprobación, en lugar de una única regla para la cadena completa. Por ejemplo, aprobar git status && npm test guarda una regla para npm test, por lo que las invocaciones futuras de npm test se reconocen independientemente de lo que preceda a &&. Los subcomandos como cd a un directorio fuera de tus directorios de trabajo generan su propia regla de lectura para esa ruta. Se pueden guardar hasta 5 reglas para un único comando compuesto.

Envoltorios

Antes de hacer coincidir las reglas de Bash, Claude Code elimina un conjunto fijo de envoltorios, por lo que una regla como Bash(npm test *) también coincide con timeout 30 npm test. Los envoltorios eliminados son timeout, time, nice, nohup y stdbuf, más los builtins de shell command y builtin, y noglob de zsh. Cada uno ejecuta su argumento como el comando real. Dos formas relacionadas no se eliminan: la forma de consulta command -v, que busca un comando en lugar de ejecutarlo, y nocorrect de zsh.

Claude Code también elimina una asignación inicial de ciertas variables de entorno conocidas como seguras, por lo que Bash(npm test *) coincide con NODE_ENV=test npm test. Una regla de permiso no coincidirá más allá de una asignación de cualquier otra variable. Una regla de negación o solicitud coincide más allá de cualquier asignación inicial, por lo que Bash(rm *) en negación aún coincide con FOO=bar rm -rf tmp/.

xargs sin opciones también se elimina, por lo que Bash(grep *) coincide con xargs grep pattern. La eliminación se aplica solo cuando xargs no tiene flags: una invocación como xargs -n1 grep pattern se evalúa como un comando xargs, por lo que las reglas escritas para el comando interno no la cubren.

Esta lista de envoltorios está integrada y no es configurable. Los ejecutores de entorno de desarrollo como direnv exec, devbox run, mise exec, npx y docker exec no están en la lista. Debido a que estas herramientas ejecutan sus argumentos como un comando, una regla como Bash(devbox run *) coincide con lo que venga después de run, incluido devbox run rm -rf .. Para aprobar el trabajo dentro de un ejecutor de entorno, escribe una regla específica que incluya tanto el ejecutor como el comando interno, como Bash(devbox run npm test). Agrega una regla por cada comando interno que quieras permitir.

Envoltorios Exec y acciones de find

Una regla de prefijo como Bash(watch *) o Bash(find *) no puede aprobar automáticamente los siguientes comandos, por lo que en modo Manual piden confirmación:

  • 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

Para aprobar una invocación específica que no contiene *, escribe una regla de coincidencia exacta para la cadena de comando completa, como Bash(find build -type f -delete).

Cuando el comando tiene un *, como en find . -name '*.tmp' -delete, Claude Code interpreta la regla como un patrón de comodín, no como una coincidencia exacta, por lo que el comando aún pide confirmación. Apruébalo cada vez que lo pida, o usa un hook PreToolUse que devuelva "allow" para él.

Con qué no coincide una regla de Bash

Una regla de Bash coincide con el texto del comando que Claude escribe, después de que Claude Code divide los comandos compuestos y elimina los envoltorios. No coincide con el mismo programa invocado de una forma diferente, por lo que una regla de negación o solicitud cubre la invocación que Claude generalmente produce y no es un límite de seguridad alrededor del programa. Estas reglas en deny o ask detienen la primera forma y no las otras:

Regla Detiene No detiene
Bash(curl *) curl https://example.com /usr/bin/curl https://example.com, sh -c 'curl https://example.com'
Bash(rm *) rm -rf build/ /bin/rm -rf build/, bash -c 'rm -rf build/'
Bash(git push *) git push origin main git -C . push origin main, git -c push.default=current push origin main, git 'push' origin main

Tus otras reglas y el modo de permisos deciden los comandos de la última columna.

Para la aplicación de restricciones de sistema de archivos y red que no depende del texto del comando, usa sandboxing. Para inspeccionar el texto completo del comando con tu propia lógica antes de que se ejecute, usa un hook PreToolUse.

Comandos de solo lectura

Claude Code reconoce un conjunto integrado de comandos de Bash como de solo lectura y los ejecuta sin una solicitud de permiso en todos los modos, excepto cuando permissions.blockReadsOutsideWorkingDirectories cambia el comportamiento para rutas fuera de tus directorios de trabajo. El conjunto incluye ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd y las formas de solo lectura de git. El conjunto no es configurable; para exigir confirmación para uno de estos comandos, agrega una regla ask o deny para él. En modo automático, estos comandos también pueden esperar la revisión del clasificador; consulta cómo el clasificador evalúa las acciones.

Una redirección como ls > out.txt agrega una verificación sobre el destino. Consulta Redirecciones.

Los patrones glob sin comillas se permiten para comandos cuyos flags son todos de solo lectura, por lo que ls *.ts y wc -l src/*.py se ejecutan sin pedir confirmación.

En modo Manual, los comandos de este conjunto aún piden confirmación en estos casos:

  • 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.
  • 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.

Un cd a una ruta dentro de tu directorio de trabajo o de un directorio adicional también es de solo lectura, y un comando compuesto como cd packages/api && ls se ejecuta sin pedir confirmación cuando cada parte califica por sí sola. Estas combinaciones piden confirmación incluso cuando cada parte es de solo lectura:

  • 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.

[!WARNING]

Los patrones de permisos de Bash que intentan restringir los argumentos de los comandos son frágiles. Por ejemplo, Bash(curl http://github.com/ *) intenta restringir curl a URLs de GitHub, pero no coincidirá con variaciones como:

  • Opciones antes de la URL: curl -X GET http://github.com/...
  • Protocolo diferente: curl https://github.com/...
  • Redirecciones: curl -L http://short.example.com/xyz, que redirige a GitHub
  • Variables: URL=http://github.com && curl $URL

Para un filtrado de URL más confiable, considera:

  • Restringir las herramientas de red de Bash: usa reglas de negación para detener curl, wget y comandos similares, y luego usa la herramienta WebFetch con el permiso WebFetch(domain:github.com) para los dominios permitidos. Una regla de negación no coincide con el mismo programa invocado por ruta o dentro de sh -c, así que combínala con la lista de permitidos de red del sandbox cuando la restricción deba cumplirse; consulta con qué no coincide una regla de Bash
  • Usar hooks PreToolUse: implementa un hook que valide las URLs en los comandos de Bash y bloquee los dominios no permitidos
  • Agregar orientación en CLAUDE.md: describe tus patrones de curl permitidos en CLAUDE.md. Esto orienta lo que Claude intenta, pero no impone un límite, así que combínalo con una de las opciones anteriores

Ten en cuenta que usar solo WebFetch no impide el acceso a la red. Si Bash está permitido, Claude aún puede usar curl, wget u otras herramientas para acceder a cualquier URL.

Redirecciones

Cuando un comando redirige la salida o la entrada, Claude Code verifica el destino de la redirección contra tus reglas de archivos como si Claude escribiera o leyera ese archivo directamente:

  • 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.

Los destinos que no tienen un archivo detrás no se verifican: /dev/null, las formas de descriptor de archivo como 2>&1 y <&3, y los here-docs y here-strings.

Claude Code también verifica los archivos que escribe un comando tee, incluso dentro de un pipeline como make | tee build.log. La verificación cubre tus reglas Edit de permiso y negación, las rutas protegidas y los directorios de trabajo. Una regla de permiso como Bash(tee *) no cubre un destino fuera de los directorios de trabajo. Claude Code verifica los destinos de tee en v2.1.269 y posteriores.

PowerShell

Las reglas de permisos de PowerShell usan la misma forma que las reglas de Bash, y un PowerShell sin argumentos o PowerShell(*) coincide con cualquier comando. Esta configuración permite los comandos Get-ChildItem y git commit mientras bloquea Remove-Item:

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

Los alias comunes se canonicalizan antes de la coincidencia. Una regla escrita para el nombre del cmdlet también coincide con esos alias, por lo que PowerShell(Get-ChildItem *) también coincide con gci, ls y dir. La coincidencia no distingue entre mayúsculas y minúsculas.

Claude Code analiza el AST de PowerShell y verifica cada comando de un comando compuesto de forma independiente. Los operadores de pipeline |, los separadores de instrucciones ; y, en PowerShell 7+, los operadores de cadena && y || dividen un comando compuesto en subcomandos. Cada subcomando debe estar permitido para que el comando compuesto se ejecute sin pedir confirmación, por ejemplo coincidiendo con una regla de permiso.

Read y Edit

Para impedir que las herramientas de archivos de Claude lean un archivo o directorio, agrega una regla de negación Read para su ruta, como Read(./.env) o Read(./secrets/**); Excluir archivos sensibles tiene un ejemplo listo para pegar. Si tu proyecto tiene un archivo .claudeignore, no tiene ningún efecto, así que traslada sus entradas a reglas de negación Read.

Qué cubren las reglas Read y Edit

Las reglas Edit se aplican a todas las herramientas integradas que editan archivos. Claude hace un esfuerzo razonable por aplicar las reglas de negación Read(path) a todas las herramientas integradas que leen archivos, como Grep y Glob. Hace el mismo esfuerzo por aplicar las reglas de negación Read(path) a las menciones @file en tus prompts y a la selección y el contexto de archivos abiertos que un IDE conectado comparte con Claude.

Una regla de negación Read(path) también se aplica a las rutas de imágenes que pegas en un prompt y a los directorios que mencionas con @:

  • 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.

Claude Code verifica las rutas de imágenes pegadas y los listados de directorios en v2.1.290 y posteriores.

Una regla de negación Read también bloquea las herramientas Edit y Write en la misma ruta, incluida la creación de un archivo nuevo allí. NotebookEdit no está cubierta, así que agrega una regla de negación Edit para las rutas que ninguna herramienta debe modificar. Para la herramienta Write, la verificación requiere Claude Code v2.1.228 o posterior.

[!WARNING]

Las reglas de negación Read y Edit se aplican a las herramientas de archivos integradas de Claude, a los comandos de archivos que Claude Code reconoce en Bash, como cat, head, tail, sed y tee, y a los destinos de las redirecciones de Bash como > file y < file. No se aplican a un comando que lee archivos sin nombrarlos, como grep -r pattern . ejecutado desde el directorio que contiene el archivo, ni a subprocesos arbitrarios que leen o escriben archivos indirectamente, como un script de Python o Node que abre archivos por sí mismo. Para una aplicación a nivel del sistema operativo que impida a todos los procesos acceder a una ruta, habilita el sandbox.

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

Claude Code verifica los permisos de archivos contra las reglas Edit(path) y Read(path). Acepta una regla con una ruta distinta de * para una de las herramientas siguientes, pero no hace coincidir con ella ninguna lectura, búsqueda ni edición. Una regla de negación Grep(docs/**) no impide que Grep busque en docs. Escribe en su lugar la regla Edit o Read:

  • 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.

Para hacer coincidir cada uso de una de estas herramientas independientemente de la ruta, escribe solo el nombre de la herramienta.

Cómo coinciden los patrones de ruta

Las reglas Read y Edit usan ambas la sintaxis de patrones de gitignore con cuatro tipos de patrón distintos:

Patrón Significado Ejemplo Coincide
//path Ruta absoluta desde la raíz del sistema de archivos Read(//Users/alice/secrets/**) /Users/alice/secrets/**
~/path Ruta desde el directorio home Read(~/Documents/*.pdf) /Users/alice/Documents/*.pdf
/path Ruta relativa a la fuente de configuración Edit(/src/**/*.ts) <primary working directory>/src/**/*.ts en la configuración del proyecto
path o ./path Ruta relativa al directorio actual Read(*.env) <cwd>/*.env

[!WARNING]

Un patrón como /Users/alice/file no es una ruta absoluta. La barra inicial única se ancla en la fuente de configuración, no en la raíz del sistema de archivos. Usa //Users/alice/file para rutas absolutas.

Dónde se ancla un patrón

Un patrón /path se ancla en un directorio asociado con la fuente de configuración que lo define, por lo que la misma regla coincide con ubicaciones diferentes según dónde la coloques:

Regla definida en /path se resuelve a
Configuración del proyecto en .claude/settings.json <primary working directory>/path
Configuración local en .claude/settings.local.json <primary working directory>/path
Configuración de usuario en ~/.claude/settings.json ~/.claude/path
Un archivo pasado con --settings <file> <directory of file>/path
Flags de la CLI o reglas de sesión <primary working directory>/path

Una regla que agregas mediante /permissions sigue la fila del archivo de configuración en el que la guardas.

Las reglas de la configuración local se anclan en el directorio de trabajo principal de la sesión, no en la raíz del repositorio donde Claude Code almacena el archivo. En una sesión iniciada en la raíz del repositorio, ambos directorios son el mismo; en una sesión de worktree, una regla compartida como Edit(/src/**) coincide con el directorio src/ propio de ese worktree.

Una regla de negación como Read(/secrets/**) en la configuración de usuario bloquea ~/.claude/secrets/**, no un directorio secrets de tu proyecto. Para escribir en la configuración de usuario una regla que se aplique dentro de cada proyecto, usa en su lugar una ruta absoluta con // o una ruta relativa al directorio home con ~/.

En Windows, las rutas se normalizan a formato POSIX antes de la coincidencia. C:\Users\alice se convierte en /c/Users/alice, así que usa //c/**/.env para que coincida con archivos .env en cualquier lugar de esa unidad. Para que coincida en todas las unidades, usa //**/.env.

Ejemplos:

  • 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

Una regla solo coincide con archivos bajo su ancla; dentro de ese límite, la profundidad de coincidencia depende de la forma del patrón y, para los patrones de directorio de un solo segmento, del tipo de regla, como se describe a continuación. Los nombres de archivo sin ruta siguen la semántica de gitignore y coinciden a cualquier profundidad, por lo que Read(.env) y Read(**/.env) son equivalentes:

Regla de negación Bloquea No bloquea
Read(.env) o Read(**/.env) cualquier .env en el directorio actual o debajo de él .env en un directorio padre o en otro proyecto
Read(//**/.env) cualquier .env en cualquier lugar del sistema de archivos nada; la regla está anclada en la raíz del sistema de archivos

Un patrón relativo con un único segmento de directorio, como src/**, coincide a profundidades diferentes según el tipo de regla:

  • 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.

Todas las demás formas de patrón coinciden a la misma profundidad en todos los tipos de regla: Edit(/src/**) y Edit(src/components/**) coinciden solo en su ubicación anclada, mientras que Edit(**/src/**) coincide a cualquier profundidad.

El siguiente ejemplo muestra cada forma de patrón frente a un proyecto con un directorio src/ de nivel superior y una copia anidada bajo vendor/:

<current-directory>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js
Regla Coincide con src/app.ts Coincide con vendor/pkg/src/lib.js
Edit(src/**) como regla de permiso Sí No
Edit(src/**) como regla de negación o solicitud Sí Sí
Edit(/src/**) en cualquier tipo de regla Sí No
Edit(**/src/**) en cualquier tipo de regla Sí Sí

[!NOTE]

En los patrones de gitignore, * coincide dentro de un único segmento de ruta y puede aparecer en cualquier posición del patrón, mientras que ** coincide a través de directorios.

Caracteres especiales y negación con !

Cuando apruebas una ruta de archivo con "Sí, y no vuelvas a preguntar", Claude Code escapa los caracteres de patrón de gitignore de esa ruta, como [, ] y *, para que la regla generada coincida solo con la ruta literal que aprobaste. Las reglas que escribes tú mismo no se escapan.

No necesitas escapar los paréntesis en una ruta, así que Edit(./Finance (2024)/**) coincide con la carpeta Finance (2024) tal como está escrita.

Una regla de negación o solicitud cuya ruta no sea utilizable como patrón de gitignore aún protege esa ruta exacta. Una regla de permiso con un patrón no utilizable no aprueba nada.

Un patrón de negación o solicitud que comienza con ! es una negación de gitignore. Excluye las rutas con las que coincide de las reglas path o ./path listadas antes que él. En la lista deny de un archivo de configuración, Read(*.env) seguido de Read(!sample.env) bloquea cada archivo cuyo nombre termina en .env a cualquier profundidad, excepto los archivos llamados sample.env. Una regla ! listada primero no excluye nada.

La exclusión solo alcanza a las reglas de la misma fuente. Un Read(!.env) en la configuración del proyecto o en --disallowedTools no anula una negación Read(./.env) de la configuración administrada ni de cualquier otro archivo de configuración.

Dos límites restringen lo que un patrón ! puede excluir:

  • 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

Cuando una ruta de archivo que Claude solicita pasa por un enlace simbólico, la verificación de permisos cubre dos rutas: la que Claude solicitó y el archivo al que se resuelve. Esto se aplica a los enlaces simbólicos en macOS, Linux y Windows, y a las uniones de directorio en Windows.

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

Las reglas de permiso y de negación tratan de manera diferente la ruta solicitada y el archivo al que se resuelve:

  • 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.

En macOS y Linux, una regla de negación o solicitud escrita a través de un directorio enlazado simbólicamente con un patrón //, ~/ o / también se aplica en la ubicación real del directorio. Por ejemplo, en macOS, donde /etc se resuelve a /private/etc, Read(//etc/**) también bloquea /private/etc/hosts. Antes de v2.1.268, una regla de negación o solicitud escrita a través de un directorio enlazado simbólicamente no se aplicaba a una ruta indicada por su ubicación real.

Grep y Glob buscan en el directorio al que se resuelve el argumento path. Claude Code aplica las reglas de negación Read a ese directorio.

Adjuntos a través de un enlace simbólico

Una regla de negación Read también cubre estos adjuntos, y compara cada uno tanto con la ruta indicada como con el archivo al que se resuelve. Claude Code deja un adjunto fuera de la conversación cuando una regla coincide con él:

  • 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

Con permissions.blockReadsOutsideWorkingDirectories activado, o en una sesión --restricted, estos adjuntos también se omiten cuando provienen de una ruta en la que ese ajuste o flag rechaza las lecturas de archivos de Claude.

Esta línea en lugar de un archivo que mencionaste con @ significa que Claude Code no pudo determinar a dónde lleva la ruta, por ejemplo porque sus enlaces simbólicos forman un bucle:

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

Se le indica a Claude que lea la ruta con sus herramientas de archivos en su lugar, lo que puede funcionar cuando a Claude Code solo se le agotó el tiempo para examinar la ruta.

Cuando los enlaces simbólicos de la ruta no se resuelven, esa lectura también se rechaza, así que corrige el enlace en el disco o menciona el archivo con @ mediante una ruta que se resuelva.

Escrituras a través de un enlace simbólico

Si la ruta que Claude pide editar o escribir es en sí misma un enlace simbólico, las herramientas Edit y Write rechazan la escritura y dirigen a Claude al destino del enlace.

Una escritura aún puede pasar por un enlace simbólico cuando un directorio en el camino hacia el archivo es un enlace simbólico, o cuando la escritura la hace un comando de Bash o PowerShell. Para esas escrituras, lo que sucede depende de dónde se encuentra el archivo al que se resuelve la escritura en relación con tus directorios de trabajo y las rutas protegidas:

  • 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

Cuando Claude Code no puede determinar a dónde lleva una ruta en el disco, por ejemplo porque los enlaces simbólicos en ella forman un bucle, las herramientas Read, Edit y Write rechazan la operación.

Cuando una herramienta abre después el archivo aprobado, confirma que la ruta aún se resuelve a la ubicación que aprobó la verificación de permisos.

Rutas de red

Cuando las herramientas de lectura de archivos de Claude, como Read, Grep y Glob, leen desde una ruta de red, la lectura recibe su propia verificación de permisos. Una ruta de red es aquella que puede llegar a otra computadora: en Windows, una ruta UNC como \\server\share\file, y en macOS y Linux, una ruta de montaje automático /net como /net/fileserver/notes.txt. Buscar una ruta así puede contactar al host que nombra, y en Windows ese contacto puede enviarle tus credenciales al host. Los comandos de shell tienen su propia verificación: en modo Manual, un comando de Bash o PowerShell de solo lectura cuyos argumentos incluyen una ruta UNC aún pide confirmación en Windows.

En Claude Code v2.1.292 y posteriores, ninguno de los siguientes elimina la solicitud:

  • 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

En el modo dontAsk, Claude Code niega la lectura en lugar de pedir confirmación. En el modo bypassPermissions, y en sesiones interactivas de terminal en modo plan con omisión de permisos disponible, la lectura se ejecuta sin esta solicitud.

Para leer archivos en un recurso compartido de red sin esta solicitud, primero asígnale al recurso compartido una ruta local:

  • 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

Las reglas de WebFetch usan un prefijo domain: y se comparan con el nombre de host de la URL solicitada. La coincidencia no distingue mayúsculas de minúsculas, admite comodines * y elimina un . final tanto de la regla como del nombre de host, de modo que example.com. y example.com se tratan igual.

  • 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

En cualquier posición que no sea un *. inicial o un * solo, el comodín coincide únicamente con el texto entre dos puntos. WebFetch(domain:example.*) coincide con example.org, donde * se convierte en org, pero no con example.evil.com, donde * tendría que convertirse en evil.com y cruzar un punto. Esto evita que un comodín final coincida con dominios que un atacante podría registrar.

Los comodines en las reglas WebFetch requieren Claude Code v2.1.172 o posterior para coincidir con las obtenciones.

Permitir o negar todas las obtenciones

Una regla WebFetch sin argumentos es el nombre de la herramienta sin la parte domain:, como "deny": ["WebFetch"]. Tanto ella como WebFetch(domain:*) cubren todas las URLs, pero Claude Code las aplica de manera diferente, y solo la forma domain: agrega además su dominio a la lista de dominios permitidos o negados del sandbox. Esa sección enumera las formas de comodín que respeta el sandbox y la versión que agregó el * solo.

Cada fila muestra lo que hace una regla en la lista allow y en la lista deny:

Regla En allow En deny
WebFetch Claude obtiene páginas sin pedirte confirmación. No cambia a qué hosts pueden acceder los comandos en el sandbox. Claude Code elimina la herramienta WebFetch, por lo que Claude no puede obtener nada. No cambia a qué hosts pueden acceder los comandos en el sandbox.
WebFetch(domain:*) Claude obtiene páginas sin pedirte confirmación, y los comandos en el sandbox pueden acceder a cualquier host. Claude Code mantiene la herramienta y rechaza cada obtención, y los comandos en el sandbox no pueden acceder a ningún host.

Las dos formas también difieren en las lecturas de artefactos, las páginas que la herramienta Artifact publica en claude.ai. Una regla de negación o solicitud WebFetch sin argumentos no se aplica a esas lecturas. Una regla domain: que cubra claude.ai o el host de contenido *.claudeusercontent.com, como WebFetch(domain:claude.ai) o WebFetch(domain:*), niega cada lectura o pide confirmación antes de ella. Una regla Artifact hace lo mismo.

Cuando una regla bloquea una lectura, el rechazo nombra la regla. Antes de v2.1.268, una regla de negación WebFetch sin argumentos bloqueaba todas las lecturas de artefactos, y una regla de solicitud sin argumentos pedía confirmación antes de cada una.

Para permitir que Claude obtenga páginas libremente sin modificar la lista de permitidos del sandbox, usa la forma sin argumentos. Este settings.json hace eso:

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

Cuando le pides a Claude que obtenga una página, lo hace sin pedir confirmación. Cuando le pides que ejecute un curl en el sandbox contra un host fuera de la lista de permitidos del sandbox, Claude Code aún te pide confirmación para ese host, porque la regla sin argumentos no agregó el host a la lista de permitidos.

En modo automático, Claude en cambio nombra el host en los dominios permitidos por comando del comando para que el clasificador lo revise.

MCP

Para hacer coincidir todas las herramientas de un servidor MCP, escribe mcp__<server>__*. Para hacer coincidir una sola herramienta, escribe su nombre completo, mcp__<server>__<tool>.

  • 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

Para <server>, escribe el nombre del servidor tal como aparece en los nombres de las herramientas de ese servidor. Estos ejemplos muestran la regla que debes escribir para un nombre con caracteres especiales, un servidor de un plugin y un nombre que contiene __ o termina en _:

  • 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.

Si tu organización ha configurado una herramienta de un conector de claude.ai en ask y esa configuración llega a Claude Code en tu sesión, las reglas de permiso para esa herramienta no tienen efecto: Claude Code pide confirmación en cada llamada, incluso en los modos auto y bypassPermissions. En el modo dontAsk, que nunca pide confirmación, Claude Code niega la llamada en su lugar. Las herramientas de los conectores que Claude Code obtiene por sí mismo aparecen como mcp__claude_ai_<server>__<tool>.

En una sesión de Cowork en la aplicación Claude Desktop, Claude ejecuta comandos de shell mediante la herramienta mcp__workspace__bash de Cowork en lugar de la herramienta Bash integrada, y Cowork también proporciona mcp__workspace__web_fetch para obtener páginas web. Claude Code también aplica a estas herramientas de Cowork las reglas de negación que nombran la herramienta Bash o WebFetch completa, por lo que una regla de negación Bash administrada impide que Claude ejecute comandos de shell en Cowork. Cuando Claude Code bloquea una llamada así, el mensaje nombra la herramienta de Cowork: Permission to use mcp__workspace__bash has been denied. Las reglas de permiso no se trasladan: Claude Code nunca aplica una regla de permiso Bash a mcp__workspace__bash.

Agent (subagentes)

Usa reglas Agent(AgentName) para controlar qué subagentes puede usar Claude:

  • 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

Agrega estas reglas al arreglo deny de tu configuración o usa el flag de la CLI --disallowedTools para deshabilitar agentes específicos. Para deshabilitar el agente Explore:

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

Cd

Las reglas Cd controlan a qué directorios puede mover la sesión el comando /cd. Cd no es una herramienta que el modelo pueda invocar: Claude no puede llamarla, y las reglas se aplican solo cuando tú mismo ejecutas /cd.

Una regla de negación Cd sin argumentos deshabilita /cd por completo. Una regla de negación Cd(<path-pattern>) bloquea los destinos que coinciden. Las reglas de negación verifican cada forma de escribir el destino, incluido cada salto de enlace simbólico por el que se resuelve, por lo que una regla escrita para una ruta también bloquea los destinos que se resuelven a ella.

Agregar cualquier regla de permiso Cd cambia /cd al modo de lista de permitidos: el directorio de destino resuelto debe coincidir con una de tus reglas de permiso, o /cd se rechaza. Sin reglas Cd configuradas, /cd mantiene su comportamiento predeterminado y te pide que confíes en un directorio desconocido.

Los patrones de ruta comparten los anclajes //, ~/ y / de las reglas Read y Edit, pero la coincidencia se ancla a la ruta completa del directorio en lugar de seguir el estilo de gitignore. * coincide exactamente con un segmento de ruta y ** coincide a través de segmentos. Un /** final también coincide con la raíz que nombra.

Regla Coincide No coincide
Cd(~/code/*) ~/code/app ~/code/app/src, ~/code
Cd(~/code/**) ~/code y cualquier directorio dentro de él directorios fuera de ~/code
Cd(**/node_modules) cualquier directorio node_modules a cualquier profundidad bajo el directorio actual node_modules/pkg

Extender permisos con hooks

Los hooks de Claude Code le permiten registrar comandos de shell personalizados que evalúan permisos en tiempo de ejecución. Cuando Claude Code realiza una llamada de herramienta, los hooks PreToolUse se ejecutan antes del aviso de permisos, para cada herramienta excepto EndConversation. La salida del hook puede denegar la llamada de herramienta, forzar un aviso u omitir el aviso para permitir que la llamada continúe.

Precedencia entre reglas, hooks y mods

Las decisiones del hook PreToolUse no omiten las reglas de permisos. Claude Code evalúa las reglas de negación y solicitud independientemente de lo que devuelva un hook PreToolUse: una regla de negación coincidente bloquea la llamada, y una regla de solicitud coincidente aún solicita incluso cuando el hook devolvió "allow" u "ask". Esto preserva la precedencia de negación primero descrita en Administrar permisos, incluyendo reglas de negación establecidas en configuración administrada.

Esa precedencia cubre los hooks en archivos de configuración y en el archivo hooks/hooks.json de un plugin. Un mod que instales y que maneje el evento tool.check da su respuesta después de que se hayan ejecutado los hooks PreToolUse. Con configuración administrada en la máquina, o un /login de Team o Enterprise como credencial de la sesión, estos resultados se mantienen de forma predeterminada cuando el mod aprueba una llamada:

  • Una llamada que una regla de negación rechaza sigue rechazada, y tu organización puede cambiar eso.
  • 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.

Sin configuración administrada ni un /login de Team o Enterprise como credencial de la sesión, el mod puede aprobar una llamada que una regla de negación rechaza o que un hook PreToolUse bloqueó. Una sesión que se ejecuta con una clave de API o con un CLAUDE_CODE_OAUTH_TOKEN de larga duración no está usando ese inicio de sesión, incluso cuando ese inicio de sesión está almacenado.

En esa configuración no se te pide confirmación cuando el mod aprueba una llamada para la que una regla de solicitud, un hook PreToolUse o permissions.blockReadsOutsideWorkingDirectories pedirían confirmación. Tampoco se consulta a tu --permission-prompt-tool ni a tu callback canUseTool sobre una llamada que el mod aprueba. El modo automático, el modo plan y el modo dontAsk agregan cada uno un resultado propio en cualquier configuración:

  • 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.

Consulte Decidir si confiar en un mod, o Administrar mods para su organización si implementa configuración administrada.

Para una herramienta que requiere interacción del usuario, como AskUserQuestion o una herramienta MCP marcada como requiresUserInteraction, la aprobación de tool.check de un mod no omite la solicitud de permiso. Requiere Claude Code v2.1.292 o posterior. Las herramientas MCP marcadas como requiresUserInteraction también siguen solicitando confirmación cuando un hook devuelve "allow", al igual que las lecturas desde rutas de red y las herramientas de conector que tu organización estableció en ask en sesiones donde ese ajuste llega a Claude Code.

Un hook de bloqueo también tiene precedencia sobre las reglas de permiso. Un hook que sale con código 2 detiene la llamada de herramienta antes de que se evalúen las reglas de permisos, por lo que el bloqueo se aplica incluso cuando una regla de permiso permitiría que la llamada continúe. Para ejecutar todos los comandos Bash sin avisos excepto algunos que desea bloquear, agregue "Bash" a su lista de permiso y registre un hook PreToolUse que rechace esos comandos específicos. Consulte Bloquear ediciones a archivos protegidos para un script de hook que puede adaptar.

Aprobaciones de hooks en modo plan

En modo plan, aparte de ExitPlanMode, el "allow" de tu hook PreToolUse no tiene efecto sobre una edición de archivo u otra llamada que no sea de solo lectura. Obtienes la misma solicitud de permiso, bloqueo o aprobación que la llamada obtendría sin ningún hook, y Claude Code sigue aplicando cualquier updatedInput que devuelva el hook. Si el hook responde a ExitPlanMode con "allow" y updatedInput, esa herramienta sigue ejecutándose sin solicitud de permiso.

En modo plan, un mod que maneje tool.check tampoco puede aprobar una edición de archivo u otra llamada que no sea de solo lectura, aunque sí puede bloquear dicha llamada. Para eliminar este límite sobre las aprobaciones de hooks y mods, aprueba el plan o cambia a otro modo de permisos.

Directorios de trabajo

De forma predeterminada, Claude tiene acceso a los archivos del directorio donde lo iniciaste. Ese directorio es el directorio de trabajo principal de la sesión hasta que muevas la sesión con /cd. Puedes ampliar este acceso:

  • 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

Los archivos de los directorios adicionales siguen las mismas reglas de permisos que el directorio de trabajo original: se pueden leer sin solicitudes de permiso, salvo por la comprobación de rutas de red, y los permisos de edición de archivos siguen el modo de permisos actual.

No puedes agregar la mayoría de las rutas de red, como el recurso compartido UNC \\server\share, como directorios de trabajo, porque buscar una de ellas puede contactar al host que nombra. En Windows, asigna el recurso compartido a una letra de unidad y pasa esa unidad con --add-dir al iniciar.

En las sesiones en segundo plano en macOS, el host de la sesión solicita acceso a carpetas protegidas como ~/Desktop, ~/Documents y ~/Downloads por separado de tu terminal cuando Claude necesita leer o escribir archivos allí; si las lecturas en esas carpetas fallan con Operation not permitted, consulta cómo otorgar acceso a carpetas a las sesiones en segundo plano.

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

Para que las herramientas de archivos de Claude rechacen las rutas fuera de los directorios de trabajo en todos los modos de permisos, incluido bypassPermissions, establece una o ambas de estas claves en true:

Para mantener accesible un directorio externo mientras cualquiera de las claves esté en true, agrégalo como directorio de trabajo.

Mover la sesión a otro directorio

Para mover la sesión a un directorio de trabajo principal diferente, en lugar de agregar un directorio junto al actual, ejecuta /cd <path>. Claude Code conserva la conversación, carga el CLAUDE.md del nuevo directorio y te pide confiar en el espacio de trabajo si no has trabajado en él antes. Después, Claude Code encuentra la sesión movida cuando ejecutas --resume desde el nuevo directorio.

En cuanto te mueves, Claude Code aplica la configuración de proyecto del nuevo directorio:

Claude Code también desconecta los servidores MCP de proyecto y de alcance local del directorio anterior, así como los servidores de los plugins que ya no están habilitados después del cambio. Toma los directorios adicionales de la configuración del nuevo directorio en lugar de la del anterior, y conserva los directorios que agregaste con --add-dir o /add-dir. Los hooks que activa el cambio siguen recibiendo ${CLAUDE_PROJECT_DIR} con el valor de la raíz del proyecto donde comenzó la sesión.

Cuando el nuevo directorio aún no es de confianza, Claude Code enumera en la solicitud de confianza las reglas de permiso, los directorios adicionales, los hooks y los comandos auxiliares que activaría la configuración del directorio, para que puedas revisarlos antes de aceptar. Si rechazas, la sesión se queda donde está. Antes de la v2.1.246, /cd no aplicaba la configuración, los hooks, los servidores MCP ni los skills del nuevo directorio hasta que reanudabas la sesión, y su solicitud de confianza no enumeraba lo que activaría la configuración del directorio.

Restringe o desactiva los destinos de /cd con reglas de permisos Cd.

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

Agregar un directorio amplía dónde Claude puede leer y editar archivos. No convierte ese directorio en una raíz de configuración completa: la mayor parte de la configuración de .claude/ no se descubre desde los directorios adicionales, aunque algunos tipos se cargan como excepciones.

Estas excepciones se aplican solo a los directorios agregados con el flag --add-dir o el comando /add-dir, incluidos los directorios que el Agent SDK agrega mediante el flag. Los directorios listados en permissions.additionalDirectories en un archivo de configuración solo otorgan acceso a archivos y no cargan ninguna de las configuraciones siguientes.

La opción additionalDirectories del Agent SDK en TypeScript y la opción add_dirs en Python también reciben las excepciones, aunque la opción de TypeScript comparte su nombre con la clave de configuración. El SDK pasa cada entrada a Claude Code como --add-dir, por lo que esos directorios se comportan como directorios agregados con el flag. Los skills, comandos y subagentes de cualquier directorio agregado con el flag se cargan a través de la fuente de configuración project, por lo que no se cargan cuando excluyes esa fuente con --setting-sources en la CLI o settingSources en el SDK, y el modo bare omite los comandos y subagentes entre ellos.

Los siguientes tipos de configuración se cargan desde los directorios de --add-dir:

Configuración Se carga desde --add-dir
Skills en .claude/skills/ Sí, con recarga en vivo
Archivos de comandos en .claude/commands/ Sí, sin recarga en vivo. Cuando el directorio agregado y tu proyecto definen un comando con el mismo nombre, Claude Code ejecuta el comando de tu proyecto
Subagentes en .claude/agents/ Sí, sin recarga en vivo
Configuración en .claude/settings.json y .claude/settings.local.json Solo las claves enabledPlugins y extraKnownMarketplaces
Archivos CLAUDE.md, .claude/rules/ y CLAUDE.local.md Solo cuando se establece CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1. CLAUDE.local.md además requiere la fuente de configuración local, que está habilitada de forma predeterminada

Para cargar los skills, comandos y subagentes de un subdirectorio de tu directorio de trabajo principal a mitad de la sesión, ejecuta /add-dir con la ruta de ese subdirectorio. Claude Code los carga durante el resto de la sesión sin pedirte confirmación y sin agregar un directorio de trabajo, porque el subdirectorio ya se puede leer. Esto requiere Claude Code v2.1.257 o posterior.

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

Claude Code descubre los estilos de salida desde el directorio de trabajo actual y sus directorios superiores, tu directorio de usuario en ~/.claude/ y la configuración administrada. Los hooks y las demás claves de .claude/settings.json se cargan desde la carpeta .claude/ del directorio de trabajo actual, sin recurrir a los directorios superiores, junto con tu ~/.claude/settings.json de usuario y la configuración administrada.

.claude/settings.local.json se carga en cambio desde la raíz del repositorio git, incluso cuando inicias Claude Code en un subdirectorio, excepto en los casos en que Claude Code no usa la raíz del repositorio, como en Windows.

Para compartir esa configuración entre proyectos, usa uno de estos enfoques:

  • 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

Los permisos y el sandboxing son capas de seguridad complementarias:

  • 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.

Use ambos para defensa en profundidad, ya que las restricciones de sandbox aún se aplican incluso si una inyección de solicitud omite la toma de decisiones de Claude. Las rutas y dominios de la configuración de sandbox y las reglas de permisos se fusionan en la configuración final del sandbox.

Cuando el sandboxing está habilitado y deja autoAllowBashIfSandboxed en su valor predeterminado de true, los comandos Bash en sandbox se ejecutan sin solicitar incluso si sus permisos incluyen una regla ask Bash simple, o la forma equivalente Bash(*): el límite del sandbox sustituye ese aviso de herramienta completa.

En modo plan, Claude Code omite esta sustitución. Sin una regla ask, los comandos de solo lectura integrados aún se ejecutan sin pedir permiso, y cualquier otro comando de shell pasa por el flujo de permisos regular mientras todavía estás planificando; consulta modo plan para saber cómo Claude Code controla los comandos allí. Con una regla ask Bash simple, cada comando Bash pide permiso, incluidos los comandos de solo lectura en el sandbox, igual que fuera del sandboxing.

Estas comprobaciones aún se aplican:

  • 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

Los comandos que no se ejecutarán en sandbox, como comandos excluidos, respetan la regla ask Bash simple como es habitual. Consulte modos de sandbox para cambiar este comportamiento.

Configuración administrada

Para organizaciones que necesitan control centralizado, los administradores implementan configuración administrada que la configuración de usuario y proyecto no pueden anular, excepto por algunas claves sensibles a la seguridad. Implementar configuración administrada cubre los mecanismos de entrega, la precedencia dentro del nivel administrado, y las claves que solo la configuración administrada puede establecer.

Una de esas claves, allowManagedPermissionRulesOnly, hace que la configuración administrada sea la única fuente de configuración de reglas de permisos. Su entrada enumera todas las fuentes que Claude Code luego ignora.

disableBypassPermissionsMode generalmente se coloca en configuración administrada para aplicar la política organizacional, pero funciona desde cualquier alcance. Un usuario puede establecerlo en su propia configuración para bloquearse a sí mismo del modo de bypass.

Precedencia de configuración

Las reglas de permisos siguen la misma precedencia de configuración que todas las demás configuraciones de Claude Code, con la configuración administrada siendo la más alta: ningún otro nivel, incluyendo argumentos de línea de comandos, puede anular una regla de permiso administrada.

Si una herramienta se deniega en cualquier nivel, ningún otro nivel puede permitirla. Por ejemplo, una negación de configuración administrada no puede ser anulada por --allowedTools, y --disallowedTools puede agregar restricciones más allá de lo que define la configuración administrada.

Lo mismo se aplica en todos los ámbitos de configuración: si la configuración de usuario permite un permiso y la configuración de proyecto lo deniega, la regla de negación lo bloquea. Lo contrario también es cierto: una negación a nivel de usuario bloquea un permiso a nivel de proyecto, porque las reglas de negación de cualquier ámbito se evalúan antes que las reglas de permiso.

Esta precedencia es entre archivos de configuración y argumentos de línea de comandos. Para saber si una regla de negación se mantiene sobre un mod que instale, consulte Extender permisos con hooks.

Los hosts de inserción pueden proporcionar política administrada adicional a través de la opción managedSettings del SDK, incluyendo reglas de permiso de permitir a menos que el administrador establezca los bloqueos allowManaged*Only; Entregar política a sesiones de Claude Desktop cubre cuándo se aplica la política del integrador en absoluto.

Reglas allow del proyecto y confianza del espacio de trabajo

Las reglas permissions.allow y las entradas permissions.additionalDirectories en el archivo .claude/settings.json de un proyecto otorgan capacidad, por lo que Claude Code las aplica solo después de que aceptes el diálogo de confianza del espacio de trabajo para esa carpeta. El diálogo enumera las reglas y directorios que la carpeta otorgaría para que puedas revisarlos primero. Las reglas deny y ask no se ven afectadas, ya que solo restringen.

Claude Code asocia y guarda la confianza que aceptas según dónde lo inicies:

  • 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.

Claude Code muestra el diálogo de confianza solo en sesiones interactivas. Una ejecución claude -p o una sesión del SDK nunca lo muestra, y confiar en una carpeta principal no cuenta para estas reglas, por lo que Lo que se ejecuta antes de confiar en una carpeta indica qué contenido del repositorio Claude Code aún utiliza en cada una de esas dos situaciones.

Antes de iniciar o reiniciar una sesión en segundo plano, Claude Code también verifica la confianza del espacio de trabajo para el directorio en el que se ejecuta la sesión. Si ejecutas claude --bg desde una terminal en un directorio en el que no has confiado, el diálogo de confianza aparece primero y la sesión comienza una vez que lo aceptas. Donde no puede aparecer ningún diálogo, como en un script, el comando sale con un error Workspace not trusted en su lugar.

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

.claude/settings.local.json es normalmente tu propio archivo, por lo que Claude Code aplica sus reglas allow y directorios adicionales sin el paso de confianza. Cuando el archivo se rastrea en git, o .claude es un enlace simbólico, Claude Code lo trata como proporcionado por el repositorio y retiene sus reglas sin aplicarlas hasta que confíes en la carpeta.

Claude Code ejecuta git para distinguir ambos casos, y ejecuta git solo después de que hayas confiado en la carpeta: aceptaste el diálogo de confianza para ella o para un directorio principal cuya confianza se extiende a ella, o estás en una sesión -p o del SDK, que cuenta como aceptada. Hasta entonces, el lugar donde iniciaste Claude Code decide qué sucede con las reglas del archivo:

  • 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.

[!NOTE]

La excepción del directorio de configuración personal omite solo el paso de confianza. ~/.claude/settings.local.json sigue siendo de alcance local, por lo que Claude Code lo lee solo en sesiones que inicias en tu propio directorio home, no en cada proyecto. Para aplicar reglas de permisos en todos tus proyectos, agrégalas a tu configuración de usuario en su lugar: ~/.claude/settings.json, o $CLAUDE_CONFIG_DIR/settings.json cuando CLAUDE_CONFIG_DIR está establecido.

Lo que se ejecuta antes de confiar en una carpeta

Cada fila es un tipo de contenido que un repositorio puede proporcionar. Las columnas son las dos situaciones en las que no has confiado en la carpeta misma: confiaste solo en una carpeta principal, o ejecutaste claude -p o el SDK allí, que nunca muestra el diálogo de confianza. La columna de carpeta principal no se aplica dentro de un repositorio anidado: en una sesión interactiva Claude Code muestra el diálogo de confianza para él, y una ejecución claude -p o del SDK allí sigue la columna claude -p.

Lo que proporciona el repositorio Confiaste solo en una carpeta principal claude -p o el SDK, carpeta nunca marcada como confiable
Hooks en archivos de configuración, el bloque env y comandos auxiliares como apiKeyHelper, y los hooks y allowed-tools de un skill del proyecto Se utiliza Se utiliza. La confianza del espacio de trabajo nunca bloquea los allowed-tools de un skill en ninguna sesión
Reglas permissions.allow y additionalDirectories en .claude/settings.json No se utilizan hasta que aceptes el diálogo de confianza, que aparece nuevamente enumerándolas No se utilizan. Claude Code imprime una advertencia this workspace has not been trusted en stderr
Hooks de frontmatter en un subagente del proyecto, un plugin @skills-dir del proyecto, y entradas extraKnownMarketplaces del repositorio o de un directorio --add-dir No se utilizan, y no se ofrece diálogo No se utilizan
mcpServers en línea en el frontmatter de un subagente del repositorio o de un directorio --add-dir No se utilizan, y no se ofrece diálogo No se utilizan
Servidores en .mcp.json, incluidos los que el repositorio aprueba en su propia configuración Claude Code te pregunta antes de conectarlos. Las aprobaciones propias del repositorio no cuentan Se conectan sin preguntar, aprobados o no. El SDK los carga solo cuando settingSources incluye la configuración del proyecto. claude mcp list en la misma carpeta aún reporta tal servidor como pendiente
Un headersHelper en un servidor en .mcp.json No se ejecuta hasta que aceptes el diálogo de confianza, que aparece nuevamente indicando dónde se declara el auxiliar. Hasta entonces, Claude Code conecta el servidor solo con sus headers estáticos No se ejecuta. Claude Code conecta el servidor solo con sus headers estáticos e imprime una línea headersHelper not run por servidor en stderr

Para las filas que necesitan que esta carpeta exacta sea de confianza, márcala como confiable manualmente: establece projects["<path>"].hasTrustDialogAccepted en true en ~/.claude.json, donde <path> es la raíz del repositorio, o la carpeta misma fuera de un repositorio. Claude Code imprime la clave exacta en la línea del registro de depuración para un hook de subagente o servidor MCP en línea omitido, en la advertencia de stderr para reglas allow omitidas, y en la línea headersHelper not run para un auxiliar omitido.

Antes de ejecutar claude -p en un repositorio que no escribiste, decide qué puede ejecutar en tu máquina:

  • 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

Este repositorio incluye configuraciones de configuración inicial para escenarios de implementación comunes. Use estos como puntos de partida y ajústelos para que se adapten a sus necesidades.

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