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:

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. 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. Las reglas de permitir solo afectan la aprobación: una herramienta no listada en allowed_tools sigue estando disponible para Claude y 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.

Para un agente bloqueado, empareje allowedTools con permissionMode: "dontAsk". Las herramientas listadas se aprueban; cualquier otra cosa se deniega directamente en lugar de solicitar:

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

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 permiso

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

Modos disponibles

El SDK admite estos modos de permiso:

Establecer modo de permiso

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

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();

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 aceptar 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 archivo (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. Las rutas fuera de ese alcance y las escrituras en rutas protegidas aún solicitan.

Usar cuando: confía en las ediciones de Claude y desea 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. Las herramientas pre-aprobadas por allowed_tools, reglas de permitir de settings.json o un hook se ejecutan normalmente. Todo lo demás se deniega sin llamar a canUseTool.

Usar cuando: desea una superficie de herramienta fija y explícita para un agente sin interfaz y prefiere una denegación dura sobre la dependencia silenciosa de que canUseTool esté ausente.

Modo de omitir permisos (`bypassPermissions`)

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

Modo de planificación (`plan`)

Restringe Claude a herramientas de solo lectura. Claude puede leer archivos y ejecutar comandos de shell de solo lectura para explorar la base de código pero no edita sus archivos fuente. Claude puede usar AskUserQuestion para aclarar requisitos antes de finalizar el plan. Consulte Manejar aprobaciones e entrada del usuario para manejar estas solicitudes.

Usar cuando: desea 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