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 ciò che è consentito automaticamente, e il callback canUseTool per gestire tutto il resto in fase di esecuzione.

Come vengono valutate le autorizzazioni

Quando Claude richiede uno strumento, l'SDK controlla le autorizzazioni in questo ordine:

Se passate un callback canUseTool in una configurazione in cui l'SDK TypeScript si aspetta che l'ordine di valutazione approvi automaticamente le chiamate prima che il callback sia consultato, l'SDK emette un avviso di processo Node.js una volta quando la query viene costruita. Il codice dell'avviso è CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Due configurazioni lo attivano:

• permissionMode: 'bypassPermissions', che approva automaticamente ogni chiamata che raggiunge il passaggio della modalità di autorizzazione a parte le azioni che nessuna modalità approva automaticamente
• Ogni voce allowedTools semplice come "Read", che approva automaticamente quello strumento intero prima che il callback sia consultato, a parte le azioni che nessuna modalità approva automaticamente

Le voci con uno specificatore come Bash(ls *) e la modalità acceptEdits non lo attivano, e le regole di autorizzazione provenienti da file di impostazioni non sono visibili al controllo.

Ascoltate con process.on('warning', ...) e abbinate il codice per registrarlo o sopprimerlo. Per controllare ogni chiamata di strumento indipendentemente dalla modalità e dalle regole, utilizzate invece un hook PreToolUse.

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

• Hooks: eseguire codice personalizzato per consentire, negare o modificare le richieste di strumenti. Vedere Controllare l'esecuzione con gli hook.
• Callback canUseTool: richiedere l'approvazione degli utenti in fase di esecuzione, quando nessun passaggio precedente risolve la chiamata. Vedere Gestire le approvazioni e l'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 descritto. Se nominate uno dei strumenti di tracciamento delle attività in allowed_tools, Claude Code opta anche per la sessione. Qualsiasi altro strumento non elencato in allowed_tools è ancora disponibile per Claude, e una chiamata ad esso che necessita di approvazione passa attraverso la modalità di autorizzazione. Le regole di negazione si comportano diversamente a seconda che nominino uno strumento o limitino un modello all'interno di uno.

Le regole di consentimento accettano glob dei nomi degli strumenti solo dopo un prefisso letterale mcp__<server>__. Il segmento del server deve essere privo di glob in modo che la regola nomini un server specifico che avete configurato: mcp__puppeteer__* corrisponde a ogni strumento dal server puppeteer, e mcp__github__get_* corrisponde ai suoi strumenti get_. Una voce non ancorata come allowed_tools=["*"] o allowed_tools=["mcp__*"] viene ignorata con un avviso di avvio e non approva automaticamente nulla.

Le regole limitate per Read e Edit accettano un modello di percorso. Le regole Edit(path) governano tutti gli strumenti integrati che scrivono file, inclusi Write e NotebookEdit; una regola Write(path) non viene mai abbinata dai controlli di autorizzazione dei file.

Utilizzate //path per un percorso del filesystem assoluto: una regola di negazione di Edit(//secrets/**) blocca le scritture ovunque sotto /secrets su disco. Con una singola barra iniziale, Edit(/secrets/**) si ancora alla fonte della regola. Per le regole passate attraverso allowed_tools o disallowed_tools, ciò significa la directory di lavoro della sessione, quindi la regola non blocca /secrets su disco. Consultate Regole Read e Edit per i quattro moduli di ancoraggio e come le regole dai file di impostazioni si risolvono.

Per un agente bloccato, abbinate allowedTools con permissionMode: "dontAsk":

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

Gli strumenti elencati sono approvati, a parte le azioni che nessuna modalità approva automaticamente, e ogni altra chiamata che comporterebbe una richiesta viene invece negata. Le chiamate che non necessitano di approvazione in modalità default vengono eseguite indipendentemente dal fatto che le elenchiate, come i comandi Bash di sola lettura, strumenti come Agent che non chiedono prima di eseguire, e letture di file all'interno delle vostre directory di lavoro. Per mettere uno strumento completamente fuori dalla portata di Claude, aggiungete il suo nome semplice a disallowedTools.

