Escrituras fuera del repo en Claude Code: qué las frena

Desde la versión 2.1.314, Claude Code tiene un ajuste, permissions.blockWritesOutsideWorkingDirectories, que hace que las herramientas Write, Edit y NotebookEdit rechacen cualquier ruta fuera de tus directorios de trabajo, en todos los modos de permisos, incluido bypassPermissions. No limita los comandos de shell. Para eso necesitas además el sandbox.

La pregunta práctica es esta: si lanzas el agente en tu repositorio, ¿puede tocar ~/.npmrc, el repositorio de al lado o tu ~/.bashrc? La respuesta depende de tres capas distintas, y cada una cubre un hueco diferente. Las verás por separado y al final tendrás una configuración copiable y una tabla para saber qué capa frena cada escritura.

Qué cuenta como directorio de trabajo

El perímetro lo marcan los directorios de trabajo, y no siempre coinciden con "la carpeta del repo". Según la documentación de permisos, el directorio principal es aquel en el que lanzas Claude Code (o al que te mueves con /cd), y puedes ampliarlo de tres formas:

• Al arrancar: claude --add-dir ../shared.
• Durante la sesión: el comando /add-dir.
• De forma persistente: la clave permissions.additionalDirectories en un fichero de settings.

Un directorio añadido amplía dónde puede leer y editar el agente, pero no lo convierte en raíz de configuración. La documentación aclara que la mayor parte de .claude/ no se descubre en esos directorios, con algunas excepciones (skills, comandos y subagentes) que solo se aplican a los añadidos con --add-dir o /add-dir, no a los de additionalDirectories. Tenlo presente antes de añadir un directorio solo para cargar su configuración.

Sin el bloqueo, el modo de permisos decide

Si no activas nada, una escritura fuera del perímetro sigue las reglas del modo en que esté la sesión. La página de modos de permisos lo describe así:

El problema está en la última fila. bypassPermissions es el modo habitual en contenedores y en ejecuciones desatendidas con claude -p, y ahí nada se interpone entre el agente y tu home si el contenedor monta más de lo que debería. En auto pasa algo parecido: la decisión queda en manos de un clasificador y no de una regla fija.

Qué hace blockWritesOutsideWorkingDirectories y qué no

El bloqueo es una regla fija que ningún modo puede saltarse, pero solo para las tres herramientas de edición de ficheros. La referencia de settings lo define así: las herramientas Write, Edit y NotebookEdit rechazan rutas fuera de los directorios de trabajo "en todos los modos, incluido bypassPermissions". La entrada del changelog oficial corresponde a la 2.1.314, y según el resumen de Classmethod esa versión se publicó el 30/10/2026.

Lo que el ajuste no cubre, según la misma referencia:

• Comandos de shell (echo ... > ~/fichero, sed -i, cp).
• Herramientas MCP.
• Los programas que ejecutan tus hooks.

Otros detalles de comportamiento que conviene conocer:

• Un true en cualquier fichero cargado gana. Un repositorio puede activar el bloqueo para sí mismo, pero no puede desactivar el tuyo. Poner false equivale a no ponerlo.
• Los ficheros de settings de Claude Code quedan bloqueados incluso dentro del proyecto, porque un settings podría levantar el bloqueo. Esos los editas tú.
• Siguen siendo escribibles algunos ficheros propios de Claude Code: planes, el scratchpad, el tmp de una sesión en segundo plano y los .md de la auto memory del proyecto.
• Desaparecen EnterWorktree y ExitWorktree, y un subagente con isolation: worktree cuyo worktree quede fuera de los directorios de trabajo no podrá editar.
• Para levantarlo tienes que quitar la clave de todos los ficheros que la ponen y reiniciar Claude Code.

La trampa de additionalDirectories en el repositorio

Un directorio que solo añade la configuración del repositorio no cuenta para el bloqueo. Es el detalle que más fácilmente rompe una configuración que parece correcta. La referencia de settings indica que el bloqueo rechaza escrituras en un directorio que additionalDirectories lista solo en .claude/settings.json, o en .claude/settings.local.json salvo que git lo marque como no rastreado.

