Guías

Configurar permisos

Controla cómo tu agente utiliza herramientas con modos de permiso, hooks y reglas declarativas de permitir/denegar.

El SDK del Agente Claude proporciona controles de permiso para gestionar cómo Claude utiliza las herramientas. Utiliza modos de permiso y reglas para definir qué está permitido automáticamente, y el callback canUseTool para manejar todo lo demás en tiempo de ejecución.

Esta página cubre modos de permiso y reglas. Para crear flujos de aprobación interactivos donde los usuarios aprueban o deniegan solicitudes de herramientas en tiempo de ejecución, consulta Manejar aprobaciones e entrada del usuario.

Cómo se evalúan los permisos

Cuando Claude solicita una herramienta, el SDK verifica los permisos en este orden:

Hooks
Ejecuta hooks primero, que pueden permitir, denegar o continuar al siguiente paso
Reglas de permiso
Verifica las reglas definidas en settings.json en este orden: primero las reglas deny (bloquean independientemente de otras reglas), luego las reglas allow (permiten si coinciden), luego las reglas ask (solicitan aprobación). Estas reglas declarativas te permiten pre-aprobar, bloquear o requerir aprobación para herramientas específicas sin escribir código.
Modo de permiso
Aplica el modo de permiso activo (bypassPermissions, acceptEdits, dontAsk, etc.)
Callback canUseTool
Si no se resuelve mediante reglas o modos, llama a tu callback canUseTool para una decisión

Diagrama de flujo de evaluación de permisos

Esta página se enfoca en modos de permiso (paso 3), la configuración estática que controla el comportamiento predeterminado. Para los otros pasos:

Hooks: ejecuta código personalizado para permitir, denegar o modificar solicitudes de herramientas. Consulta Controlar la ejecución con hooks.
Reglas de permiso: configura reglas declarativas de permitir/denegar en settings.json. Consulta Configuración de permisos.
Callback canUseTool: solicita aprobación a los usuarios en tiempo de ejecución. Consulta Manejar aprobaciones e entrada del usuario.

Modos de permiso

Los modos de permiso proporcionan control global sobre cómo Claude utiliza las herramientas. Puedes establecer el modo de permiso al llamar a query() o cambiarlo dinámicamente durante sesiones de streaming.

Modos disponibles

El SDK admite estos modos de permiso:

Modo	Descripción	Comportamiento de herramientas
`default`	Comportamiento de permiso estándar	Sin aprobaciones automáticas; las herramientas no coincidentes activan tu callback `canUseTool`
`acceptEdits`	Auto-aceptar ediciones de archivos	Las ediciones de archivos y operaciones del sistema de archivos (`mkdir`, `rm`, `mv`, etc.) se aprueban automáticamente
`bypassPermissions`	Omitir todas las verificaciones de permiso	Todas las herramientas se ejecutan sin solicitudes de permiso (usar con precaución)
`plan`	Modo de planificación	Sin ejecución de herramientas; Claude planifica sin hacer cambios

Herencia de subagenetes: Al usar bypassPermissions, todos los subagenetes heredan este modo y no se puede anular. Los subagenetes pueden tener diferentes indicaciones del sistema y comportamiento menos restringido que tu agente principal. Habilitar bypassPermissions les otorga acceso completo y autónomo al sistema sin solicitudes de aprobación.

Establecer modo de permiso

Puedes establecer el modo de permiso una vez al iniciar una consulta, o cambiarlo dinámicamente mientras la sesión está activa.

Detalles del modo

Modo de aceptación de ediciones (`acceptEdits`)

Auto-aprueba operaciones de archivo para que Claude pueda editar código sin solicitar. Otras herramientas (como comandos Bash que no son operaciones del sistema de archivos) aún requieren permisos normales.

Operaciones auto-aprobadas:

Ediciones de archivos (herramientas Edit, Write)
Comandos del sistema de archivos: mkdir, touch, rm, mv, cp

Usar cuando: confías en las ediciones de Claude y deseas una iteración más rápida, como durante la creación de prototipos o cuando trabajas en un directorio aislado.

Modo de omisión de permisos (`bypassPermissions`)

Auto-aprueba todos los usos de herramientas sin solicitudes. Los hooks aún se ejecutan y pueden bloquear operaciones si es necesario.

Usar con extrema precaución. Claude tiene acceso completo al sistema en este modo. Solo usa en entornos controlados donde confías en todas las operaciones posibles.

Modo de planificación (`plan`)

Previene la ejecución de herramientas por completo. Claude puede analizar código y crear planes pero no puede hacer cambios. Claude puede usar AskUserQuestion para aclarar requisitos antes de finalizar el plan. Consulta Manejar aprobaciones e entrada del usuario para manejar estas solicitudes.

Usar cuando: deseas que Claude proponga cambios sin ejecutarlos, como durante la revisión de código o cuando necesitas aprobar cambios antes de que se realicen.

Recursos relacionados

