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:1
Hook
Eseguire prima gli hook. Un hook può negare la chiamata completamente o lasciarla passare. Un hook che restituisce
allow non salta le regole di negazione e di richiesta riportate di seguito; quelle vengono valutate indipendentemente dal risultato dell’hook. Un hook PreToolUse che restituisce allow inoltre non può approvare una rimozione rm o rmdir che prende di mira un percorso critico. Per sapere cosa fa quell’allow nel plan mode, consulta Approvazioni degli hook nel plan mode.2
Regole di negazione
Controllare le regole
deny (da disallowed_tools e settings.json). Se una regola di negazione corrisponde, lo strumento viene bloccato, anche in modalità bypassPermissions. Le regole di negazione con nome semplice come Bash rimuovono lo strumento dal contesto di Claude prima che questa valutazione inizi, quindi solo le regole con ambito come Bash(rm *) vengono controllate in questo passaggio.3
Regole di richiesta
Controllare le regole
ask da settings.json. Se una regola di richiesta corrisponde, la chiamata passa al tuo callback canUseTool per la conferma, anche in modalità bypassPermissions.Gli strumenti che richiedono l’interazione dell’utente si comportano allo stesso modo: AskUserQuestion e gli strumenti MCP il cui server imposta _meta["anthropic/requiresUserInteraction"] passano sempre al callback, anche quando una regola di autorizzazione corrisponde. In modalità dontAsk entrambi i casi vengono negati, perché quella modalità non richiede mai. L’annotazione MCP richiede Claude Code v2.1.199 o successivo.Gli strumenti del connettore claude.ai che la vostra organizzazione ha impostato su ask lasciano anche il flusso in questo passaggio. Ogni chiamata passa al callback, anche in modalità bypassPermissions e anche quando una regola di autorizzazione corrisponde. Il callback riceve il motivo Your organization requires approval for this tool. In modalità dontAsk la chiamata viene negata, perché quella modalità non richiede mai.4
Modalità di autorizzazione
Applicare la modalità di autorizzazione attiva:
- In modalità
bypassPermissions, Claude Code approva tutto ciò che raggiunge questo passaggio tranne le rimozionirmermdirche prendono di mira un percorso critico, che passano invece. - In modalità
acceptEdits, Claude Code approva le operazioni su file elencate in Modalità accetta modifiche. - In modalità
plan, Claude Code invia gli strumenti di modifica file e scrittura shell al vostro callbackcanUseToolindipendentemente dalle regole di autorizzazione, in modo che le operazioni di scrittura non possano essere approvate automaticamente durante la pianificazione. - In altre modalità, la richiesta passa.
5
Regole di autorizzazione
Controllare le regole
allow (da allowed_tools e settings.json). Se una regola corrisponde, lo strumento viene approvato. Una chiamata che lo strumento approva da solo viene risolta in questo passaggio, senza alcuna regola necessaria: ad esempio una lettura di file all’interno delle vostre directory di lavoro o un comando Bash di sola lettura.Le rimozioni rm e rmdir che prendono di mira un percorso critico non vengono mai approvate da una regola di consenso. Se poi raggiungano il tuo callback dipende dalla modalità di permesso: in una sessione Agent SDK in modalità auto, ad esempio, Claude Code le nega per impostazione predefinita senza chiamarlo. La tabella delle modalità in Percorsi critici elenca cosa fa ogni modalità con esse.Una regola di consenso non approva una lettura da un percorso di rete.6
Callback canUseTool
Se la chiamata non è stata risolta da nessuno dei passaggi precedenti, chiamare il tuo callback
canUseTool per una decisione. In modalità dontAsk, questo passaggio viene saltato e lo strumento viene negato.Nell’SDK TypeScript, se impostate permissionPrompts: 'none', il vostro callback non viene chiamato in questo passaggio. Un hook PermissionRequest ha ancora la possibilità di decidere, e se non lo fa, Claude Code nega la chiamata. L’opzione richiede Claude Code v2.1.259 o successivo.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
allowedToolssemplice come"Read", che approva automaticamente l’intero strumento prima che il callback venga consultato, a parte le azioni che nessuna modalità approva automaticamente e le letture da percorsi di rete
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":
default vengono eseguite indipendentemente dal fatto che tu le elenchi, come i comandi Bash di sola lettura, strumenti come Agent che non chiedono prima di essere eseguiti, e letture di file all’interno delle tue directory di lavoro. Per rimuovere completamente uno strumento dalla richiesta, aggiungi 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 chiamaquery() o modificarla dinamicamente durante le sessioni di streaming.
Se non ne imposti una, Claude Code sceglie la modalità di autorizzazione iniziale in base alle regole in Quale modalità inizia una sessione:
- Un
permissions.defaultModedai file di impostazioni della sessione quando uno si applica - Altrimenti il valore predefinito integrato, che può essere modalità auto
Bash semplice, come Come la modalità auto valuta le azioni descrive. Se la tua applicazione si basa sulla modalità default o su tale regola, passa default esplicitamente.
Prima di TypeScript Agent SDK v0.3.286, omettere permissionMode era lo stesso che passare default.
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.- Al momento della query
- Durante lo streaming
Passa
permission_mode (Python) o permissionMode (TypeScript) quando crei una query.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
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
rmormdir
Modalità non chiedere (dontAsk)
Converte qualsiasi richiesta di permesso in una negazione, senza chiamare canUseTool. Gli strumenti pre-approvati da allowed_tools, da regole di permesso in settings.json o da un hook vengono eseguiti normalmente, così come le chiamate che non richiedono approvazione in modalità default, come le letture di file all’interno delle tue directory di lavoro e le chiamate a Agent. Gli strumenti connettore che la tua organizzazione ha impostato su ask, gli strumenti che richiedono interazione dell’utente, le letture da percorsi di rete e le rimozioni rm e rmdir che interessano un percorso critico vengono negati anche quando una regola di permesso corrisponde. Nemmeno un’approvazione da parte di un hook PreToolUse sblocca una rimozione di un percorso critico o una lettura da un percorso di rete.
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 nel plan mode, anche quando una regola di permesso corrisponde o un hook PreToolUse restituisce allow. Passano invece per il tuo callback canUseTool. Su Claude Code v2.1.212 o successivo, i comandi shell che modificano i file, come touch e rm, raggiungono il tuo 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.
Modalità auto (auto)
Un modello classificatore esamina azioni come comandi shell e richieste di rete prima che vengano eseguite, e consente o blocca ciascuna di quelle che esamina. Per i modelli e i provider richiesti dalla modalità auto e l’ordine in cui valuta le azioni, consulta Eliminare le richieste di permesso con la modalità auto.
Se passi una sessione in modalità auto a un modello che la modalità auto non supporta, usando set_model(), setModel() o applyFlagSettings(), la sessione passa alla modalità default:
- Cosa vedi: un messaggio
systemcon sottotipostatusepermissionModeimpostato su"default", che il TypeScript SDK tipizza comeSDKStatusMessage. Da quel momento, le chiamate che richiedono approvazione e non corrispondono a nessuna regola di permesso raggiungono il tuo callbackcanUseTool. - Per tornare alla modalità auto: passa a un modello supportato, quindi chiama
set_permission_mode("auto")osetPermissionMode("auto"). Se ripristini il modello senza effettuare quella chiamata, la sessione rimane in modalitàdefault. Mentre il modello non supportato è attivo, la chiamata non riesce conCannot set permission mode to auto: auto mode unavailable for this model.
default dopo una chiamata a set_model(), setModel() o applyFlagSettings() richiede Claude Code v2.1.299 o successivo.
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