Configurer les permissions

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

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

[!NOTE]

Si vous chargez un plugin qui contient un mod, consultez où se situent les décisions d'un mod parmi les règles et les hooks.

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

1. Hooks

Exécutez d'abord les hooks. Un hook peut refuser l'appel catégoriquement ou le transmettre. Un hook qui retourne allow ne contourne pas les règles de refus et de demande ci-dessous ; celles-ci sont évaluées indépendamment du résultat du hook.

Un hook PreToolUse qui retourne allow ne peut pas non plus approuver une commande rm ou rmdir dont Claude Code reconnaît la cible comme un chemin critique, par exemple rm -rf ~. Pour savoir ce que fait ce allow en mode plan, consultez Approbations par hook en mode plan.

2. Règles de refus

Si une règle de refus provenant de disallowed_tools ou de settings.json correspond, l'appel est refusé et canUseTool n'est pas appelé, même en mode bypassPermissions et même lorsqu'un hook a retourné allow.

Dans le SDK TypeScript, si vous définissez la permission_policy d'un outil personnalisé sur always_deny, un appel à cet outil est refusé à cette étape.

3. Règles de demande

Vérifiez les règles ask à partir de settings.json. Si une règle de demande correspond, l'appel passe à votre callback canUseTool pour confirmation, même en mode bypassPermissions.

Les outils qui nécessitent une interaction utilisateur se comportent de la même manière : AskUserQuestion et les outils MCP dont le serveur définit _meta["anthropic/requiresUserInteraction"] passent toujours au callback, même lorsqu'une règle allow correspond. En mode dontAsk, les deux cas sont refusés à la place, car ce mode ne demande jamais. L'annotation MCP nécessite Claude Code v2.1.199 ou ultérieur.

Les outils du connecteur claude.ai que votre organisation a définis sur ask quittent également le flux à cette étape. Chaque appel passe au callback, même en mode bypassPermissions et même lorsqu'une règle allow correspond. Le callback reçoit la raison Your organization requires approval for this tool. En mode dontAsk, l'appel est refusé à la place, car ce mode ne demande jamais.

Dans le SDK TypeScript, si vous définissez la permission_policy d'un outil personnalisé sur always_ask, aucune règle allow n'approuve ses appels, pas même une entrée allowedTools. En mode dontAsk, Claude Code refuse ces appels, et en mode auto, plan ou bypassPermissions, il peut les approuver avant l'exécution de votre callback.

4. Mode de permission

Appliquez le mode de permission actif :

• En mode bypassPermissions, Claude Code approuve tout ce qui atteint cette étape sauf les suppressions de chemins critiques reconnues et les commandes Bash signalées Dangerous rm operation not ruled out, qui passent à la place.
  • Pour exécuter ces suppressions sans demande de permission, consultez Désactiver la demande de permission pour les suppressions de chemins critiques.
• En mode acceptEdits, Claude Code approuve les opérations de fichier listées sous Mode Accept edits.
• En mode plan, Claude Code envoie les outils de modification de fichier à votre callback canUseTool indépendamment des règles allow.
• Dans les autres modes, la demande passe.

5. 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é. Un appel que l'outil approuve de lui-même est résolu à cette étape aussi, sans règle nécessaire : par exemple une lecture de fichier dans vos répertoires de travail ou une commande Bash en lecture seule.

Les suppressions de chemins critiques reconnues ne sont pas approuvées par une règle allow, et les commandes signalées Dangerous rm operation not ruled out ne sont pas approuvées par une règle Bash ou Bash(*). Qu'elles atteignent ensuite votre callback dépend du mode de permission : dans une session Agent SDK en mode auto, par exemple, Claude Code les refuse par défaut sans l'appeler. Le tableau des modes pour les chemins critiques liste ce que chaque mode fait avec elles.

Une règle allow n'approuve pas une lecture depuis un chemin réseau.

6. Callback canUseTool

