Configurer les permissions

Contrôlez comment votre agent utilise les outils avec les modes de permission, les hooks et les règles de permission/refus déclaratives.

Le Claude Agent SDK fournit des contrôles de permission pour gérer la façon dont Claude utilise les outils. Utilisez les modes de permission et les règles pour définir ce qui est autorisé automatiquement, et le callback canUseTool pour gérer tout le reste à l'exécution.

Comment les permissions sont évaluées

Lorsque Claude demande un outil, le SDK vérifie les permissions dans cet ordre :

Cette page se concentre sur les règles d'autorisation et de refus et les modes de permission. Pour les autres étapes :

• Hooks : exécutez du code personnalisé pour autoriser, refuser ou modifier les demandes d'outils. Consultez Contrôler l'exécution avec les hooks.
• Callback canUseTool : invitez les utilisateurs à approuver à l'exécution, lorsqu'aucune étape antérieure ne résout l'appel. Consultez Gérer les approbations et les entrées utilisateur.

Règles d'autorisation et de refus

allowed_tools et disallowed_tools (TypeScript : allowedTools / disallowedTools) ajoutent des entrées aux listes de règles d'autorisation et de refus dans le flux d'évaluation ci-dessus. Les règles d'autorisation affectent uniquement l'approbation : un outil non listé dans allowed_tools est toujours disponible pour Claude et passe au mode de permission. Les règles de refus se comportent différemment selon qu'elles nomment un outil ou délimitent un motif au sein de celui-ci.

Les règles d'autorisation acceptent les globs de noms d'outils uniquement après un préfixe littéral mcp__<server>__. Le segment serveur doit être sans glob afin que la règle nomme un serveur spécifique que vous avez configuré : mcp__puppeteer__* correspond à chaque outil du serveur puppeteer, et mcp__github__get_* correspond à ses outils get_. Une entrée non ancrée comme allowed_tools=["*"] ou allowed_tools=["mcp__*"] est ignorée avec un avertissement au démarrage et n'auto-approuve rien.

Pour un agent verrouillé, associez allowedTools avec permissionMode: "dontAsk". Les outils listés sont approuvés ; tout le reste est refusé directement au lieu de demander :

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

Vous pouvez également configurer les règles d'autorisation, de refus et de demande de manière déclarative dans .claude/settings.json. Ces règles sont lues lorsque la source de paramètre project est activée, ce qui est le cas pour les options query() par défaut. Si vous définissez setting_sources (TypeScript : settingSources) explicitement, incluez "project" pour qu'elles s'appliquent. Consultez Paramètres de permission pour la syntaxe des règles.

Modes de permission

Les modes de permission fournissent un contrôle global sur la façon dont Claude utilise les outils. Vous pouvez définir le mode de permission lors de l'appel de query() ou le modifier dynamiquement pendant les sessions de streaming.

Modes disponibles

Le SDK supporte ces modes de permission :

Définir le mode de permission

Vous pouvez définir le mode de permission une fois au démarrage d'une requête, ou le modifier dynamiquement pendant que la session est active.

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

Détails des modes

Mode d'acceptation des modifications (`acceptEdits`)

Auto-approuve les opérations de fichiers afin que Claude puisse modifier le code sans demander. Les autres outils (comme les commandes Bash qui ne sont pas des opérations du système de fichiers) nécessitent toujours des permissions normales.

Opérations auto-approuvées :

• Modifications de fichiers (outils Edit, Write)
• Commandes du système de fichiers : mkdir, touch, rm, rmdir, mv, cp, sed

Les deux s'appliquent uniquement aux chemins à l'intérieur du répertoire de travail ou de additionalDirectories. Les chemins en dehors de cette portée et les écritures vers des chemins protégés demandent toujours.

À utiliser quand : vous faites confiance aux modifications de Claude et voulez une itération plus rapide, par exemple lors du prototypage ou lorsque vous travaillez dans un répertoire isolé.

Mode de non-demande (`dontAsk`)

Convertit toute invite de permission en refus. Les outils pré-approuvés par allowed_tools, les règles d'autorisation de settings.json ou un hook s'exécutent normalement. Tout le reste est refusé sans appeler canUseTool.

À utiliser quand : vous voulez une surface d'outil fixe et explicite pour un agent sans interface et préférez un refus catégorique à une dépendance silencieuse à l'absence de canUseTool.

Mode de contournement des permissions (`bypassPermissions`)

Auto-approuve tous les usages d'outils sans invites. Les hooks s'exécutent toujours et peuvent bloquer les opérations si nécessaire.

Mode de planification (`plan`)

Claude explore la base de code et produit un plan sans modifier vos fichiers source. Les outils en lecture seule s'exécutent comme en mode par défaut. Les modifications de fichiers ne sont jamais auto-approuvées en mode plan, même lorsqu'une règle d'autorisation correspond. Elles demandent via votre callback canUseTool à la place. Claude peut utiliser AskUserQuestion pour clarifier les exigences avant de finaliser le plan. Consultez Gérer les approbations et les entrées utilisateur pour gérer ces invites.

À utiliser quand : vous voulez que Claude propose des modifications sans les exécuter, par exemple lors d'une révision de code ou lorsque vous devez approuver les modifications avant qu'elles ne soient apportées.

Ressources connexes

Pour les autres étapes du flux d'évaluation des permissions :

• Gérer les approbations et les entrées utilisateur : invites d'approbation interactives et questions de clarification
• Guide des hooks : exécutez du code personnalisé à des points clés du cycle de vie de l'agent
• Règles de permission : règles d'autorisation/refus déclaratives dans settings.json