SpyBara
Go Premium

agent-sdk/permissions.md 2026-10-22 22:58 UTC to 2026-10-23 22:59 UTC

This page contains 48 additions and 46 deletions.

2026
Thu 1 23:59 Fri 9 23:02 Sat 10 23:01 Sat 17 23:57 Mon 19 23:58 Tue 20 23:00 Wed 21 23:02 Thu 22 22:58 Fri 23 22:59 Mon 26 22:57 Tue 27 22:59 Fri 30 23:01

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:

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 deny e ask riportate di seguito; quelle vengono valutate indipendentemente dal risultato dell'hook.

Un hook PreToolUse che restituisce allow inoltre non può approvare un comando rm o rmdir la cui destinazione Claude Code riconosce come un percorso critico, come rm -rf ~. Per sapere cosa fa quell'allow nel plan mode, consulta Approvazioni degli hook nel plan mode.

2. Regole deny

Controllare le regole deny (da disallowed_tools e settings.json). Se una regola deny corrisponde, lo strumento viene bloccato, anche in modalità bypassPermissions. Le regole deny 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 ask

Controllare le regole ask da settings.json. Se una regola ask 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 allow 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 allow 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 rimozioni di percorsi critici riconosciute, che passano invece oltre.
  • 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 allow, in modo che le operazioni di scrittura non possano essere approvate automaticamente durante la pianificazione.
  • In altre modalità, la richiesta passa oltre.

5. Regole allow

Controllare le regole allow (da allowed_tools e settings.json). Se una regola corrisponde, lo strumento viene approvato. Anche 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 tue directory di lavoro o un comando Bash di sola lettura.

Le rimozioni di percorsi critici riconosciute non vengono approvate da una regola allow. 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à per i percorsi critici elenca cosa fa ogni modalità con esse.

Una regola allow 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, anche se un mod che hai installato può comunque approvare alcune di queste chiamate.

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.

Diagramma del flusso di valutazione delle autorizzazioni in sei passaggi che corrisponde ai passaggi precedenti: una richiesta di strumento passa attraverso hook, regole deny, regole ask, modalità di autorizzazione, regole allow e canUseTool. Hook, regole deny e canUseTool possono instradare verso il basso a Bloccato; bypass della modalità di autorizzazione, regole allow e canUseTool possono instradare verso l'alto a Esegui; le regole ask instradano a canUseTool.

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:

Le voci con uno specificatore come Bash(ls *) e la modalità acceptEdits non lo attivano, e le regole allow 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 allow e deny e modalità di autorizzazione. Per gli altri passaggi:

Regole allow e deny

allowed_tools e disallowed_tools (TypeScript: allowedTools / disallowedTools) aggiungono voci agli elenchi di regole allow e deny nel flusso di valutazione sopra descritto. Se nominate uno degli strumenti di tracciamento delle attività in allowed_tools, Claude Code abilita anche quegli strumenti 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 deny si comportano diversamente a seconda che nominino uno strumento o limitino un modello all'interno di uno.

Opzione Effetto
allowed_tools=["Read", "Grep"] Read e Grep sono approvati automaticamente, a parte le letture da percorsi di rete. Gli altri strumenti non elencati qui esistono ancora, e le chiamate ad essi che necessitano di approvazione passano alla modalità di permesso e a 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 che corrispondono a rm * come scritto vengono negate in ogni modalità di autorizzazione, inclusa bypassPermissions. Le altre chiamate Bash, incluso /bin/rm, passano attraverso la modalità di autorizzazione.
disallowed_tools=["*"] Ogni definizione di strumento viene rimossa dalla richiesta. I glob dei nomi degli strumenti sono supportati nelle regole deny: "*" corrisponde a ogni strumento e "mcp__*" corrisponde a ogni strumento MCP su tutti i server.

Le regole allow 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 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 deny 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.

[!WARNING]

Gli strumenti approvati automaticamente non raggiungono mai canUseTool. Una chiamata a uno strumento approvata in qualsiasi fase precedente, da acceptEdits o bypassPermissions, o da una regola allow, salta il callback canUseTool, quindi i controlli di autorizzazione che inserite lì vengono silenziosamente ignorati per quello strumento.

Nessuna regola allow approva automaticamente AskUserQuestion, gli strumenti MCP contrassegnati _meta["anthropic/requiresUserInteraction"], gli strumenti dei connettori che la tua organizzazione ha impostato su ask, o le rimozioni di percorsi critici riconosciute con rm e rmdir. In modalità dontAsk Claude Code nega queste chiamate senza invocare il callback. In altre modalità le prime tre raggiungono il callback. La tabella delle modalità per i percorsi critici elenca cosa fa ciascuna modalità con una rimozione di percorso critico. Il controllo che riconosce queste rimozioni può non rilevare alcuni comandi.

La copertura dipende dalla forma della voce: un nome semplice come Read o mcp__github__get_issue approva automaticamente ogni chiamata a quello strumento a parte tali eccezioni e le letture da percorsi di rete, mentre una regola limitata come Bash(npm test *) approva automaticamente solo le chiamate corrispondenti, e le altre chiamate Bash che necessitano di approvazione passano comunque al callback. Per i controlli che devono essere eseguiti su ogni chiamata a uno strumento, usa un hook PreToolUse: gli hook vengono eseguiti prima di ogni altro passaggio, e una negazione da parte di un hook si applica anche in modalità bypassPermissions.

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 le letture da percorsi di rete. Ogni altra chiamata che comporterebbe una richiesta di permesso viene invece negata, anche se un mod che hai installato può comunque approvare alcune di queste chiamate.

Le chiamate che non necessitano di approvazione in modalità default vengono eseguite indipendentemente dal fatto che tu le elenchi. Includono 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.

[!WARNING]