Si aucune des étapes ci-dessus ne l'a résolu, appelez votre callback canUseTool pour une décision. En mode dontAsk, cette étape est ignorée et l'outil est refusé, bien qu'un mod que vous avez installé puisse toujours approuver certains de ces appels.

Dans le SDK TypeScript, si vous définissez permissionPrompts: 'none', votre callback n'est pas appelé à cette étape. Un hook PermissionRequest a toujours une chance de décider, et s'il ne le fait pas, Claude Code refuse l'appel. L'option nécessite Claude Code v2.1.259 ou ultérieur.

Si vous transmettez un callback canUseTool dans une configuration où le SDK TypeScript s'attend à ce que l'ordre d'évaluation approuve automatiquement les appels avant que le callback ne soit consulté, le SDK émet un avertissement de processus Node.js une fois lorsque la requête est construite. Le code de l'avertissement est CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Deux configurations le déclenchent :

• permissionMode: 'bypassPermissions' : le texte de l'avertissement commence par canUseTool will not be invoked: permissionMode 'bypassPermissions'. Les appels d'outils sont approuvés avant que canUseTool ne soit consulté, de sorte que votre callback ne s'exécute que pour quelques appels, tels que ceux listés sous Mode Bypass permissions. Pour vérifier également les appels approuvés, placez les vérifications de votre callback dans un hook PreToolUse
• Une entrée allowedTools qui n'est qu'un nom d'outil, comme "Read" : l'avertissement liste chacune de ces entrées après canUseTool will not be invoked for:. Les appels à un outil listé sont approuvés avant que canUseTool ne soit consulté, à l'exception des appels qu'une règle allow n'approuve jamais. Pour que votre callback s'exécute pour les appels d'un outil listé qui nécessitent une approbation, supprimez l'entrée de cet outil de allowedTools

Les entrées avec un spécificateur comme Bash(ls *) et le mode acceptEdits ne le déclenchent pas, et les règles d'autorisation provenant de fichiers de paramètres ne sont pas visibles pour la vérification.

L'avertissement ne bloque aucun appel et ne modifie aucune option. Si votre callback reçoit déjà chaque appel que vous souhaitez vérifier, laissez votre configuration telle quelle. Pour journaliser l'avertissement, écoutez avec process.on('warning', ...) et faites correspondre le code CLAUDE_SDK_CAN_USE_TOOL_SHADOWED.

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. Voir Contrôler l'exécution avec les hooks.
• Callback canUseTool : invitez les utilisateurs à approuver au moment de l'exécution, lorsqu'aucune étape antérieure ne résout l'appel. Voir Gérer les approbations et l'entrée 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. Si vous nommez l'un des outils de suivi des tâches dans allowed_tools, Claude Code active également ces outils pour la session. Tout autre outil non listé dans allowed_tools reste disponible pour Claude, et un appel à celui-ci qui nécessite une approbation tombe dans le 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 et n'approuve automatiquement rien.

Les règles délimitées pour Read et Edit prennent un motif de chemin. Les règles Edit(path) régissent tous les outils intégrés qui écrivent des fichiers, y compris Write et NotebookEdit ; une règle Write(path) n'est jamais mise en correspondance par les vérifications de permission de fichier.

Utilisez //path pour un chemin du système de fichiers absolu : une règle de refus de Edit(//secrets/**) bloque les écritures n'importe où sous /secrets sur le disque. Avec une seule barre oblique, Edit(/secrets/**) s'ancre à la source de la règle à la place. Pour les règles transmises via allowed_tools ou disallowed_tools, cela signifie le répertoire de travail de la session, donc la règle ne bloque pas /secrets sur le disque. Voir Règles Read et Edit pour les quatre formes d'ancrage et comment les règles des fichiers de paramètres se résolvent.

[!WARNING]

