Permessi SDK

Il Claude Agent SDK fornisce potenti controlli dei permessi che ti permettono di gestire come Claude utilizza gli strumenti nella tua applicazione.

Questa guida copre come implementare sistemi di permessi utilizzando il callback canUseTool, gli hook e le regole di permesso di settings.json. Per la documentazione completa dell'API, consulta il riferimento TypeScript SDK.

Panoramica

Il Claude Agent SDK fornisce quattro modi complementari per controllare l'uso degli strumenti:

1. Modalità di Permesso - Impostazioni globali del comportamento dei permessi che influenzano tutti gli strumenti
2. callback canUseTool - Gestore di permessi runtime per casi non coperti da altre regole
3. Hook - Controllo granulare su ogni esecuzione di strumento con logica personalizzata
4. Regole di permesso (settings.json) - Regole dichiarative di permesso/negazione con parsing integrato dei comandi bash

Casi d'uso per ogni approccio:

• Modalità di permesso - Imposta il comportamento generale dei permessi (pianificazione, accettazione automatica delle modifiche, bypass dei controlli)
• canUseTool - Approvazione dinamica per casi non coperti, richiede il permesso all'utente
• Hook - Controllo programmatico su tutte le esecuzioni degli strumenti
• Regole di permesso - Politiche statiche con parsing intelligente dei comandi bash