Potete anche configurare le 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 avviene per le opzioni predefinite di query(). Se impostate esplicitamente setting_sources (TypeScript: settingSources), includete "project" affinché si applichino. Consultate Impostazioni di autorizzazione per la sintassi delle regole.

Modalità di autorizzazione

Le modalità di autorizzazione forniscono un controllo globale su come Claude utilizza gli strumenti. È possibile impostare la modalità di autorizzazione quando si chiama query() o modificarla dinamicamente durante le sessioni di streaming.

Modalità disponibili

L'SDK supporta queste modalità di autorizzazione:

Impostare la modalità di autorizzazione

È possibile impostare la modalità di autorizzazione una volta all'avvio di una query, oppure modificarla 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 sui file in modo che Claude possa modificare il codice senza richiedere conferma. Gli altri strumenti (come i comandi Bash che non sono operazioni del filesystem) richiedono comunque autorizzazioni 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. In modalità acceptEdits, Claude Code non approva automaticamente la richiesta quando Claude:

• Lavora su un percorso al di fuori di tale ambito
• Scrive in un percorso protetto
• Rimuove un percorso critico con rm o rmdir

Utilizzare quando: si confida nelle modifiche di Claude e si desidera un'iterazione più veloce, ad esempio durante la prototipazione o quando si lavora in una directory isolata.

Modalità non chiedere (`dontAsk`)

Converte qualsiasi richiesta di autorizzazione in una negazione, senza chiamare canUseTool. Gli strumenti pre-approvati da allowed_tools, regole di autorizzazione in settings.json o un hook vengono eseguiti normalmente, così come le chiamate che non richiedono approvazione in modalità default, come le letture di file all'interno delle directory di lavoro e le chiamate a Agent. Gli strumenti connector impostati dalla vostra organizzazione su ask, gli strumenti che richiedono interazione dell'utente e le rimozioni rm e rmdir che interessano un percorso critico vengono negati anche quando una regola di autorizzazione corrisponde. Un'autorizzazione del hook PreToolUse non cancella nemmeno una rimozione di percorso critico.

Utilizzare quando: si desidera una superficie di strumenti fissa ed esplicita per un agente headless e si preferisce un rifiuto netto rispetto all'affidamento silenzioso all'assenza di canUseTool.

Modalità ignora autorizzazioni (`bypassPermissions`)

Approva automaticamente gli usi degli strumenti senza richiedere conferma, ad eccezione dei casi elencati nell'avviso di seguito. I hook vengono comunque eseguiti e possono bloccare le operazioni se necessario. Su Linux e macOS, Claude Code rifiuta di avviarsi in questa modalità come root o sotto sudo al di fuori di una sandbox riconosciuta, e la query non riesce prima del primo turno.

Modalità pianificazione (`plan`)

Claude esplora la base di codice e produce un piano senza modificare i file sorgente. Gli strumenti di sola lettura vengono eseguiti come nella modalità di autorizzazione default.

Le modifiche ai file non vengono mai approvate automaticamente in modalità plan, anche quando una regola di autorizzazione corrisponde. Invece, richiedono il callback canUseTool. Su Claude Code v2.1.212 o successivo, i comandi shell che modificano i file, come touch e rm, raggiungono il callback canUseTool allo stesso modo.

Se si imposta allowDangerouslySkipPermissions: true insieme a permissionMode: 'plan', le modifiche ai file e i comandi shell che modificano i file raggiungono comunque il callback canUseTool. L'opzione consente di passare a bypassPermissions in seguito con setPermissionMode().

Claude può utilizzare AskUserQuestion per chiarire i requisiti prima di finalizzare il piano. Vedere Gestire approvazioni e input dell'utente per la gestione di queste richieste.

Utilizzare quando: si desidera che Claude proponga modifiche senza eseguirle, ad esempio durante la revisione del codice o quando è necessario approvare le modifiche prima che vengano apportate.

Risorse correlate

Per gli altri passaggi nel flusso di valutazione delle autorizzazioni:

• Gestire approvazioni e input dell'utente: prompt di approvazione interattivi e domande di chiarimento
• Guida hooks: eseguire codice personalizzato nei punti chiave del ciclo di vita dell'agente
• Regole di autorizzazione: regole dichiarative di consentimento/negazione in settings.json