Les outils approuvés automatiquement n'atteignent jamais canUseTool. Un appel d'outil approuvé à n'importe quelle étape antérieure, par acceptEdits ou bypassPermissions, ou par une règle d'autorisation, ignore votre rappel canUseTool, donc les vérifications de permission que vous y mettez sont silencieusement contournées pour cet outil.

Si des appels à un outil présent dans allowed_tools atteignent toujours votre rappel canUseTool, ou sont refusés en mode dontAsk, vérifiez s'il s'agit de lectures depuis des chemins réseau ou de l'un des appels suivants. Aucune règle d'autorisation n'approuve ces appels. En mode dontAsk, qui ne demande jamais, Claude Code les refuse sans appeler canUseTool, et dans les autres modes de permission, vous les gérez comme l'indique chaque élément :

• AskUserQuestion, les outils MCP marqués _meta["anthropic/requiresUserInteraction"], et les outils connecteur que votre organisation a définis sur ask : répondez-y dans le rappel. Gérer les questions de clarification montre comment répondre à AskUserQuestion, et un appel de connecteur arrive avec la raison Your organization requires approval for this tool

• Les outils personnalisés que votre application marque always_ask : décidez de l'appel dans le rappel. Pour que ces appels cessent d'arriver, modifiez la politique en cours de session. En mode auto, plan et bypassPermissions, l'appel peut à la place être approuvé avant le rappel, dans les cas listés sous Modes de permission pouvant approuver un appel always_ask

• Les suppressions de chemins critiques rm et rmdir reconnues : en mode default, acceptEdits et bypassPermissions, autorisez ou refusez la suppression dans le rappel, où decisionReason commence par Dangerous rm. Pour les modes auto et plan, voir Suppressions de chemins critiques dans chaque mode de permission. La vérification qui reconnaît ces suppressions peut manquer certaines commandes

• Nom nu : une entrée comme Read ou mcp__github__get_issue approuve automatiquement chaque appel à cet outil, en dehors des actions qu'aucun mode n'approuve automatiquement et des lectures depuis des chemins réseau.

• Règle délimitée : une entrée comme Bash(npm test *) approuve automatiquement uniquement les appels correspondants, et les autres appels Bash qui nécessitent une approbation tombent toujours dans le rappel.

Pour les vérifications qui doivent s'exécuter sur chaque appel d'outil, utilisez un hook PreToolUse : les hooks s'exécutent avant chaque autre étape, et un refus de hook s'applique même en mode bypassPermissions.

Pour un agent verrouillé, associez allowedTools avec permissionMode: "dontAsk" :

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

Les appels Read, Glob et Grep listés sont approuvés, en dehors des actions qu'aucun mode n'approuve automatiquement et des lectures depuis des chemins réseau. Chaque autre appel qui déclencherait une demande est refusé à la place, bien qu'un mod que vous avez installé puisse toujours approuver certains de ces appels.

Les appels qui ne nécessitent aucune approbation en mode default s'exécutent que vous les listiez ou non. Ils incluent les commandes Bash en lecture seule, les outils comme Agent qui ne demandent pas avant d'exécuter, et les lectures de fichiers dans vos répertoires de travail. Pour masquer entièrement un outil intégré à Claude plutôt que de refuser ses appels, ajoutez son nom nu à disallowedTools.

[!WARNING]

allowed_tools ne contraint pas bypassPermissions. allowed_tools pré-approuve les outils que vous listez. Les autres outils non listés ne sont pas mis en correspondance par aucune règle d'autorisation et tombent dans le mode de permission, où bypassPermissions les approuve. Définir allowed_tools=["Read"] aux côtés de permission_mode="bypassPermissions" approuve toujours chaque outil, y compris Bash, Write, et Edit. Si vous avez besoin de bypassPermissions mais que vous voulez que des outils spécifiques 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 qu'elle est pour les options query() par défaut. Si vous définissez setting_sources (TypeScript : settingSources) explicitement, incluez "project" pour qu'elles s'appliquent. Voir Paramètres de permission pour la syntaxe des règles.