Diagramma del Flusso dei Permessi

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

    PreHook -->|  Consenti  | Execute(Esegui Strumento)
    PreHook -->|  Nega  | Denied(Negato)
    PreHook -->|  Chiedi  | Callback(Callback canUseTool)
    PreHook -->|  Continua  | Deny(Controlla Regole di Negazione)

    Deny -->|  Corrispondenza  | Denied
    Deny -->|  Nessuna Corrispondenza  | Allow(Controlla Regole di Permesso)

    Allow -->|  Corrispondenza  | Execute
    Allow -->|  Nessuna Corrispondenza  | Ask(Controlla Regole di Richiesta)

    Ask -->|  Corrispondenza  | Callback
    Ask -->|  Nessuna Corrispondenza  | Mode{Modalità Permesso?}

    Mode -->|  bypassPermissions  | Execute
    Mode -->|  Altre modalità  | Callback

    Callback -->|  Consenti  | Execute
    Callback -->|  Nega  | Denied

    Denied --> DeniedResponse([Feedback all'agente])

    Execute --> PostHook(Hook PostToolUse)
    PostHook --> Done([Risposta Strumento])

    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

Ordine di Elaborazione: Hook PreToolUse → Regole di Negazione → Regole di Permesso → Regole di Richiesta → Controllo Modalità Permesso → Callback canUseTool → Hook PostToolUse

Modalità di Permesso

Le modalità di permesso forniscono controllo globale su come Claude utilizza gli strumenti. Puoi impostare la modalità di permesso quando chiami query() o cambiarla dinamicamente durante le sessioni di streaming.

Modalità Disponibili

L'SDK supporta quattro modalità di permesso, ognuna con comportamento diverso:

Impostazione della Modalità di Permesso

Puoi impostare la modalità di permesso in due modi:

1. Configurazione Iniziale

Imposta la modalità quando crei una query:

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

const result = await query({
  prompt: "Aiutami a refactorizzare questo codice",
  options: {
    permissionMode: 'default'  // Modalità permesso standard
  }
});

2. Cambiamenti Dinamici della Modalità (Solo Streaming)

Cambia la modalità durante una sessione di streaming:

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

// Crea un generatore asincrono per l'input streaming
async function* streamInput() {
  yield { 
    type: 'user',
    message: { 
      role: 'user', 
      content: "Iniziamo con i permessi predefiniti" 
    }
  };
  
  // Più tardi nella conversazione...
  yield {
    type: 'user',
    message: {
      role: 'user',
      content: "Ora acceleriamo lo sviluppo"
    }
  };
}

const q = query({
  prompt: streamInput(),
  options: {
    permissionMode: 'default'  // Inizia in modalità predefinita
  }
});

// Cambia modalità dinamicamente
await q.setPermissionMode('acceptEdits');

// Elabora i messaggi
for await (const message of q) {
  console.log(message);
}

Comportamenti Specifici delle Modalità

Modalità Accetta Modifiche (acceptEdits)

In modalità accetta modifiche:

• Tutte le modifiche ai file vengono approvate automaticamente
• Le operazioni del filesystem (mkdir, touch, rm, ecc.) vengono auto-approvate
• Altri strumenti richiedono ancora permessi normali
• Accelera lo sviluppo quando ti fidi delle modifiche di Claude
• Utile per prototipazione rapida e iterazioni

Operazioni approvate automaticamente:

• Modifiche ai file (strumenti Edit, Write)
• Comandi bash del filesystem (mkdir, touch, rm, mv, cp)
• Creazione ed eliminazione di file

Modalità Bypassa Permessi (bypassPermissions)

In modalità bypassa permessi:

• TUTTI gli usi degli strumenti vengono approvati automaticamente
• Non appaiono richieste di permesso
• Gli hook vengono ancora eseguiti (possono ancora bloccare le operazioni)
• Usa con estrema cautela - Claude ha accesso completo al sistema
• Raccomandato solo per ambienti controllati

Priorità della Modalità nel Flusso dei Permessi

Le modalità di permesso vengono valutate in un punto specifico del flusso dei permessi:

1. Gli hook vengono eseguiti per primi - Possono consentire, negare, chiedere o continuare
2. Le regole di negazione vengono controllate - Bloccano gli strumenti indipendentemente dalla modalità
3. Le regole di permesso vengono controllate - Permettono gli strumenti se corrispondenti
4. Le regole di richiesta vengono controllate - Richiedono permesso se corrispondenti
5. La modalità di permesso viene valutata:
   • Modalità bypassPermissions - Se attiva, consente tutti gli strumenti rimanenti
   • Altre modalità - Delegano al callback canUseTool
6. Callback canUseTool - Gestisce i casi rimanenti

Questo significa:

• Gli hook possono sempre controllare l'uso degli strumenti, anche in modalità bypassPermissions
• Le regole di negazione esplicite sovrascrivono tutte le modalità di permesso
• Le regole di richiesta vengono valutate prima delle modalità di permesso
• La modalità bypassPermissions sovrascrive il callback canUseTool per gli strumenti non corrispondenti

Migliori Pratiche

1. Usa la modalità predefinita per l'esecuzione controllata con controlli normali dei permessi
2. Usa la modalità acceptEdits quando lavori su file o directory isolate
3. Evita bypassPermissions in produzione o su sistemi con dati sensibili
4. Combina le modalità con gli hook per un controllo granulare
5. Cambia le modalità dinamicamente in base al progresso del compito e alla fiducia

Esempio di progressione delle modalità:

// Inizia in modalità predefinita per l'esecuzione controllata
permissionMode: 'default'

// Passa ad acceptEdits per l'iterazione rapida
await q.setPermissionMode('acceptEdits')

canUseTool

Il callback canUseTool viene passato come opzione quando si chiama la funzione query. Riceve il nome dello strumento e i parametri di input, e deve restituire una decisione - consentire o negare.

canUseTool si attiva ogni volta che Claude Code mostrerebbe una richiesta di permesso a un utente, ad esempio gli hook e le regole di permesso non lo coprono e non è in modalità acceptEdits.

Ecco un esempio completo che mostra come implementare l'approvazione interattiva degli strumenti:

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

async function promptForToolApproval(toolName: string, input: any) {
  console.log("\n🔧 Richiesta Strumento:");
  console.log(`   Strumento: ${toolName}`);
  
  // Visualizza i parametri dello strumento
  if (input && Object.keys(input).length > 0) {
    console.log("   Parametri:");
    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}`);
    }
  }
  
  // Ottieni l'approvazione dell'utente (sostituisci con la tua logica UI)
  const approved = await getUserApproval();
  
  if (approved) {
    console.log("   ✅ Approvato\n");
    return {
      behavior: "allow",
      updatedInput: input
    };
  } else {
    console.log("   ❌ Negato\n");
    return {
      behavior: "deny",
      message: "L'utente ha negato il permesso per questo strumento"
    };
  }
}

// Usa il callback di permesso
const result = await query({
  prompt: "Aiutami ad analizzare questa codebase",
  options: {
    canUseTool: async (toolName, input) => {
      return promptForToolApproval(toolName, input);
    }
  }
});

Risorse Correlate

• Guida agli Hook - Impara come implementare gli hook per un controllo granulare sull'esecuzione degli strumenti
• Impostazioni: Regole di Permesso - Configura regole dichiarative di permesso/negazione con parsing dei comandi bash