Supongamos que tienes un monorepo partido en ~/code/web y ~/code/shared-types, lanzas Claude Code en web y en el .claude/settings.json versionado pones "additionalDirectories": ["../shared-types/"]. Con el bloqueo activo, lo esperable según la documentación es que el agente pueda leer shared-types pero que sus Edit allí se rechacen. La lógica es de seguridad: si un repositorio clonado pudiera ampliar su propio perímetro de escritura, el bloqueo no protegería de nada.

Para dejar pasar ese directorio tienes dos opciones:

• Lanzar con claude --add-dir ../shared-types o usar /add-dir en la sesión.
• Poner additionalDirectories en tus settings de usuario (~/.claude/settings.json) o en los gestionados.

En el caso de los worktrees de subagentes, la documentación indica que añadas como directorio de trabajo .claude/worktrees en la raíz del repositorio. Como /add-dir exige que el directorio exista, créalo antes.

Configuración para un claude -p desatendido

Para cerrar las dos vías (herramientas de ficheros y shell) necesitas combinar el bloqueo con el sandbox. El sandbox de Bash está desactivado por defecto. Cuando lo activas, los comandos solo pueden escribir en el directorio de trabajo, en el directorio temporal del usuario y en los directorios añadidos. Funciona en macOS, Linux y WSL2. En Linux necesita los paquetes bubblewrap y socat.

Este ~/.claude/settings.json (de usuario, para que el repositorio no pueda levantarlo) activa las dos capas y abre una única ruta extra de escritura para el shell:

{
  "permissions": {
    "blockWritesOutsideWorkingDirectories": true,
    "additionalDirectories": ["~/code/shared-types/"]
  },
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["/tmp/build"]
    }
  }
}

Fíjate en que las rutas del sandbox siguen la convención estándar (~/ es tu home y /tmp/build es absoluta). No son las convenciones //ruta y /ruta de las reglas Read y Edit, y la propia documentación del sandbox advierte de la diferencia.

Antes de confiar en el bloqueo, comprueba la versión y haz la prueba que propone la documentación:

claude --version   # necesitas 2.1.314 o superior
claude -p "Usa la herramienta Write para crear ~/block-test.txt con el texto hola"
ls ~/block-test.txt   # lo esperado: No such file or directory

Según la referencia de errores, el rechazo aparece con un mensaje como <path>: Writes outside the working directories are blocked (permissions.blockWritesOutsideWorkingDirectories). Si el fichero se crea, revisa que la clave esté en un settings que la sesión cargue de verdad y que tu home no sea uno de los directorios de trabajo, porque en ese caso la ruta queda dentro del perímetro.

Qué capa frena cada escritura

Ninguna capa cubre por sí sola todas las vías de escritura. Usa esta tabla para saber qué te falta según quién escriba:

Las dos últimas filas son las que dependen de ti: revisa qué servidores MCP con capacidad de escritura conectas y qué ejecutan tus hooks, porque ninguna de las tres capas los encierra.

Cuándo no activar el bloqueo

El bloqueo sobra o estorba en estos casos:

• Sesiones cloud. La referencia de settings indica que en una sesión cloud Claude Code puede no aplicar la clave, porque el contenedor ya es la frontera.
• Flujos con EnterWorktree. Si trabajas con worktrees que crea el propio agente y no quieres reorganizar rutas, el bloqueo te quita esas herramientas. Antes de activarlo, decide si añades .claude/worktrees como directorio de trabajo.
• Tareas que, por diseño, tocan tu configuración global, como pedirle que ajuste tu ~/.gitconfig. Ahí es más honesto usar el modo Manual y aprobar cada cambio que levantar y bajar el bloqueo.
• Cuando lo que te preocupa es el shell. Si el agente casi siempre escribe con Bash (generadores, npm install, scripts), el bloqueo apenas cambia nada. La capa que te protege es el sandbox, y en Windows nativo los comandos se ejecutan sin él según la documentación, así que tendrías que trabajar dentro de WSL2.

Como referencia práctica, y no como dato: si ejecutas claude -p en CI o en un contenedor con bypassPermissions, activa las dos capas en settings de usuario o gestionados. En una sesión interactiva en modo Manual, el bloqueo te ahorra sobre todo aprobar por despiste una edición fuera de sitio.