Modes de permission

Les modes de permission offrent 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.

Avec Claude Code v2.1.302 ou ultérieur, votre application démarre en mode default, sauf si vous définissez un mode de permission ou si elle en obtient un via permissions.defaultMode dans ses fichiers de paramètres. En mode default, Claude Code refuse tout appel d'outil nécessitant une approbation, sauf si vous l'approuvez via une règle d'autorisation, un hook, un rappel canUseTool ou un outil de demande de permission. Si des appels d'outils sont refusés, consultez Appels d'outils refusés dans claude -p et les exécutions de l'Agent SDK.

Modes disponibles

Le SDK prend en charge ces modes de permission :

[!WARNING]

Héritage des sous-agents : Si votre session principale est en mode plan, un sous-agent dont l'AgentDefinition définit permissionMode: "acceptEdits" s'exécute tout de même en mode plan. Les appels Edit et Write de ce sous-agent sur vos fichiers source sont toujours transmis à votre rappel canUseTool. Le mode plan s'applique également aux sous-agents que vous définissez, de sorte que confier du travail à l'un d'eux ne permet pas de contourner la revue préalable du plan.

Le sous-agent hérite de plan, acceptEdits, auto ou bypassPermissions de la session principale, et sous une session principale en mode default ou dontAsk, il s'exécute dans le mode que vous définissez. Même dans ce cas, Claude Code n'applique jamais une valeur "bypassPermissions", et n'applique une valeur "auto" que lorsque le mode auto est disponible pour ce sous-agent. L'exception bypassPermissions nécessite Claude Code v2.1.267 ou ultérieur.

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. Les actions qu'aucun mode n'approuve automatiquement s'appliquent toujours.

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.

[tab] Au moment de la requête

Passez permission_mode (Python) ou permissionMode (TypeScript) lors de la création d'une requête.

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

[tab] Pendant le streaming

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

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)

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, rmdir, mv, cp, sed

Les deux s'appliquent uniquement aux chemins à l'intérieur du répertoire de travail ou de additionalDirectories. En mode acceptEdits, Claude Code n'approuve pas automatiquement la demande lorsque Claude :

• Travaille sur un chemin en dehors de cette portée
• Écrit dans un chemin protégé
• Supprime avec rm ou rmdir un chemin que Claude Code reconnaît comme un chemin critique
• Exécute touch avec, par exemple, une option, un glob, ou un préfixe timeout 5 ou LANG=C

À 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 ne pas demander (dontAsk)

Convertit toute demande de permission en refus, sans appeler canUseTool, bien qu'un mod que vous avez installé puisse encore approuver certains de ces appels. Les outils pré-approuvés par allowed_tools, les règles d'autorisation settings.json ou un hook s'exécutent normalement. Les appels qui ne nécessitent pas d'approbation en mode default s'exécutent également, tels que les lectures de fichiers dans vos répertoires de travail et les appels à Agent.

Ces appels sont refusés même lorsqu'une règle d'autorisation correspond :

• Les outils connecteur que votre organisation a définis sur ask
• Les outils qui nécessitent une interaction utilisateur, tels que AskUserQuestion et les outils MCP dont le serveur définit _meta["anthropic/requiresUserInteraction"]
• Les outils personnalisés dont votre application définit la permission_policy sur always_ask
• Les lectures depuis des chemins réseau
• Les suppressions de chemins critiques reconnues

Si votre hook PreToolUse renvoie allow pour une suppression de chemin critique reconnue, une lecture depuis un chemin réseau ou un appel à un outil marqué always_ask, l'appel est tout de même refusé. La vérification qui reconnaît ces suppressions peut manquer certaines commandes.

À utiliser quand : vous souhaitez une surface d'outils 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 contournement des permissions (bypassPermissions)