allowed_tools non vincola bypassPermissions. allowed_tools pre-approva gli strumenti che elencate. Gli altri strumenti non elencati non vengono abbinati da alcuna regola allow e passano attraverso la modalità di autorizzazione, dove bypassPermissions li approva. L'impostazione di allowed_tools=["Read"] insieme a permission_mode="bypassPermissions" approva comunque ogni strumento, inclusi Bash, Write e Edit. Se avete bisogno di bypassPermissions ma volete che strumenti specifici siano bloccati, utilizzate disallowed_tools.

Potete anche configurare le regole allow, deny e ask 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.

Con Claude Code v2.1.302 o successivo, la tua app si avvia in modalità default a meno che tu non imposti una modalità di permesso o che non ne riceva una da permissions.defaultMode nei suoi file di impostazioni. In modalità default, Claude Code nega qualsiasi chiamata a uno strumento che richieda approvazione, a meno che tu non la approvi tramite una regola allow, un hook, un callback canUseTool o uno strumento per le richieste di permesso. Se le chiamate agli strumenti vengono negate, consulta Chiamate agli strumenti negate in claude -p e nelle esecuzioni dell'Agent SDK.

Modalità disponibili

L'SDK supporta queste modalità di autorizzazione:

Modalità Descrizione Comportamento dello strumento
default Comportamento di autorizzazione standard Nessuna approvazione automatica basata sulla modalità; le chiamate che richiedono approvazione e non corrispondono a nessuna regola allow attivano il callback canUseTool
dontAsk Nega invece di chiedere Qualsiasi chiamata che altrimenti genererebbe una richiesta di conferma viene negata senza chiamare canUseTool, anche se un mod che hai installato può comunque approvare alcune di queste chiamate. Le chiamate approvate da allowed_tools o da regole allow in settings.json vengono eseguite, così come le chiamate che non richiedono approvazione in modalità default. Alcune chiamate, come le letture da percorsi di rete, vengono negate anche quando allowed_tools o una regola allow corrisponde. Per l'elenco, consulta Modalità non chiedere
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 autorizzazione Gli strumenti vengono eseguiti senza richieste di autorizzazione, ad eccezione delle azioni che nessuna modalità approva automaticamente. Utilizzare con cautela
plan Modalità di pianificazione Claude esplora e pianifica senza modificare i file sorgente; le modifiche ai file non vengono mai approvate automaticamente e richiedono il callback canUseTool
auto Approvazioni classificate dal modello Un classificatore del modello esamina azioni come comandi shell e richieste di rete, consentendo o bloccando ciascuna che esamina. Vedere Modalità Auto per la disponibilità e l'ordine di decisione

[!WARNING]

Ereditarietà dei subagent: Se la tua sessione principale è in plan mode, un subagent la cui AgentDefinition imposta permissionMode: "acceptEdits" viene comunque eseguito in plan mode. Le chiamate Edit e Write di quel subagent sui tuoi file sorgente passano comunque al tuo callback canUseTool. Il plan mode vale anche per i subagent che definisci, così che affidare il lavoro a uno di essi non permetta di aggirare la revisione preliminare del piano.

Il subagent eredita plan, acceptEdits, auto o bypassPermissions dalla sessione principale e, con una sessione principale in modalità default o dontAsk, viene eseguito nella modalità che imposti. Anche in questo caso, Claude Code non applica mai un valore "bypassPermissions" e applica un valore "auto" solo quando la modalità auto è disponibile per quel subagent. L'eccezione bypassPermissions richiede Claude Code v2.1.267 o successivo.

I subagent possono avere prompt di sistema diversi e comportamenti meno vincolati rispetto all'agente principale, quindi ereditare bypassPermissions concede loro accesso completo e autonomo al sistema. Le azioni che nessuna modalità approva automaticamente si applicano comunque.

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

Passa permission_mode (Python) o permissionMode (TypeScript) quando crei una query.

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

Durante lo streaming

Chiamare set_permission_mode() (Python) o setPermissionMode() (TypeScript) per modificare la modalità durante la sessione. La nuova modalità ha effetto immediatamente per tutte le successive richieste di strumenti. Questo consente di iniziare in modo restrittivo e allentare le autorizzazioni 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())

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 con rm o rmdir un percorso che Claude Code riconosce come percorso critico

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 permesso in una negazione, senza chiamare canUseTool, anche se un mod che hai installato può comunque approvare alcune di queste chiamate. Gli strumenti pre-approvati da allowed_tools, da regole allow in settings.json o da un hook vengono eseguiti normalmente. Vengono eseguite anche 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 di percorsi critici riconosciute vengono negati anche quando una regola allow corrisponde. Nemmeno un'approvazione da parte di un hook PreToolUse sblocca una rimozione riconosciuta di un percorso critico o una lettura da un percorso di rete. Il controllo che riconosce queste rimozioni può non individuare alcuni comandi.

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.

[!WARNING]

Utilizzare con estrema cautela. Claude ha accesso completo al sistema in questa modalità. Utilizzare solo in ambienti controllati in cui si fidano di tutte le possibili operazioni.

allowed_tools non vincola questa modalità. Ogni strumento è approvato, non solo quelli che avete elencato. Questi controlli si applicano comunque:

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 allow 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.

Nell'SDK TypeScript, 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 system con sottotipo status e permissionMode impostato su "default", che il TypeScript SDK tipizza come SDKStatusMessage. Da quel momento, le chiamate che richiedono approvazione e non corrispondono a nessuna regola allow raggiungono il tuo callback canUseTool.
  • Per tornare alla modalità auto: passa a un modello supportato, quindi chiama set_permission_mode("auto") o setPermissionMode("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 con Cannot set permission mode to auto: auto mode unavailable for this model.

Il passaggio alla modalità 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: