Configurar permisos
Controle cómo su agente utiliza herramientas con modos de permiso, hooks y reglas declarativas de permitir/denegar.
El SDK del Agente Claude proporciona controles de permisos para gestionar cómo Claude utiliza las herramientas. Utilice modos de permiso y reglas para definir qué está permitido automáticamente, y la devolución de llamada canUseTool para manejar todo lo demás en tiempo de ejecución.
Cómo se evalúan los permisos
Cuando Claude solicita una herramienta, el SDK verifica los permisos en este orden:
Hooks
Ejecute hooks primero. Un hook puede denegar la llamada directamente o pasarla. Un hook que devuelve allow no omite las reglas de denegar y preguntar a continuación; esas se evalúan independientemente del resultado del hook. Un hook PreToolUse allow tampoco puede aprobar una eliminación rm o rmdir dirigida a una ruta crítica.
Reglas de denegar
Verifique las reglas deny (de disallowed_tools y settings.json). Si una regla de denegar coincide, la herramienta se bloquea, incluso en modo bypassPermissions. Las reglas de nombre simple como Bash eliminan la herramienta del contexto de Claude antes de que comience esta evaluación, por lo que solo se verifican las reglas con alcance como Bash(rm *) en este paso.
Reglas de preguntar
Verifique las reglas ask de settings.json. Si una regla de preguntar coincide, la llamada se pasa a su devolución de llamada canUseTool para confirmación, incluso en modo bypassPermissions.
Las herramientas que requieren interacción del usuario se comportan de la misma manera: AskUserQuestion y las herramientas MCP cuyo servidor establece _meta["anthropic/requiresUserInteraction"] siempre se pasan a la devolución de llamada, incluso cuando una regla de permitir coincide. En modo dontAsk ambos casos se deniegan en su lugar, porque ese modo nunca solicita confirmación. La anotación MCP requiere Claude Code v2.1.199 o posterior.
Las herramientas del conector claude.ai que su organización ha establecido en ask también salen del flujo en este paso. Cada llamada se pasa a la devolución de llamada, incluso en modo bypassPermissions y incluso cuando una regla de permitir coincide. La devolución de llamada recibe la razón Your organization requires approval for this tool. En modo dontAsk la llamada se deniega en su lugar, porque ese modo nunca solicita confirmación.
Modo de permiso
Aplique el modo de permiso activo:
- En modo
bypassPermissions, Claude Code aprueba todo lo que llega a este paso excepto las eliminacionesrmyrmdirdirigidas a una ruta crítica, que se pasan en su lugar. - En modo
acceptEdits, Claude Code aprueba las operaciones de archivo enumeradas en Modo de aceptar ediciones. - En modo
plan, Claude Code envía herramientas de edición de archivo y escritura de shell a su devolución de llamadacanUseToolindependientemente de las reglas de permitir, por lo que las operaciones de escritura no pueden ser aprobadas automáticamente mientras se planifica. - En otros modos, la solicitud se pasa.
Reglas de permitir
Verifique las reglas allow (de allowed_tools y settings.json). Si una regla coincide, la herramienta se aprueba. Una llamada que la herramienta aprueba por sí sola se resuelve en este paso también, sin necesidad de regla: por ejemplo una lectura de archivo dentro de sus directorios de trabajo o un comando Bash de solo lectura. Las eliminaciones rm y rmdir dirigidas a una ruta crítica nunca se aprueban por una regla de permitir: llegan a su devolución de llamada en los modos que solicitan confirmación, van al clasificador en modo auto en Claude Code v2.1.218 o posterior, y se deniegan en modo dontAsk.
Devolución de llamada canUseTool
Si no se resuelve por ninguno de los anteriores, llame a su devolución de llamada canUseTool para una decisión. En modo dontAsk, este paso se omite y la herramienta se deniega.
En el SDK de TypeScript, si establece permissionPrompts: 'none', su devolución de llamada no se llama en este paso. Un hook PermissionRequest aún tiene la oportunidad de decidir, y si no lo hace, Claude Code deniega la llamada. La opción requiere Claude Code v2.1.259 o posterior.
Si pasa una devolución de llamada canUseTool en una configuración donde el SDK de TypeScript espera que el orden de evaluación apruebe automáticamente las llamadas antes de que se consulte la devolución de llamada, el SDK emite una advertencia de proceso de Node.js una vez cuando se construye la consulta. El código de la advertencia es CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Dos configuraciones lo desencadenan:
permissionMode: 'bypassPermissions', que aprueba automáticamente cada llamada que llega al paso del modo de permiso aparte de las acciones que ningún modo aprueba automáticamente- Cada entrada
allowedToolssimple como"Read", que aprueba automáticamente esa herramienta completa antes de que se consulte la devolución de llamada, aparte de las acciones que ningún modo aprueba automáticamente
Las entradas con un especificador como Bash(ls *) y el modo acceptEdits no lo desencadenan, y las reglas de permitir provenientes de archivos de configuración no son visibles para la verificación.
Escuche con process.on('warning', ...) y haga coincidir el código para registrarlo o suprimirlo. Para controlar cada llamada de herramienta independientemente del modo y las reglas, use un hook PreToolUse en su lugar.
Esta página se enfoca en reglas de permitir y denegar y modos de permiso. Para los otros pasos:
- Hooks: ejecute código personalizado para permitir, denegar o modificar solicitudes de herramientas. Consulte Controlar la ejecución con hooks.
- Devolución de llamada canUseTool: solicite aprobación a los usuarios en tiempo de ejecución, cuando ningún paso anterior resuelve la llamada. Consulte Manejar aprobaciones e entrada del usuario.
Reglas de permitir y denegar
allowed_tools y disallowed_tools (TypeScript: allowedTools / disallowedTools) agregan entradas a las listas de reglas de permitir y denegar en el flujo de evaluación anterior. Si nombra una de las herramientas de seguimiento de tareas en allowed_tools, Claude Code también opta por la sesión. Cualquier otra herramienta no listada en allowed_tools sigue estando disponible para Claude, y una llamada a ella que necesita aprobación se descarta al modo de permiso. Las reglas de denegar se comportan de manera diferente dependiendo de si nombran una herramienta o delimitan un patrón dentro de una.
| Opción | Efecto |
|---|---|
allowed_tools=["Read", "Grep"] |
Read y Grep se aprueban automáticamente. Otras herramientas no listadas aquí aún existen, y las llamadas a ellas que necesitan aprobación se descartan al modo de permiso y canUseTool. |
disallowed_tools=["Bash"] |
La definición de la herramienta Bash se elimina de la solicitud. Claude no ve la herramienta y no puede intentarla. |
disallowed_tools=["Bash(rm *)"] |
Bash permanece disponible. Las llamadas que coinciden con rm * tal como está escrito se deniegan en cada modo de permiso, incluido bypassPermissions. Otras llamadas de Bash, incluidas /bin/rm, se descartan al modo de permiso. |
disallowed_tools=["*"] |
Cada definición de herramienta se elimina de la solicitud. Los patrones globales de nombres de herramientas se admiten en reglas de denegar: "*" coincide con cada herramienta y "mcp__*" coincide con cada herramienta MCP en todos los servidores. |
Las reglas de permitir aceptan patrones globales de nombres de herramientas solo después de un prefijo literal mcp__<server>__. El segmento del servidor debe estar libre de patrones globales para que la regla nombre un servidor específico que haya configurado: mcp__puppeteer__* coincide con cada herramienta del servidor puppeteer, y mcp__github__get_* coincide con sus herramientas get_. Una entrada sin ancla como allowed_tools=["*"] o allowed_tools=["mcp__*"] se ignora con una advertencia de inicio y no pre-aprueba nada.
Las reglas delimitadas para Read y Edit toman un patrón de ruta. Las reglas Edit(path) rigen todas las herramientas integradas que escriben archivos, incluidas Write y NotebookEdit; una regla Write(path) nunca es coincidida por las comprobaciones de permiso de archivo.
Use //path para una ruta del sistema de archivos absoluta: una regla de denegar de Edit(//secrets/**) bloquea escrituras en cualquier lugar bajo /secrets en el disco. Con una sola barra diagonal inicial, Edit(/secrets/**) se ancla en la fuente de la regla en su lugar. Para reglas pasadas a través de allowed_tools o disallowed_tools, eso significa el directorio de trabajo de la sesión, por lo que la regla no bloquea /secrets en el disco. Consulte Reglas de Read y Edit para las cuatro formas de anclaje y cómo se resuelven las reglas de archivos de configuración.
Para un agente bloqueado, empareje allowedTools con permissionMode: "dontAsk":
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};
Las herramientas listadas se aprueban, aparte de las acciones que ningún modo pre-aprueba, y cada otra llamada que solicitaría se deniega en su lugar. Las llamadas que no necesitan aprobación en modo default se ejecutan independientemente de si las lista, como comandos Bash de solo lectura, herramientas como Agent que no solicitan antes de ejecutarse, y lecturas de archivos dentro de sus directorios de trabajo. Para poner una herramienta fuera del alcance de Claude completamente, agregue su nombre simple a disallowedTools.
También puede configurar reglas de permitir, denegar y preguntar de forma declarativa en .claude/settings.json. Estas reglas se leen cuando la fuente de configuración project está habilitada, que lo está para las opciones predeterminadas de query(). Si establece setting_sources (TypeScript: settingSources) explícitamente, incluya "project" para que se apliquen. Consulte Configuración de permisos para la sintaxis de reglas.
Modos de permisos
Los modos de permisos proporcionan control global sobre cómo Claude utiliza las herramientas. Puede establecer el modo de permisos al llamar a query() o cambiarlo dinámicamente durante sesiones de transmisión.
Modos disponibles
El SDK admite estos modos de permisos:
| Modo | Descripción | Comportamiento de herramientas |
|---|---|---|
default |
Comportamiento de permisos estándar | Sin aprobaciones automáticas basadas en modo; las llamadas que necesitan aprobación y no coinciden con ninguna regla de permiso activan su devolución de llamada canUseTool |
dontAsk |
Denegar en lugar de preguntar | Cualquier llamada que de otro modo solicitaría confirmación se deniega. Las llamadas aprobadas por allowed_tools o reglas se ejecutan, al igual que las llamadas que no necesitan aprobación en modo default, como lecturas de archivos dentro de sus directorios de trabajo y llamadas a Agent. Las herramientas de conector que su organización estableció en ask y las herramientas que requieren interacción del usuario se deniegan incluso si las ha preaprobado, al igual que las eliminaciones rm y rmdir dirigidas a una ruta crítica. canUseTool nunca se llama |
acceptEdits |
Aceptar automáticamente ediciones de archivos | Las ediciones de archivos y operaciones del sistema de archivos (mkdir, rm, mv, etc.) se aprueban automáticamente |
bypassPermissions |
Omitir comprobaciones de permisos | Las herramientas se ejecutan sin solicitudes de permisos, excepto para las acciones que ningún modo aprueba automáticamente. Úselo con precaución |
plan |
Modo de planificación | Claude explora y planifica sin editar sus archivos fuente; las ediciones de archivos nunca se aprueban automáticamente y se solicitan a través de su devolución de llamada canUseTool |
auto |
Aprobaciones clasificadas por modelo | Un clasificador de modelo aprueba o deniega solicitudes de permisos. Consulte Modo Auto para disponibilidad |
Establecer modo de permisos
Puede establecer el modo de permisos una vez al iniciar una consulta, o cambiarlo dinámicamente mientras la sesión está activa.
Pase permission_mode (Python) o permissionMode (TypeScript) al crear una consulta. Este modo se aplica durante toda la sesión a menos que se cambie dinámicamente.
import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions
async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default", # Set the mode here
),
):
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
for await (const message of query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Set the mode here
}
})) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
Llame a set_permission_mode() (Python) o setPermissionMode() (TypeScript) para cambiar el modo a mitad de sesión. El nuevo modo entra en vigor inmediatamente para todas las solicitudes de herramientas posteriores. Esto le permite comenzar de forma restrictiva y flexibilizar los permisos a medida que aumenta la confianza, por ejemplo, cambiar a acceptEdits después de revisar el enfoque inicial de Claude.
import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions
async def main():
async with ClaudeSDKClient(
options=ClaudeAgentOptions(
permission_mode="default", # Start in default mode
)
) as client:
await client.query("Help me refactor this code")
# Change mode dynamically mid-session
await client.set_permission_mode("acceptEdits")
# Process messages with the new permission mode
async for message in client.receive_response():
if hasattr(message, "result"):
print(message.result)
asyncio.run(main())
import { query } from "@anthropic-ai/claude-agent-sdk";
async function main() {
const q = query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Start in default mode
}
});
// Change mode dynamically mid-session
await q.setPermissionMode("acceptEdits");
// Process messages with the new permission mode
for await (const message of q) {
if ("result" in message) {
console.log(message.result);
}
}
}
main();
Detalles del modo
Modo de aceptación de ediciones (`acceptEdits`)
Aprueba automáticamente operaciones de archivo para que Claude pueda editar código sin solicitar confirmación. Otras herramientas (como comandos Bash que no son operaciones del sistema de archivos) aún requieren permisos normales.
Operaciones aprobadas automáticamente:
- Ediciones de archivos (herramientas Edit, Write)
- Comandos del sistema de archivos:
mkdir,touch,rm,rmdir,mv,cp,sed
Ambos se aplican solo a rutas dentro del directorio de trabajo o additionalDirectories. En modo acceptEdits, Claude Code no aprueba automáticamente la solicitud cuando Claude:
- Trabaja en una ruta fuera de ese alcance
- Escribe en una ruta protegida
- Elimina una ruta crítica con
rmormdir
Úselo cuando: confíe en las ediciones de Claude y desee una iteración más rápida, como durante la creación de prototipos o cuando trabaja en un directorio aislado.
Modo no preguntar (`dontAsk`)
Convierte cualquier solicitud de permiso en una denegación, sin llamar a canUseTool. Las herramientas preaprobadas por allowed_tools, reglas de permiso en settings.json o un hook se ejecutan normalmente, al igual que las llamadas que no necesitan aprobación en modo default, como lecturas de archivos dentro de sus directorios de trabajo y llamadas a Agent. Las herramientas de conector que su organización estableció en ask, las herramientas que requieren interacción del usuario y las eliminaciones rm y rmdir dirigidas a una ruta crítica se deniegan incluso cuando una regla de permiso coincide. Un permiso de hook PreToolUse tampoco borra una eliminación de ruta crítica.
Úselo cuando: desee una superficie de herramientas fija y explícita para un agente sin interfaz y prefiera una denegación definitiva sobre la dependencia silenciosa de que canUseTool esté ausente.
Modo de omisión de permisos (`bypassPermissions`)
Aprueba automáticamente los usos de herramientas sin solicitar confirmación, excepto los casos enumerados en la advertencia a continuación. Los hooks aún se ejecutan y pueden bloquear operaciones si es necesario.
Modo de planificación (`plan`)
Claude explora la base de código y produce un plan sin editar sus archivos fuente. Las herramientas de solo lectura se ejecutan como lo hacen en el modo de permisos default.
Las ediciones de archivos nunca se aprueban automáticamente en modo de planificación, incluso cuando una regla de permiso coincide. En su lugar, se solicitan a través de su devolución de llamada canUseTool. En Claude Code v2.1.212 o posterior, los comandos de shell que modifican archivos, como touch y rm, llegan a su devolución de llamada canUseTool de la misma manera.
Claude puede usar AskUserQuestion para aclarar requisitos antes de finalizar el plan. Consulte Manejar aprobaciones e entrada del usuario para manejar estas solicitudes.
Úselo cuando: desee que Claude proponga cambios sin ejecutarlos, como durante la revisión de código o cuando necesita 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: ejecute código personalizado en puntos clave del ciclo de vida del agente
- Reglas de permisos: reglas declarativas de permitir/denegar en
settings.json