Configurare i permessi

Controlla come il tuo agente utilizza gli strumenti con modalità di permesso, hook e regole dichiarative di consentimento/negazione.

Claude Agent SDK fornisce controlli di permesso per gestire come Claude utilizza gli strumenti. Utilizza modalità di permesso e regole per definire cosa è consentito automaticamente, e il callback canUseTool per gestire tutto il resto in fase di esecuzione.

Come vengono valutati i permessi

Quando Claude richiede uno strumento, l'SDK controlla i permessi in questo ordine:

Questa pagina si concentra su regole di consentimento e negazione e modalità di permesso. Per gli altri passaggi:

• Hooks: esegui codice personalizzato per consentire, negare o modificare le richieste di strumenti. Vedi Controllare l'esecuzione con gli hook.
• Callback canUseTool: richiedi agli utenti l'approvazione in fase di esecuzione. Vedi Gestire approvazioni e input dell'utente.

Regole di consentimento e negazione

allowed_tools e disallowed_tools (TypeScript: allowedTools / disallowedTools) aggiungono voci agli elenchi di regole di consentimento e negazione nel flusso di valutazione sopra. Le regole di consentimento influiscono solo sull'approvazione: uno strumento non elencato in allowed_tools è ancora disponibile per Claude e passa alla modalità di permesso. Le regole di negazione si comportano diversamente a seconda che denominino uno strumento o limitino un modello all'interno di uno.

Per un agente bloccato, abbina allowedTools con permissionMode: "dontAsk". Gli strumenti elencati vengono approvati; tutto il resto viene negato completamente invece di richiedere:

const options = {
  allowedTools: ["Read", "Glob", "Grep"],
  permissionMode: "dontAsk"
};

Puoi anche configurare regole di consentimento, negazione e richiesta in modo dichiarativo in .claude/settings.json. Queste regole vengono lette quando la fonte di impostazione project è abilitata, il che è il caso per le opzioni predefinite di query(). Se imposti setting_sources (TypeScript: settingSources) esplicitamente, includi "project" affinché si applichino. Vedi Impostazioni di permesso per la sintassi delle regole.

Modalità di permesso

Le modalità di permesso forniscono un 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 queste modalità di permesso:

Impostare la modalità di permesso

Puoi impostare la modalità di permesso una volta all'inizio di una query, o cambiarla dinamicamente mentre la sessione è attiva.

import asyncio
from claude_agent_sdk import query, ClaudeAgentOptions


async def main():
async for message in query(
prompt="Help me refactor this code",
options=ClaudeAgentOptions(
permission_mode="default",  # Set the mode here
),
):
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

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

async function main() {
for await (const message of query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Set the mode here
}
})) {
if ("result" in message) {
console.log(message.result);
}
}
}

main();

import asyncio
from claude_agent_sdk import ClaudeSDKClient, ClaudeAgentOptions


async def main():
async with ClaudeSDKClient(
options=ClaudeAgentOptions(
permission_mode="default",  # Start in default mode
)
) as client:
await client.query("Help me refactor this code")

# Change mode dynamically mid-session
await client.set_permission_mode("acceptEdits")

# Process messages with the new permission mode
async for message in client.receive_response():
if hasattr(message, "result"):
print(message.result)


asyncio.run(main())

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

async function main() {
const q = query({
prompt: "Help me refactor this code",
options: {
permissionMode: "default" // Start in default mode
}
});

// Change mode dynamically mid-session
await q.setPermissionMode("acceptEdits");

// Process messages with the new permission mode
for await (const message of q) {
if ("result" in message) {
console.log(message.result);
}
}
}

main();

Dettagli della modalità

Modalità accetta modifiche (`acceptEdits`)

Approva automaticamente le operazioni su file in modo che Claude possa modificare il codice senza richiedere. Altri strumenti (come i comandi Bash che non sono operazioni del filesystem) richiedono comunque i permessi normali.

Operazioni approvate automaticamente:

• Modifiche ai file (strumenti Edit, Write)
• Comandi del filesystem: mkdir, touch, rm, rmdir, mv, cp, sed

Entrambi si applicano solo ai percorsi all'interno della directory di lavoro o additionalDirectories. I percorsi al di fuori di tale ambito e le scritture su percorsi protetti richiedono comunque una richiesta.

Usare quando: ti fidi delle modifiche di Claude e desideri un'iterazione più veloce, ad esempio durante la prototipazione o quando lavori in una directory isolata.

Modalità non chiedere (`dontAsk`)

Converte qualsiasi richiesta di permesso in una negazione. Gli strumenti pre-approvati da allowed_tools, regole di consentimento di settings.json o un hook vengono eseguiti normalmente. Tutto il resto viene negato senza chiamare canUseTool.

Usare quando: desideri una superficie di strumenti fissa ed esplicita per un agente headless e preferisci una negazione definitiva rispetto a un affidamento silenzioso su canUseTool assente.

Modalità ignora permessi (`bypassPermissions`)

Approva automaticamente tutti gli usi degli strumenti senza richieste. Gli hook vengono comunque eseguiti e possono bloccare le operazioni se necessario.

Modalità piano (`plan`)

Limita Claude agli strumenti di sola lettura. Claude può leggere file ed eseguire comandi shell di sola lettura per esplorare la base di codice ma non modifica i tuoi file sorgente. Claude può utilizzare AskUserQuestion per chiarire i requisiti prima di finalizzare il piano. Vedi Gestire approvazioni e input dell'utente per gestire queste richieste.

Usare quando: desideri che Claude proponga modifiche senza eseguirle, ad esempio durante la revisione del codice o quando hai bisogno di approvare le modifiche prima che vengano apportate.

Risorse correlate

Per gli altri passaggi nel flusso di valutazione dei permessi:

• Gestire approvazioni e input dell'utente: richieste di approvazione interattive e domande di chiarimento
• Guida agli hook: esegui codice personalizzato nei punti chiave del ciclo di vita dell'agente
• Regole di permesso: regole dichiarative di consentimento/negazione in settings.json