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 :
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. Un hook PreToolUse allow ne peut pas non plus approuver une suppression rm ou rmdir ciblant un chemin critique.
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.
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 d'autorisation 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 d'autorisation 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.
Mode de permission
Appliquez le mode de permission actif :
- En mode
bypassPermissions, Claude Code approuve tout ce qui atteint cette étape sauf les suppressionsrmetrmdirciblant un chemin critique, qui passent à la place. - En mode
acceptEdits, Claude Code approuve les opérations de fichiers listées sous Mode d'acceptation des modifications. - En mode
plan, Claude Code achemine les outils d'édition de fichiers et d'écriture shell vers votre callbackcanUseToolindépendamment des règles d'autorisation, donc les opérations d'écriture ne peuvent pas être approuvées automatiquement lors de la planification. - Dans les autres modes, la demande passe 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é. Un appel que l'outil approuve de lui-même est également résolu à cette étape, 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 rm et rmdir ciblant un chemin critique ne sont jamais approuvées par une règle d'autorisation : elles atteignent votre callback dans les modes qui demandent, vont au classificateur en mode auto sur Claude Code v2.1.218 ou ultérieur, et sont refusées en mode dontAsk.
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é.
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 du 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', qui approuve automatiquement chaque appel qui atteint l'étape du mode de permission à part les actions qu'aucun mode n'approuve automatiquement- Chaque entrée
allowedToolssimple comme"Read", qui approuve automatiquement cet outil entier avant que le callback ne soit consulté, à part les actions qu'aucun mode n'approuve automatiquement
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 des fichiers de paramètres ne sont pas visibles pour la vérification.
Écoutez avec process.on('warning', ...) et faites correspondre le code pour le journaliser ou le supprimer. Pour contrôler chaque appel d'outil indépendamment du mode et des règles, utilisez plutôt un hook PreToolUse.
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. Si vous nommez l'un des outils de suivi des tâches dans allowed_tools, Claude Code opte également la session. Tout autre outil non listé dans allowed_tools est toujours disponible pour Claude, et un appel à celui-ci qui nécessite une approbation 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 autres outils non listés ici existent toujours, et les appels à ceux-ci qui nécessitent une approbation 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 * tel qu'écrit sont refusés dans tous les modes de permission, y compris bypassPermissions. Les autres appels Bash, y compris /bin/rm, passent au 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 avec un avertissement au démarrage et n'auto-approuve 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 de 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, de sorte que la règle ne bloque pas /secrets sur le disque. Consultez Règles Read et Edit pour les quatre formes d'ancrage et la façon dont les règles des fichiers de paramètres se résolvent.
Pour un agent verrouillé, associez allowedTools avec permissionMode: "dontAsk" :
const options = {
allowedTools: ["Read", "Glob", "Grep"],
permissionMode: "dontAsk"
};
Les outils listés sont approuvés, à l'exception des actions qu'aucun mode n'auto-approuve, et tout autre appel qui demanderait une approbation est refusé à la place. Les appels qui ne nécessitent aucune approbation en mode default s'exécutent que vous les listiez ou non, comme les commandes Bash en lecture seule, les outils comme Agent qui ne demandent pas avant de s'exécuter, et les lectures de fichiers dans vos répertoires de travail. Pour mettre un outil hors de portée de Claude entièrement, ajoutez son nom nu à disallowedTools.
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 basées sur le mode ; les appels qui nécessitent une approbation et ne correspondent à aucune règle d'autorisation déclenchent votre callback canUseTool |
dontAsk |
Refuser au lieu de demander | Tout appel qui demanderait autrement est refusé. Les appels approuvés par allowed_tools ou les règles s'exécutent, tout comme les appels qui ne nécessitent pas d'approbation en mode default ; les outils connecteur que votre organisation a défini sur ask et les outils qui nécessitent une interaction utilisateur sont refusés même si vous les avez pré-approuvés, tout comme les suppressions rm et rmdir ciblant un chemin critique. 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 les contrôles de permission | Les outils s'exécutent sans invites de permission, sauf pour les actions qu'aucun mode n'auto-approuve. À utiliser avec prudence |
plan |
Mode de planification | Claude explore et planifie sans modifier vos fichiers source ; les modifications de fichiers ne sont jamais auto-approuvées et demandent via votre callback canUseTool |
auto |
Approbations classées par modèle | Un classificateur de modèle approuve ou refuse les invites de permission. Consultez Mode Auto pour la disponibilité |
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.
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())
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();
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`)
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. En mode acceptEdits, Claude Code n'auto-approuve pas la demande lorsque Claude :
- Travaille sur un chemin en dehors de cette portée
- Écrit vers un chemin protégé
- Supprime un chemin critique avec
rmourmdir
À 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, sans appeler canUseTool. Les outils pré-approuvés par allowed_tools, les règles d'autorisation de settings.json, ou un hook s'exécutent normalement, tout comme les appels qui ne nécessitent pas d'approbation en mode default, tels que les lectures de fichiers à l'intérieur de vos répertoires de travail et les appels à Agent. Les outils connecteur que votre organisation a défini sur ask, les outils qui nécessitent une interaction utilisateur, et les suppressions rm et rmdir ciblant un chemin critique sont refusés même lorsqu'une règle d'autorisation correspond. Un allow hook PreToolUse ne supprime pas non plus une suppression de chemin critique.
À 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 les usages d'outils sans invites, sauf les cas énumérés dans l'avertissement ci-dessous. 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 default.
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. Sur Claude Code v2.1.212 ou ultérieur, les commandes shell qui modifient les fichiers, telles que touch et rm, atteignent votre callback canUseTool de la même manière.
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