SpyBara
Go Premium

agent-sdk/permissions.md 2026-09-08 20:00 UTC to 2026-09-09 22:58 UTC

This page contains 48 additions and 29 deletions.

2026
Wed 9 22:58 Sat 12 03:02 Mon 14 22:58 Fri 18 23:58 Fri 25 23:58

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:

1

Hooks

Esegui hooks per primo. Un hook può negare la chiamata completamente o trasmetterla. Un hook che restituisce allow non salta le regole di negazione e richiesta di seguito; quelle vengono valutate indipendentemente dal risultato dell'hook. Un hook PreToolUse allow inoltre non può approvare una rimozione rm o rmdir che prende di mira un percorso critico.

2

Regole di negazione

Controlla 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

Controlla 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 consentimento corrisponde. In modalità dontAsk entrambi i casi vengono negati invece, perché quella modalità non richiede mai conferma. L'annotazione MCP richiede Claude Code v2.1.199 o successivo.

Gli strumenti del connettore claude.ai che la tua 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 consentimento corrisponde. Il callback riceve il motivo La tua organizzazione richiede l'approvazione per questo strumento. In modalità dontAsk la chiamata viene negata invece, perché quella modalità non richiede mai conferma.

4

Modalità di permesso

Applica la modalità di permesso attiva:

  • In modalità bypassPermissions, Claude Code approva tutto ciò che raggiunge questo passaggio tranne le rimozioni rm e rmdir che 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 tuo callback canUseTool indipendentemente dalle regole di consentimento, quindi le operazioni di scrittura non possono essere approvate automaticamente durante la pianificazione.
  • Nelle altre modalità, la richiesta passa oltre.
5

Regole di consentimento

Controlla le regole allow (da allowed_tools e settings.json). Se una regola corrisponde, lo strumento viene approvato. Le rimozioni rm e rmdir che prendono di mira un percorso critico non vengono mai approvate da una regola di consentimento: raggiungono il tuo callback nelle modalità che richiedono conferma, vanno al classificatore in modalità auto su Claude Code v2.1.218 o successivo, e vengono negate in modalità dontAsk.

6

Callback canUseTool

Se non risolto da nessuno dei precedenti, chiama il tuo callback canUseTool per una decisione. In modalità dontAsk, questo passaggio viene saltato e lo strumento viene negato.

Nell'SDK TypeScript, se imposti permissionPrompts: 'none', il tuo 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.

Diagramma del flusso di valutazione dei permessi in sei passaggi che corrisponde ai passaggi precedenti: una richiesta di strumento passa attraverso hook, regole di negazione, regole di richiesta, modalità di permesso, regole di consentimento e canUseTool. Hook, regole di negazione e canUseTool possono instradare verso Bloccato; bypass della modalità di permesso, regole di consentimento e canUseTool possono instradare verso Esegui; regole di richiesta instradano verso canUseTool. Diagramma del flusso di valutazione dei permessi in sei passaggi che corrisponde ai passaggi precedenti: una richiesta di strumento passa attraverso hook, regole di negazione, regole di richiesta, modalità di permesso, regole di consentimento e canUseTool. Hook, regole di negazione e canUseTool possono instradare verso Bloccato; bypass della modalità di permesso, regole di consentimento e canUseTool possono instradare verso Esegui; regole di richiesta instradano verso canUseTool.

Se passi 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 del processo Node.js una volta quando la query viene costruita. Il codice dell'avviso è CLAUDE_SDK_CAN_USE_TOOL_SHADOWED. Due configurazioni lo attivano:

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

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

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

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. Se nominate uno dei task-tracking tools in allowed_tools, Claude Code opta anche la sessione. Qualsiasi altro 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.

Opzione Effetto
allowed_tools=["Read", "Grep"] Read e Grep vengono approvati automaticamente. Gli strumenti non elencati qui esistono ancora e passano alla modalità di permesso e canUseTool.
disallowed_tools=["Bash"] La definizione dello strumento Bash viene rimossa dalla richiesta. Claude non vede lo strumento e non può tentarlo.
disallowed_tools=["Bash(rm *)"] Bash rimane disponibile. Le chiamate corrispondenti a rm * vengono negate in ogni modalità di permesso, inclusa bypassPermissions. Altre chiamate Bash passano alla modalità di permesso.
disallowed_tools=["*"] Ogni definizione di strumento viene rimossa dalla richiesta. I glob dei nomi degli strumenti sono supportati nelle regole di negazione: "*" corrisponde a ogni strumento e "mcp__*" corrisponde a ogni strumento MCP su tutti i server.

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 hai 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 permesso dei file.

Utilizza //path per un percorso del file system 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 tramite allowed_tools o disallowed_tools, ciò significa la directory di lavoro della sessione, quindi la regola non blocca /secrets su disco. Vedi Regole Read e Edit per i quattro moduli di ancoraggio e come le regole dai file di impostazioni si risolvono.

Per un agente bloccato, abbina allowedTools con permissionMode: "dontAsk". Gli strumenti elencati vengono approvati, a parte gli strumenti sempre-prompt nella Avvertenza sopra; 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:

Modalità Descrizione Comportamento dello strumento
default Comportamento di permesso standard Nessuna approvazione automatica; gli strumenti non abbinati attivano il tuo callback canUseTool
dontAsk Nega invece di richiedere Qualsiasi cosa non pre-approvata da allowed_tools o regole viene negata; gli strumenti del connettore che la tua organizzazione ha impostato su ask e gli strumenti che richiedono l'interazione dell'utente vengono negati anche se li hai pre-approvati, così come le rimozioni rm e rmdir che puntano a un percorso critico. canUseTool non viene mai chiamato
acceptEdits Accetta automaticamente le modifiche ai file Le modifiche ai file e le operazioni del filesystem (mkdir, rm, mv, ecc.) vengono approvate automaticamente
bypassPermissions Ignora i controlli di permesso Gli strumenti vengono eseguiti senza richieste di permesso, ad eccezione delle azioni che nessuna modalità approva automaticamente. Usare con cautela
plan Modalità di pianificazione Claude esplora e pianifica senza modificare i tuoi file sorgente; le modifiche ai file non vengono mai approvate automaticamente e richiedono il tuo callback canUseTool
auto Approvazioni classificate dal modello Un classificatore di modello approva o nega le richieste di permesso. Vedi Auto mode per la disponibilità

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.

Passa permission_mode (Python) o permissionMode (TypeScript) quando crei una query. Questa modalità si applica per l'intera sessione a meno che non venga modificata dinamicamente.

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())

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. In modalità acceptEdits, Claude Code non approva automaticamente la richiesta quando Claude:

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

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. Gli strumenti del connettore che la tua organizzazione ha impostato su ask, gli strumenti che richiedono l'interazione dell'utente e le rimozioni rm e rmdir che puntano a un percorso critico vengono negati anche quando una regola di consentimento corrisponde. Un'autorizzazione di hook PreToolUse non cancella nemmeno una rimozione di percorso critico. 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 gli usi degli strumenti senza richiedere, ad eccezione dei casi elencati nell'avvertenza di seguito. Gli hook vengono comunque eseguiti e possono bloccare le operazioni se necessario.

Modalità piano (`plan`)

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

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

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.

Per gli altri passaggi nel flusso di valutazione dei permessi: