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

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

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', qui approuve automatiquement chaque appel qui atteint l'étape du mode de permission à l'exception des actions qu'aucun mode n'approuve automatiquement
• Chaque entrée allowedTools sans nom comme "Read", qui approuve automatiquement cet outil entier avant que le callback ne soit consulté, à l'exception des 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 de 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. 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 opte également 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 avec un avertissement au démarrage 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.

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

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

Les outils listés sont approuvés, en dehors des actions qu'aucun mode n'approuve automatiquement, et chaque autre appel qui inviterait 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 d'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 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.

Modes disponibles

Le SDK prend en charge ces modes de permission :

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.

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

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 un chemin critique avec rm ou rmdir

À 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 invite de permission en refus, sans appeler canUseTool. Les outils pré-approuvés par allowed_tools, les règles d'autorisation 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 dans vos répertoires de travail et les appels à Agent. Les outils connecteur que votre organisation a définis 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 refus de hook PreToolUse ne supprime pas non plus une suppression de chemin critique.

À 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 cas énumérés dans l'avertissement ci-dessous. 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 bac à sable reconnu, et la requête échoue avant le premier tour.

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 ils le font en mode de permission default.

Les modifications de fichiers ne sont jamais approuvées automatiquement en mode plan, même lorsqu'une règle d'autorisation correspond. Elles demandent via votre rappel 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 rappel canUseTool de la même manière.

Si vous définissez allowDangerouslySkipPermissions: true aux côtés de permissionMode: 'plan', les modifications de fichiers et les commandes shell qui modifient les fichiers atteignent toujours votre rappel canUseTool. L'option vous permet de passer à bypassPermissions plus tard avec setPermissionMode().

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.

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