SpyBara
Go Premium

agent-sdk/permissions.md 2026-10-25 23:58 UTC to 2026-10-26 22:57 UTC

This page contains 49 additions and 20 deletions.

2026
Thu 1 23:59 Fri 9 23:02 Sat 10 23:01 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Mon 26 22:57 Tue 27 22:59 Fri 30 23:01

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

Diagramme du flux d'évaluation des permissions en six étapes correspondant aux étapes ci-dessus : une demande d'outil passe par les hooks, les règles de refus, les règles de demande, le mode de permission, les règles d'autorisation et canUseTool. Les hooks, les règles de refus et canUseTool peuvent router vers Blocked ; le contournement du mode de permission, les règles d'autorisation et canUseTool peuvent router vers Execute ; les règles de demande routent vers canUseTool.

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 :

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.

Option Effet
allowed_tools=["Read", "Grep"] Read et Grep sont approuvés automatiquement, à l'exception des lectures depuis des chemins réseau. Les autres outils non listés ici existent toujours, et les appels à ceux-ci qui nécessitent une approbation tombent dans le 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 * tel qu'écrit sont refusés dans tous les modes de permission, y compris bypassPermissions. Les autres appels Bash, y compris /bin/rm, tombent dans le mode de permission.
disallowed_tools=["*"] Chaque définition d'outil est supprimée de la requête. Les globs de noms d'outils sont pris en charge dans les règles de refus : "*" correspond à chaque outil et "mcp__*" correspond à chaque outil MCP sur tous les serveurs.

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 :

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 :

Mode Description Comportement des outils
default Comportement de permission standard Pas d'approbations automatiques basées sur le mode ; les appels qui nécessitent une approbation et ne correspondent à aucune règle d'autorisation déclenchent votre rappel canUseTool
dontAsk Refuser au lieu de demander Tout appel qui déclencherait autrement une demande est refusé sans appeler canUseTool, bien qu'un mod que vous avez installé puisse encore approuver certains de ces appels. Les appels approuvés par allowed_tools ou par les règles d'autorisation de settings.json s'exécutent, tout comme les appels qui ne nécessitent pas d'approbation en mode default. Certains appels, tels que les lectures depuis des chemins réseau, sont refusés même lorsque allowed_tools ou une règle d'autorisation leur correspond. Pour la liste, consultez Mode ne pas demander
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 les vérifications de permission Les outils s'exécutent sans demandes de permission, sauf pour les actions qu'aucun mode n'approuve automatiquement et, en dehors d'une session cloud, les outils personnalisés que votre application marque always_ask. À utiliser avec prudence
plan Mode de planification Claude explore et planifie sans modifier vos fichiers source ; les modifications de fichiers ne sont jamais approuvées automatiquement et demandent via votre rappel canUseTool
auto Approbations classées par le modèle Un classificateur de modèle examine les actions telles que les commandes shell et les demandes réseau, en approuvant ou en bloquant chacune qu'il examine. Voir Mode Auto pour la disponibilité et l'ordre de décision

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

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

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 :

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 :

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 :