​

Permessi SDK

​

Panoramica

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

• 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

​

Modalità di Permesso

​

Modalità Disponibili

​

Impostazione della Modalità di Permesso

​

1. Configurazione Iniziale

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)

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)

• 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

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

​

Modalità Bypassa Permessi (bypassPermissions)

• 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

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

• 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

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

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

​

canUseTool

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