​

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 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éfinir le 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, 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)

• 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 complet au système
• 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 outrepasser n’importe quel mode
2. Les règles de refus sont vérifiées - Bloquent les outils indépendamment du 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

• 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 permission
• 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 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);
    }
  }
});

​

Utiliser les Hooks pour le Contrôle des Outils

​

Implémentation des Hooks

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

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)

​

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

• 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’outil uniquement : Omettent les parenthèses pour contrôler des outils entiers. Exemple : WebFetch bloque toutes les récupérations web

​

Utilisation avec le SDK

​

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

• 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

• Bash(git:*) - Correspond à toute commande git
• Bash(npm run test) - Correspond à la commande exacte
• Bash(npm run test:*) - Correspond aux commandes Bash commençant par npm run test comme npm run test anyFile.test.ts

​

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