Configurer les permissions - Claude Code Docs

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.

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. Un hook peut refuser l’appel directement ou le transmettre. Un hook qui retourne allow ne saute pas les règles de refus et de demande ci-dessous ; celles-ci sont évaluées indépendamment du résultat du hook.

Règles de refus

Vérifiez les règles deny (à partir de disallowed_tools et settings.json). Si une règle de refus correspond, l’outil est bloqué, même en mode bypassPermissions. Les règles de nom simple comme Bash suppriment l’outil du contexte de Claude avant que cette évaluation ne commence, donc seules les règles délimitées comme Bash(rm *) sont vérifiées à cette étape.

Mode de permission

Appliquez le mode de permission actif. bypassPermissions approuve tout ce qui atteint cette étape. acceptEdits approuve les opérations de fichiers. Les autres modes passent au suivant.

Règles d'autorisation

Vérifiez les règles allow (à partir de allowed_tools et settings.json). Si une règle correspond, l’outil est approuvé.

Callback canUseTool

Si aucune des étapes ci-dessus ne résout le problème, appelez votre callback canUseTool pour une décision. En mode dontAsk, cette étape est ignorée et l’outil est refusé.

Diagramme du flux d'évaluation des permissions

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. 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.

Option	Effet
`allowed_tools=["Read", "Grep"]`	`Read` et `Grep` sont auto-approuvés. Les outils non listés ici existent toujours et passent au mode de permission et à `canUseTool`.
`disallowed_tools=["Bash"]`	La définition de l’outil `Bash` est supprimée de la requête. Claude ne voit pas l’outil et ne peut pas le tenter.
`disallowed_tools=["Bash(rm *)"]`	`Bash` reste disponible. Les appels correspondant à `rm *` sont refusés dans tous les modes de permission, y compris `bypassPermissions`. Les autres appels `Bash` passent au mode de permission.

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"
};

allowed_tools ne contraint pas bypassPermissions. allowed_tools pré-approuve uniquement les outils que vous listez. Les outils non listés ne correspondent à aucune règle d’autorisation et passent au mode de permission, où bypassPermissions les approuve. Définir allowed_tools=["Read"] avec permission_mode="bypassPermissions" approuve toujours tous les outils, y compris Bash, Write et Edit. Si vous avez besoin de bypassPermissions mais que vous voulez que certains outils soient bloqués, utilisez disallowed_tools.

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 :

Mode	Description	Comportement de l’outil
`default`	Comportement de permission standard	Pas d’auto-approbations ; les outils non appariés déclenchent votre callback `canUseTool`
`dontAsk`	Refuser au lieu de demander	Tout ce qui n’est pas pré-approuvé par `allowed_tools` ou les règles est refusé ; `canUseTool` n’est jamais appelé
`acceptEdits`	Auto-accepter 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	Les outils en lecture seule s’exécutent ; Claude analyse et planifie sans modifier vos fichiers source
`auto` (TypeScript uniquement)	Approbations classées par modèle	Un classificateur de modèle approuve ou refuse chaque appel d’outil. Consultez Mode Auto pour la disponibilité

Héritage des sous-agents : Lorsque le parent utilise bypassPermissions, acceptEdits ou auto, tous les sous-agents héritent de ce mode et il ne peut pas être remplacé par sous-agent. Les sous-agents peuvent avoir des invites système différentes et un comportement moins contraint que votre agent principal, donc hériter 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.

Au moment de la requête
Pendant le streaming

Passez permission_mode (Python) ou permissionMode (TypeScript) lors de la création d’une requête. Ce mode s’applique pour toute la session sauf s’il est modifié dynamiquement.

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

Appelez set_permission_mode() (Python) ou setPermissionMode() (TypeScript) pour modifier le mode en cours de session. Le nouveau mode prend effet immédiatement pour toutes les demandes d’outils suivantes. Cela vous permet de commencer de manière restrictive et d’assouplir les permissions à mesure que la confiance augmente, par exemple en passant à acceptEdits après avoir examiné l’approche initiale 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())

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.

À 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.allowed_tools ne contraint pas ce mode. Tous les outils sont approuvés, pas seulement ceux que vous avez listés. Les règles de refus (disallowed_tools), les règles ask explicites et les hooks sont évalués avant la vérification du mode et peuvent toujours bloquer un outil.

Mode de planification (`plan`)

Restreint Claude aux outils en lecture seule. Claude peut lire des fichiers et exécuter des commandes shell en lecture seule pour explorer la base de code mais ne modifie pas vos fichiers source. 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

​Comment les permissions sont évaluées

​Règles d’autorisation et de refus

​Modes de permission

​Modes disponibles

​Définir le mode de permission

​Détails des modes

​Mode d’acceptation des modifications (acceptEdits)

​Mode de non-demande (dontAsk)

​Mode de contournement des permissions (bypassPermissions)

​Mode de planification (plan)

​Ressources connexes

Comment les permissions sont évaluées

Règles d’autorisation et de refus

Modes de permission

Modes disponibles

Définir le mode de permission

Détails des modes

Mode d’acceptation des modifications (`acceptEdits`)

Mode de non-demande (`dontAsk`)

Mode de contournement des permissions (`bypassPermissions`)

Mode de planification (`plan`)

Ressources connexes