Configurare i permessi - Claude Code Docs

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.

Questa pagina copre le modalità di permesso e le regole. Per creare flussi di approvazione interattivi in cui gli utenti approvano o negano le richieste di strumenti in fase di esecuzione, vedi Gestire approvazioni e input dell’utente.

Come vengono valutati i permessi

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

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.

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.

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. In modalità dontAsk una regola di richiesta corrispondente viene negata invece, perché quella modalità non richiede mai conferma.

Modalità di permesso

Applica la modalità di permesso attiva. bypassPermissions approva tutto ciò che raggiunge questo passaggio. acceptEdits approva le operazioni su file. plan instrada 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. Le altre modalità passano oltre.

Regole di consentimento

Controlla le regole allow (da allowed_tools e settings.json). Se una regola corrisponde, lo strumento viene approvato.

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.

Diagramma del flusso di valutazione dei permessi in cinque passaggi che corrisponde ai passaggi precedenti: una richiesta di strumento passa attraverso hook, regole di negazione, 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.

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.

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. 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"
};

allowed_tools non vincola bypassPermissions. allowed_tools pre-approva solo gli strumenti che elenchi. Gli strumenti non elencati non vengono abbinati da alcuna regola di consentimento e passano alla modalità di permesso, dove bypassPermissions li approva. Impostare allowed_tools=["Read"] insieme a permission_mode="bypassPermissions" approva comunque ogni strumento, inclusi Bash, Write e Edit. Se hai bisogno di bypassPermissions ma vuoi bloccare strumenti specifici, usa disallowed_tools.

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; `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, a meno che non corrisponda una regola `ask` esplicita (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` (solo TypeScript)	Approvazioni classificate dal modello	Un classificatore di modello approva o nega ogni chiamata di strumento. Vedi Modalità Auto per la disponibilità

Eredità del subagente: Quando il genitore utilizza bypassPermissions, acceptEdits o auto, tutti i subagenti ereditano quella modalità e non può essere sovrascritta per subagente. I subagenti possono avere prompt di sistema diversi e comportamento meno vincolato rispetto al tuo agente principale, quindi ereditare bypassPermissions concede loro accesso completo e autonomo al sistema. Una regola ask esplicita forza comunque una richiesta.

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.

Al momento della query
Durante lo streaming

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

Chiama set_permission_mode() (Python) o setPermissionMode() (TypeScript) per cambiare la modalità a metà sessione. La nuova modalità ha effetto immediatamente per tutte le richieste di strumenti successive. Questo ti consente di iniziare in modo restrittivo e allentare i permessi man mano che la fiducia aumenta, ad esempio passando a acceptEdits dopo aver esaminato l’approccio iniziale di Claude.

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

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.

Usare con estrema cautela. Claude ha accesso completo al sistema in questa modalità. Usare solo in ambienti controllati in cui ti fidi di tutte le operazioni possibili.allowed_tools non vincola questa modalità. Ogni strumento viene approvato, non solo quelli che hai elencato. Le regole di negazione (disallowed_tools), le regole esplicite ask e gli hook vengono valutati prima del controllo della modalità e possono comunque bloccare uno strumento.

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à predefinita. 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. 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:

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

​Come vengono valutati i permessi

​Regole di consentimento e negazione

​Modalità di permesso

​Modalità disponibili

​Impostare la modalità di permesso

​Dettagli della modalità

​Modalità accetta modifiche (acceptEdits)

​Modalità non chiedere (dontAsk)

​Modalità ignora permessi (bypassPermissions)

​Modalità piano (plan)

​Risorse correlate

Come vengono valutati i permessi

Regole di consentimento e negazione

Modalità di permesso

Modalità disponibili

Impostare la modalità di permesso

Dettagli della modalità

Modalità accetta modifiche (`acceptEdits`)

Modalità non chiedere (`dontAsk`)

Modalità ignora permessi (`bypassPermissions`)

Modalità piano (`plan`)

Risorse correlate