Gestion des Permissions

Contrôlez l’utilisation des outils et les permissions dans le SDK Claude Code

Permissions du SDK

Le SDK Claude Code fournit des contrôles de permissions puissants qui vous permettent de gérer comment Claude utilise les outils dans votre application.

Ce guide couvre comment implémenter des systèmes de permissions en utilisant le callback canUseTool, les hooks, et les règles de permissions settings.json. Pour la documentation complète de l’API, consultez la référence du SDK TypeScript.

Vue d’ensemble

Le SDK Claude Code fournit quatre façons complémentaires de contrôler l’utilisation des outils :

1. Modes de permissions - Paramètres de comportement de permissions globales qui affectent tous les outils
2. callback canUseTool - Gestionnaire de permissions d’exécution pour les cas non couverts par d’autres règles
3. Hooks - Contrôle fin sur chaque exécution d’outil avec une logique personnalisée
4. Règles de permissions (settings.json) - Règles déclaratives d’autorisation/refus avec analyse intégrée des commandes bash

Cas d’usage pour chaque approche :

• Modes de permissions - Définir le comportement global des permissions (planification, acceptation automatique des modifications, contournement des vérifications)
• canUseTool - Approbation dynamique pour les cas non couverts, demande l’autorisation à l’utilisateur
• Hooks - Contrôle programmatique sur toutes les exécutions d’outils
• Règles de permissions - Politiques statiques avec analyse intelligente des commandes bash

Diagramme de flux des permissions

Ordre de traitement : Hook PreToolUse → Règles Ask → Règles Deny → Vérification du mode de permission → Règles Allow → Callback canUseTool → Hook PostToolUse

Modes de permissions

Les modes de permissions 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 changer dynamiquement pendant les sessions de streaming.

Modes disponibles

Le SDK prend en charge quatre modes de permissions, chacun avec un comportement différent :

Mode	Description	Comportement des outils
default	Comportement de permissions standard	Les vérifications de permissions normales s’appliquent
plan	Mode planification - pas d’exécution	Claude ne peut utiliser que des outils en lecture seule ; présente un plan avant l’exécution (Actuellement non pris en charge dans le SDK)
acceptEdits	Accepter automatiquement les modifications de fichiers	Les modifications de fichiers et les opérations du système de fichiers sont automatiquement approuvées
bypassPermissions	Contourner toutes les vérifications de permissions	Tous les outils s’exécutent sans invites de permissions (à utiliser avec précaution)

Définir le mode de permission

Vous pouvez définir le mode de permission de deux façons :

1. Configuration initiale

Définir le mode lors de la création d’une requête :

TypeScript

import { query } from "@anthropic-ai/claude-code";

const result = await query({
  prompt: "Aidez-moi à refactoriser ce code",
  options: {
    permissionMode: 'default'  // Mode de permissions standard
  }
});

2. Changements de mode dynamiques (Streaming uniquement)

Changer le mode pendant une session de streaming :

TypeScript

import { query } from "@anthropic-ai/claude-code";

// Créer un générateur asynchrone pour l'entrée en streaming
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Commençons avec les permissions par défaut" 
    }
  };
  
  // Plus tard dans la conversation...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Maintenant accélérons le développement"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // Commencer en mode par défaut
  }
});

// Changer le mode dynamiquement
await q.setPermissionMode('acceptEdits');

// Traiter les messages
for await (const message of q) {
  console.log(message);
}

Comportements spécifiques aux modes

Mode Accepter les modifications (acceptEdits)

En mode accepter les modifications :

• Toutes les modifications de fichiers sont automatiquement approuvées
• Les opérations du système de fichiers (mkdir, touch, rm, etc.) sont auto-approuvées
• Les autres outils nécessitent encore des permissions normales
• Accélère le développement quand vous faites confiance aux modifications de Claude
• Utile pour le prototypage rapide et les itérations

Opérations auto-approuvées :

• Modifications de fichiers (outils Edit, MultiEdit, Write)
• Commandes bash du système de fichiers (mkdir, touch, rm, mv, cp)
• Création et suppression de fichiers

