Permissions du SDK

Le SDK Claude Agent 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 API complète, voir la référence du SDK TypeScript.

Vue d'ensemble

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

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

Cas d'usage pour chaque approche :

• 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

%%{init: {"theme": "base", "themeVariables": {"edgeLabelBackground": "#F0F0EB", "lineColor": "#91918D"}, "flowchart": {"edgeLabelMarginX": 12, "edgeLabelMarginY": 8}}}%%
flowchart TD
    Start([Demande d'outil]) --> PreHook(Hook PreToolUse)

    PreHook -->|  Autoriser  | Execute(Exécuter l'Outil)
    PreHook -->|  Refuser  | Denied(Refusé)
    PreHook -->|  Demander  | Callback(Callback canUseTool)
    PreHook -->|  Continuer  | Deny(Vérifier Règles de Refus)

    Deny -->|  Correspondance  | Denied
    Deny -->|  Pas de Correspondance  | Allow(Vérifier Règles d'Autorisation)

    Allow -->|  Correspondance  | Execute
    Allow -->|  Pas de Correspondance  | Ask(Vérifier Règles de Demande)

    Ask -->|  Correspondance  | Callback
    Ask -->|  Pas de Correspondance  | Mode{Mode de Permission ?}

    Mode -->|  bypassPermissions  | Execute
    Mode -->|  Autres modes  | Callback

    Callback -->|  Autoriser  | Execute
    Callback -->|  Refuser  | Denied

    Denied --> DeniedResponse([Retour à l'agent])

    Execute --> PostHook(Hook PostToolUse)
    PostHook --> Done([Réponse de l'Outil])

    style Start fill:#F0F0EB,stroke:#D9D8D5,color:#191919

    style Denied fill:#BF4D43,color:#fff
    style DeniedResponse fill:#BF4D43,color:#fff
    style Execute fill:#DAAF91,color:#191919
    style Done fill:#DAAF91,color:#191919

    classDef hookClass fill:#CC785C,color:#fff
    class PreHook,PostHook hookClass

    classDef ruleClass fill:#EBDBBC,color:#191919
    class Deny,Allow,Ask ruleClass

    classDef modeClass fill:#A8DAEF,color:#191919
    class Mode modeClass

    classDef callbackClass fill:#D4A27F,color:#191919
    class Callback callbackClass

Ordre de Traitement : Hook PreToolUse → Règles de Refus → Règles d'Autorisation → Règles de Demande → Vérification du Mode de Permission → Callback canUseTool → Hook PostToolUse

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

Modes Disponibles

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

Définition du Mode de Permission

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

1. Configuration Initiale

Définissez le mode lors de la création d'une requête :

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)

Changez le mode pendant une session de streaming :

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)

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

Les modes de permission sont évalués à un point spécifique 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

Cela signifie :

• 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

Exemple de progression de mode :

// 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 permission à un utilisateur, par exemple les hooks et les règles de permissions ne le couvrent pas et il n'est pas en mode acceptEdits.

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

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