Approuve automatiquement les utilisations d'outils sans demander, sauf les actions qu'aucun mode n'approuve automatiquement. Les hooks s'exécutent toujours et peuvent bloquer les opérations si nécessaire. Sur Linux et macOS, Claude Code refuse de démarrer dans ce mode en tant que root ou sous sudo en dehors d'un sandbox reconnu, et la requête échoue avant le premier tour.

[!WARNING]

À 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. Chaque outil est approuvé, pas seulement ceux que vous avez énumérés. Ces contrôles s'appliquent toujours :

• Les règles de refus, les règles explicites ask et les hooks sont évalués avant la vérification du mode et peuvent toujours bloquer un outil.
• Les outils connecteur que votre organisation a définis sur ask, les outils qui nécessitent une interaction utilisateur et les suppressions de chemins critiques reconnues reviennent toujours à votre rappel canUseTool. La vérification qui reconnaît ces suppressions peut manquer certaines commandes, et vous pouvez désactiver la demande de permission pour la suppression de chemins critiques. En dehors d'une session cloud, les appels aux outils personnalisés que votre application marque always_ask reviennent également au rappel.
• Les protections de messagerie inter-sessions s'appliquent toujours.

Mode de planification (plan)

Claude explore la base de code et produit un plan sans modifier vos fichiers source. Les modifications de fichiers ne sont jamais approuvées automatiquement en mode plan, même lorsqu'une règle d'autorisation correspond ou qu'un hook PreToolUse renvoie allow. Elles demandent via votre rappel canUseTool à la place.

Tant que le mode auto est disponible pour la session, les commandes que Claude exécute pendant la planification n'atteignent pas votre rappel par défaut, car le modèle classifieur qu'utilise le mode auto les examine à la place. Lorsque cet examen est activé, le classifieur peut également approuver des appels en lecture seule qui atteindraient autrement votre rappel, comme un appel WebFetch sans règle d'autorisation.

[!NOTE]

Dans le SDK TypeScript, si vous définissez allowDangerouslySkipPermissions: true aux côtés de permissionMode: 'plan', les modifications de fichiers atteignent toujours votre rappel canUseTool. Pour faire passer plus tard une session qui démarre en mode plan à bypassPermissions avec setPermissionMode(), vous devez définir allowDangerouslySkipPermissions dès le départ.

Claude peut utiliser AskUserQuestion pour clarifier les exigences avant de finaliser le plan. Voir 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 révision de code ou lorsque vous devez approuver les modifications avant qu'elles ne soient apportées.

Mode auto (auto)

Un modèle classifieur examine les actions telles que les commandes shell et les requêtes réseau avant leur exécution, et autorise ou bloque chacune de celles qu'il examine. Pour connaître les modèles et les fournisseurs requis par le mode auto ainsi que l'ordre dans lequel il évalue les actions, consultez Éliminer les demandes de permission avec le mode auto.

Si vous basculez une session en mode auto vers un modèle que le mode auto ne prend pas en charge, à l'aide de set_model(), setModel() ou applyFlagSettings(), la session passe en mode default :

• Ce que vous voyez : un message system avec le sous-type status et permissionMode défini sur "default", que le SDK TypeScript type comme SDKStatusMessage. À partir de là, les appels qui nécessitent une approbation et ne correspondent à aucune règle d'autorisation atteignent votre rappel canUseTool.
• Pour revenir au mode auto : passez à un modèle pris en charge, puis appelez set_permission_mode("auto") ou setPermissionMode("auto"). Si vous revenez au modèle précédent sans effectuer cet appel, la session reste en mode default. Tant que le modèle non pris en charge est actif, l'appel échoue avec Cannot set permission mode to auto: auto mode unavailable for this model.

Le passage au mode default après un appel à set_model(), setModel() ou applyFlagSettings() nécessite Claude Code v2.1.299 ou ultérieur.

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écuter du code personnalisé aux points clés du cycle de vie de l'agent
• Règles de permission : règles déclaratives d'autorisation/refus dans settings.json