Configurer les permissions

Le Claude Agent SDK fournit des contrôles de permission pour gérer comment 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.

Cette page couvre les modes de permission et les règles. Pour créer des flux d'approbation interactifs où les utilisateurs approuvent ou refusent les demandes d'outils à l'exécution, consultez Gérer les approbations et les entrées utilisateur.

Comment les permissions sont évaluées

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

Hooks
Exécutez d'abord les hooks, qui peuvent autoriser, refuser ou continuer à l'étape suivante
Règles de permission
Vérifiez les règles définies dans settings.json dans cet ordre : d'abord les règles deny (bloquer indépendamment des autres règles), puis les règles allow (autoriser si correspondance), puis les règles ask (demander l'approbation). Ces règles déclaratives vous permettent de pré-approuver, bloquer ou exiger une approbation pour des outils spécifiques sans écrire de code.
Mode de permission
Appliquez le mode de permission actif (bypassPermissions, acceptEdits, dontAsk, etc.)
Callback canUseTool
Si non résolu par les règles ou les modes, appelez votre callback canUseTool pour une décision

Diagramme du flux d'évaluation des permissions

Cette page se concentre sur les modes de permission (étape 3), la configuration statique qui contrôle le comportement par défaut. 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.
Règles de permission : configurez les règles déclaratives d'autorisation/refus dans settings.json. Consultez Paramètres de permission.
Callback canUseTool : invitez les utilisateurs à approuver à l'exécution. Consultez Gérer les approbations et les entrées utilisateur.

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 :

Mode	Description	Comportement des outils
`default`	Comportement de permission standard	Pas d'approbations automatiques ; les outils non correspondants déclenchent votre callback `canUseTool`
`acceptEdits`	Accepter automatiquement les modifications de fichiers	Les modifications de fichiers et les opérations du système de fichiers (`mkdir`, `rm`, `mv`, etc.) sont automatiquement approuvées
`bypassPermissions`	Contourner tous les contrôles de permission	Tous les outils s'exécutent sans invites de permission (à utiliser avec prudence)
`plan`	Mode de planification	Pas d'exécution d'outils ; Claude planifie sans apporter de modifications

Héritage des sous-agents : Lors de l'utilisation de bypassPermissions, tous les sous-agents héritent de ce mode et il ne peut pas être remplacé. Les sous-agents peuvent avoir des invites système différentes et un comportement moins contraint que votre agent principal. L'activation de bypassPermissions leur accorde un accès système complet et autonome sans aucune invite d'approbation.

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.

Détails des modes

Mode d'acceptation des modifications (`acceptEdits`)

Approuve automatiquement 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 approuvées automatiquement :

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

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

Mode de contournement des permissions (`bypassPermissions`)

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

À utiliser avec une extrême prudence. Claude a un accès système complet dans ce mode. À utiliser uniquement dans des environnements contrôlés où vous faites confiance à toutes les opérations possibles.

Mode de planification (`plan`)

Empêche complètement l'exécution des outils. Claude peut analyser le code et créer des plans mais ne peut pas apporter de modifications. 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 souhaitez que Claude propose des modifications sans les exécuter, par exemple lors d'une revue 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éclaratives d'autorisation/refus dans settings.json

Comment les permissions sont évaluées

Modes de permission

Modes disponibles

Définir le mode de permission

Détails des modes

Mode d'acceptation des modifications (acceptEdits)

Mode de contournement des permissions (bypassPermissions)

Mode de planification (plan)

Ressources connexes

Mode d'acceptation des modifications (`acceptEdits`)

Mode de contournement des permissions (`bypassPermissions`)

Mode de planification (`plan`)