Mode Contourner les permissions (bypassPermissions)

En mode contourner les permissions :

• TOUTES les utilisations d’outils sont automatiquement approuvées
• Aucune invite de permissions n’apparaît
• Les hooks s’exécutent toujours (peuvent encore bloquer les opérations)
• À utiliser avec une extrême précaution - Claude a un accès complet au système
• Recommandé uniquement pour les environnements contrôlés

Priorité des modes dans le flux de permissions

Les modes de permissions sont évalués à un point spécifique dans le flux de permissions :

1. Les hooks s’exécutent en premier - Peuvent outrepasser n’importe quel mode
2. Les règles de refus sont vérifiées - Bloquent les outils quel que soit le mode
3. Le mode bypassPermissions - Si actif, autorise tous les outils restants
4. Les règles d’autorisation sont vérifiées
5. Les autres modes affectent des comportements d’outils spécifiques
6. Le callback canUseTool - Gère les cas restants

Cela signifie :

• Les hooks peuvent toujours bloquer l’utilisation d’outils, même en mode bypassPermissions
• Les règles de refus explicites outrepassent tous les modes de permissions
• Le mode bypassPermissions outrepasse les règles d’autorisation et canUseTool

Meilleures pratiques

1. Utilisez le mode par défaut pour une exécution contrôlée avec des vérifications de permissions normales
2. Utilisez le mode acceptEdits quand vous travaillez sur des fichiers ou répertoires isolés
3. Évitez bypassPermissions en production ou sur des systèmes avec des données sensibles
4. Combinez les modes avec des hooks pour un contrôle fin
5. Changez les modes dynamiquement selon le progrès de la tâche et la confiance

Exemple de progression de modes :

// Commencer en mode par défaut pour une exécution contrôlée
permissionMode: 'default'

// Passer à acceptEdits pour une itération rapide
await q.setPermissionMode('acceptEdits')

canUseTool

Le callback canUseTool est passé comme option lors de l’appel de la fonction query. Il reçoit le nom de l’outil et les paramètres d’entrée, et doit retourner une décision - soit autoriser soit refuser.

canUseTool se déclenche chaque fois que Claude Code afficherait une invite de permissions à un utilisateur, par exemple les hooks et les règles de permissions ne le couvrent pas et il n’est pas en mode d’acceptation automatique.

Voici un exemple complet montrant comment implémenter l’approbation interactive d’outils :

TypeScript

import { query } from "@anthropic-ai/claude-code";

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 Demande d'outil :");
  console.log(`   Outil : ${toolName}`);
  
  // Afficher les paramètres de l'outil
  if (input && Object.keys(input).length > 0) {
    console.log("   Paramètres :");
    for (const [key, value] of Object.entries(input)) {
      let displayValue = value;
      if (typeof value === 'string' && value.length > 100) {
        displayValue = value.substring(0, 100) + "...";
      } else if (typeof value === 'object') {
        displayValue = JSON.stringify(value, null, 2);
      }
      console.log(`     ${key}: ${displayValue}`);
    }
  }
  
  // Obtenir l'approbation de l'utilisateur (remplacez par votre logique d'interface utilisateur)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Approuvé\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Refusé\n");
    return {
      behavior: "deny",
      message: "L'utilisateur a refusé la permission pour cet outil"
    };
  }
}

// Utiliser le callback de permissions
const result = await query({
  prompt: "Aidez-moi à analyser cette base de code",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

Utiliser les hooks pour le contrôle des outils

Les hooks fournissent un contrôle programmatique sur l’exécution des outils à diverses étapes. Les hooks sont appelés pour chaque utilisation d’outil, vous donnant un contrôle complet sur le pipeline de permissions.

Implémentation des hooks

TypeScript

import { query } from "@anthropic-ai/claude-code";

const result = await query({
  prompt: "Aidez-moi à refactoriser ce code",
  options: {
    hooks: {
      PreToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Demande d'outil : ${input.tool_name}`);
          
          // Analyser et valider l'entrée de l'outil vous-même
          if (input.tool_name === "Bash") {
            const command = input.tool_input.command;
            if (command.startsWith("rm -rf")) {
              return {
                decision: "block",
                reason: "Commande dangereuse bloquée"
              };
            }
          }
          
          return { continue: true };
        }]
      }],
      PostToolUse: [{
        hooks: [async (input, toolUseId, { signal }) => {
          console.log(`Outil terminé : ${input.tool_name}`);
          // Enregistrer ou auditer les résultats des outils
          return { continue: true };
        }]
      }]
    }
  }
});