Para los otros pasos en el flujo de evaluación de permisos:

Manejar aprobaciones e entrada del usuario: solicitudes de aprobación interactivas y preguntas aclaratorias
Guía de hooks: ejecuta código personalizado en puntos clave del ciclo de vida del agente
Reglas de permiso: reglas declarativas de permitir/denegar en settings.json

Was this page helpful?

Guías

Configurar permisos

Controla cómo tu agente utiliza herramientas con modos de permiso, hooks y reglas declarativas de permitir/denegar.

Cómo se evalúan los permisos

Cuando Claude solicita una herramienta, el SDK verifica los permisos en este orden:

Hooks
Ejecuta hooks primero, que pueden permitir, denegar o continuar al siguiente paso
Reglas de permiso
Verifica las reglas definidas en settings.json en este orden: primero las reglas deny (bloquean independientemente de otras reglas), luego las reglas allow (permiten si coinciden), luego las reglas ask (solicitan aprobación). Estas reglas declarativas te permiten pre-aprobar, bloquear o requerir aprobación para herramientas específicas sin escribir código.
Modo de permiso
Aplica el modo de permiso activo (bypassPermissions, acceptEdits, dontAsk, etc.)
Callback canUseTool
Si no se resuelve mediante reglas o modos, llama a tu callback canUseTool para una decisión

Esta página se enfoca en modos de permiso (paso 3), la configuración estática que controla el comportamiento predeterminado. Para los otros pasos:

Hooks: ejecuta código personalizado para permitir, denegar o modificar solicitudes de herramientas. Consulta Controlar la ejecución con hooks.
Reglas de permiso: configura reglas declarativas de permitir/denegar en settings.json. Consulta Configuración de permisos.
Callback canUseTool: solicita aprobación a los usuarios en tiempo de ejecución. Consulta Manejar aprobaciones e entrada del usuario.

Modos de permiso

Modos disponibles

El SDK admite estos modos de permiso:

Modo	Descripción	Comportamiento de herramientas
`default`	Comportamiento de permiso estándar	Sin aprobaciones automáticas; las herramientas no coincidentes activan tu callback `canUseTool`
`acceptEdits`	Auto-aceptar ediciones de archivos	Las ediciones de archivos y operaciones del sistema de archivos (`mkdir`, `rm`, `mv`, etc.) se aprueban automáticamente
`bypassPermissions`	Omitir todas las verificaciones de permiso	Todas las herramientas se ejecutan sin solicitudes de permiso (usar con precaución)
`plan`	Modo de planificación	Sin ejecución de herramientas; Claude planifica sin hacer cambios

Establecer modo de permiso

Puedes establecer el modo de permiso una vez al iniciar una consulta, o cambiarlo dinámicamente mientras la sesión está activa.

Detalles del modo

Modo de aceptación de ediciones (`acceptEdits`)

Operaciones auto-aprobadas:

Ediciones de archivos (herramientas Edit, Write)
Comandos del sistema de archivos: mkdir, touch, rm, mv, cp

Usar cuando: confías en las ediciones de Claude y deseas una iteración más rápida, como durante la creación de prototipos o cuando trabajas en un directorio aislado.

Modo de omisión de permisos (`bypassPermissions`)

Auto-aprueba todos los usos de herramientas sin solicitudes. Los hooks aún se ejecutan y pueden bloquear operaciones si es necesario.

Usar con extrema precaución. Claude tiene acceso completo al sistema en este modo. Solo usa en entornos controlados donde confías en todas las operaciones posibles.

Modo de planificación (`plan`)

Usar cuando: deseas que Claude proponga cambios sin ejecutarlos, como durante la revisión de código o cuando necesitas aprobar cambios antes de que se realicen.

Recursos relacionados

Para los otros pasos en el flujo de evaluación de permisos:

Manejar aprobaciones e entrada del usuario: solicitudes de aprobación interactivas y preguntas aclaratorias
Guía de hooks: ejecuta código personalizado en puntos clave del ciclo de vida del agente
Reglas de permiso: reglas declarativas de permitir/denegar en settings.json

Was this page helpful?

Cómo se evalúan los permisos

Modos de permiso

Modos disponibles

Establecer modo de permiso

Detalles del modo

Modo de aceptación de ediciones (acceptEdits)

Modo de omisión de permisos (bypassPermissions)

Modo de planificación (plan)

Recursos relacionados

Cómo se evalúan los permisos

Modos de permiso

Modos disponibles

Establecer modo de permiso

Detalles del modo

Modo de aceptación de ediciones (acceptEdits)

Modo de omisión de permisos (bypassPermissions)

Modo de planificación (plan)

Recursos relacionados

Modo de aceptación de ediciones (`acceptEdits`)

Modo de omisión de permisos (`bypassPermissions`)

Modo de planificación (`plan`)

Modo de aceptación de ediciones (`acceptEdits`)

Modo de omisión de permisos (`bypassPermissions`)

Modo de planificación (`plan`)