​

Permissions du SDK

​

Vue d’ensemble

1. Modes de Permission - Paramètres de comportement de permission globaux 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

• Modes de permission - 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

​

Modes de Permission

​

Modes Disponibles

​

Définition du Mode de Permission

​

1. Configuration Initiale

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

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

​

2. Changements de Mode Dynamiques (Streaming Uniquement)

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

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

• 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

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

​

Mode Contourner les Permissions (bypassPermissions)

• TOUTES les utilisations d’outils sont automatiquement approuvées
• Aucune invite de permission 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 système complet
• Recommandé uniquement pour les environnements contrôlés

​

Priorité des Modes dans le Flux de Permissions

1. Les hooks s’exécutent en premier - Peuvent autoriser, refuser, demander, ou continuer
2. Les règles de refus sont vérifiées - Bloquent les outils indépendamment du mode
3. Les règles d’autorisation sont vérifiées - Permettent les outils si correspondance
4. Les règles de demande sont vérifiées - Demandent la permission si correspondance
5. Le mode de permission est évalué :
   • Mode bypassPermissions - Si actif, autorise tous les outils restants
   • Autres modes - Défèrent au callback canUseTool
6. Callback canUseTool - Gère les cas restants

• Les hooks peuvent toujours contrôler l’utilisation des outils, même en mode bypassPermissions
• Les règles de refus explicites prévalent sur tous les modes de permission
• Les règles de demande sont évaluées avant les modes de permission
• Le mode bypassPermissions préempt le callback canUseTool pour les outils non correspondants

​

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 les hooks pour un contrôle fin
5. Changez les modes dynamiquement basé sur le progrès de la tâche et la confiance

// 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

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

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 (remplacer 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 permission
const result = await query({
  prompt: "Aidez-moi à analyser cette base de code",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

​

Ressources Connexes

• Guide des Hooks - Apprenez comment implémenter des hooks pour un contrôle fin sur l’exécution des outils
• Paramètres : Règles de Permissions - Configurez des règles déclaratives d’autorisation/refus avec analyse des commandes bash