Différences clés avec canUseTool

• Portée : Les hooks sont appelés pour toutes les utilisations d’outils ; canUseTool gère les cas non couverts par les règles de permissions
• Contrôle : Les hooks nécessitent d’analyser et de valider les entrées vous-même
• Événements : Les hooks prennent en charge plusieurs événements (PreToolUse, PostToolUse, etc.) pour différentes étapes

Utiliser les règles de permissions (settings.json)

Les règles de permissions dans settings.json fournissent un contrôle déclaratif avec analyse intégrée des commandes bash. Ces règles sont évaluées avant que canUseTool ne soit appelé. Pour plus de détails sur la configuration des paramètres, consultez la documentation des paramètres Claude Code.

Structure de configuration

{
  "permissions": {
    "allow": [
      "Bash(npm run lint)",
      "Bash(npm run test:*)",
      "Read(~/.zshrc)"
    ],
    "deny": [
      "Bash(curl:*)",
      "Read(./.env)",
      "Read(./secrets/**)",
      "WebFetch"
    ],
    "ask": [
      "Bash(git push:*)",
      "Write(./production/**)"
    ]
  }
}

Syntaxe des règles

Les règles de permissions suivent le modèle : NomOutil(motif)

• Règles Bash : Utilisent la correspondance de préfixe (pas regex). Exemple : Bash(npm:*) correspond à toute commande commençant par “npm”
• Règles de fichiers : Prennent en charge les motifs glob. Exemple : Read(./src/**/*.ts) correspond aux fichiers TypeScript dans src
• Règles d’outils uniquement : Omettent les parenthèses pour contrôler des outils entiers. Exemple : WebFetch bloque toutes les récupérations web

Utilisation avec le SDK

Bien que les règles ne puissent pas encore être définies programmatiquement dans le SDK, elles seront lues depuis le fichier settings.json dans le chemin où le SDK est chargé.

Ordre d’évaluation des permissions

1. Les règles de refus sont vérifiées en premier - si correspondance, l’utilisation de l’outil est bloquée
2. Les règles d’autorisation sont vérifiées ensuite - si correspondance, l’utilisation de l’outil est permise
3. Les règles de demande sont vérifiées - si correspondance, l’utilisateur est invité
4. Le callback canUseTool est invoqué pour tous les cas restants

Analyse des commandes Bash

Le SDK inclut un analyseur bash intégré qui comprend la structure des commandes :

• Gère les pipes, redirections et substitution de commandes
• Reconnaît les motifs dangereux comme rm -rf ou curl | sh
• Prend en charge les caractères génériques et la correspondance de préfixe

Exemple de fonctionnement des motifs bash :

• Bash(git:*) - Correspond à toute commande git
• Bash(npm run test) - Correspond à la commande exacte
• Bash(npm run test:*) - Correspond à npm run test:unit, test:integration, etc.

Meilleures pratiques

1. Commencez avec le mode par défaut pour les vérifications de permissions standard
2. Utilisez les règles de permissions pour les politiques statiques, en particulier les commandes bash (voir paramètres de permissions)
3. Utilisez les hooks pour enregistrer, auditer ou transformer toutes les utilisations d’outils (voir types de hooks)
4. Utilisez canUseTool pour les décisions dynamiques sur les cas non couverts (voir type CanUseTool)
5. Superposez les défenses en combinant modes, règles, hooks et callbacks pour les applications critiques