SpyBara
Go Premium

permissions.md 2026-10-01 23:59 UTC to 2026-10-02 19:58 UTC

This page contains 130 additions and 119 deletions.

2026
Thu 1 23:59 Fri 2 20:57

Configurare i permessi

Controlla a cosa Claude Code può accedere e cosa può fare con regole di permesso granulari, modalità e criteri gestiti.

Claude Code supporta autorizzazioni granulari in modo che Lei possa specificare esattamente cosa l'agente è autorizzato a fare e cosa non può fare. Le impostazioni di autorizzazione possono essere archiviate nel controllo della versione e distribuite a tutti gli sviluppatori della Sua organizzazione, nonché personalizzate dai singoli sviluppatori.

Sistema di autorizzazione

Claude Code utilizza un sistema di autorizzazione a livelli per bilanciare potenza e sicurezza. La tabella mostra, per ogni tipo di strumento, se la modalità Manuale chiede prima che l'azione venga eseguita. Gli altri modalità di autorizzazione cambiano quali di questi ti chiedono; in modalità auto un classificatore esamina le azioni al tuo posto, e come il classificatore valuta le azioni elenca quali vede.

Tipo di strumento Esempio Approvazione richiesta Comportamento "Sì, non chiedere più"
Sola lettura Letture di file, Grep No, all'interno della directory di lavoro e directory aggiuntive N/A
Comandi Bash Esecuzione shell Sì, eccetto un insieme integrato di comandi di sola lettura Permanentemente per repository e comando
Modifica di file Edit/Write di file Sì Fino alla fine della sessione
Web fetch WebFetch Sì, eccetto un insieme integrato di domini di documentazione preapprovati Permanentemente per repository e dominio
Web search WebSearch Sì Permanentemente per repository

Una richiesta di permesso mostra cosa Claude sta per fare, seguito dalle tue opzioni. Questo esempio è la richiesta per un comando Bash, da una sessione in modalità Manuale:

Una richiesta di permesso di Claude Code intitolata Bash command. Sotto un suggerimento sulla modalità auto, mostra la descrizione 'Run the test suite', il comando npm test e la riga 'This command requires approval', quindi chiede 'Do you want to proceed?' con quattro opzioni: Yes; Yes, and don't ask again for: npm test *; Yes, and switch to auto mode; e No. Un piè di pagina elenca due tasti: Esc per annullare e Tab per modificare. Una richiesta di permesso di Claude Code intitolata Bash command. Sotto un suggerimento sulla modalità auto, mostra la descrizione 'Run the test suite', il comando npm test e la riga 'This command requires approval', quindi chiede 'Do you want to proceed?' con quattro opzioni: Yes; Yes, and don't ask again for: npm test *; Yes, and switch to auto mode; e No. Un piè di pagina elenca due tasti: Esc per annullare e Tab per modificare.

La terza opzione, Yes, and switch to auto mode, non compare in ogni richiesta.

Quando scegli "Sì, non chiedere più" e l'approvazione viene salvata permanentemente, come per un comando Bash o un dominio WebFetch, Claude Code salva la regola in .claude/settings.local.json alla radice del repository git, risolto attraverso worktrees al checkout principale. La regola si applica alle sessioni future ovunque in quel repository, incluse le sessioni avviate in sottodirectory e in worktrees. Un'approvazione di modifica di file non viene salvata nel file: come mostra la tabella, dura fino alla fine della sessione. In alcuni casi, come al di fuori di un repository git o su Windows, Claude Code non utilizza la radice del repository; Dove Claude Code cerca ogni file elenca quei casi e dove salva la regola invece.

Prima della v2.1.211, Claude Code salvava sempre la regola nella directory di avvio, quindi un'approvazione concessa in un worktree o sottodirectory non si applicava al resto del repository. Le regole che le versioni precedenti hanno salvato in una sottodirectory o worktree si applicano ancora alle sessioni avviate lì.

A volte un prompt di autorizzazione offre solo un'approvazione una tantum, senza opzione "non chiedere più" e senza opzione per consentire l'azione per il resto della sessione. Claude Code offre quelle opzioni solo quando il prompt può mostrarti tutto ciò che consentirebbero, quindi una regola che salvi da un prompt copre solo ciò che la sua opzione denominata. Quando un prompt offre solo l'approvazione una tantum, approva l'azione una volta, o aggiungi la regola tu stesso in /permissions.

Aggiungi un commento quando rispondi a un prompt di autorizzazione

Puoi allegare una nota a Claude quando approvi o neghi una singola azione. Sulla maggior parte dei prompt di autorizzazione, inclusi Bash, PowerShell, file e prompt di strumenti MCP, spostati su Sì o No e premi Tab per aprire un campo di commento su quell'opzione. I prompt WebFetch e browser non offrono il campo. Le opzioni che consentono l'azione per il resto della sessione o salvano una regola non ne accettano una neanche.

Con il campo aperto, digita il commento e poi premi uno di questi tasti:

  • Enter: invia la tua risposta con il commento allegato. Se lasci il campo vuoto, Claude Code invia la risposta senza un commento.
  • Tab: chiude il campo senza rispondere. Claude Code mantiene il testo che hai digitato e lo invia comunque se rispondi con quell'opzione.
  • Shift+Tab: su un prompt di file, come un prompt Edit o Write, chiude il campo come Tab. Prima della v2.1.235, premere Shift+Tab all'interno del campo selezionava invece l'opzione che consente l'azione per il resto della sessione, quindi Claude Code approvava l'azione per il resto della sessione e scartava il commento.

Claude Code consegna il commento diversamente a seconda di come hai risposto:

  • Sì: Claude Code esegue l'azione, quindi invia il tuo commento a Claude dopo il risultato.
  • No: Claude Code invia il tuo commento a Claude come motivo del rifiuto, e Claude continua a lavorare. Se selezioni No senza un commento su un prompt dalla conversazione principale, Claude Code interrompe il turno.

Gestire le autorizzazioni

Potete visualizzare e gestire le autorizzazioni degli strumenti di Claude Code con /permissions. Questa interfaccia utente elenca tutte le regole di autorizzazione e il file settings.json da cui provengono. Potete aprire la finestra di dialogo mentre Claude sta lavorando: quando aggiungete o rimuovete una regola, Claude Code applica la modifica a partire dalla prossima chiamata dello strumento di Claude nello stesso turno. Prima della versione 2.1.234, Claude Code metteva in coda il comando fino al termine del turno.

  • Le regole Allow consentono a Claude Code di utilizzare lo strumento specificato senza approvazione manuale.
  • Le regole Ask richiedono una conferma ogni volta che Claude Code tenta di utilizzare lo strumento specificato.
  • Le regole Deny impediscono a Claude Code di utilizzare lo strumento specificato.

Le regole vengono valutate in ordine: deny, quindi ask, quindi allow. La prima corrispondenza in quell'ordine determina il risultato, e la specificità della regola non cambia l'ordine.

Una regola deny ampia come Bash(aws *) blocca ogni chiamata corrispondente, incluse le chiamate che corrispondono anche a una regola allow più ristretta come Bash(aws s3 ls). Una regola allow non può creare un'eccezione da una regola deny. La stessa precedenza si applica tra ask e allow: una regola ask corrispondente richiede una conferma anche quando una regola allow più specifica corrisponde anche alla stessa chiamata.

Le regole deny si comportano diversamente a seconda che denominino uno strumento o che limitino un modello all'interno di uno. Un nome di strumento semplice come Bash rimuove lo strumento dal contesto di Claude interamente, quindi Claude non lo vede mai. Se aggiungete tale regola a metà sessione, Claude non può chiamare lo strumento dalla sua prossima chiamata dello strumento in poi; Denying an entire tool spiega cosa accade a una definizione che Claude ha già visto. Una regola limitata come Bash(rm *) lascia lo strumento disponibile e blocca le chiamate corrispondenti quando Claude tenta di utilizzarle.

La rimozione con nome semplice si applica a ogni strumento tranne EndConversation: una regola deny non può rimuoverlo mentre rimane qualsiasi altro strumento, e una regola ask non lo richiede mai.

Quando la modalità auto è disponibile per la vostra sessione, la finestra di dialogo include anche le regole del classificatore della modalità auto. Selezionate la scheda Auto mode per visualizzarle.

Modalità di autorizzazione

Claude Code supporta diverse modalità di autorizzazione che controllano come approva le chiamate di strumenti. Vedi Permission modes per quando utilizzare ciascuna. Per modificare la modalità in cui iniziano le sessioni, imposta defaultMode nei tuoi file di impostazioni. Which mode a session starts in copre il valore predefinito integrato per ogni piano e cosa legge l'estensione VS Code.

Modalità Descrizione
default Richiede l'autorizzazione al primo utilizzo di ogni strumento. Etichettato come Manual nella CLI, nelle estensioni VS Code e JetBrains, e nell'app desktop, e Claude Code accetta manual come alias. L'etichetta e l'alias richiedono Claude Code v2.1.200 o successivo. L'etichetta dell'app desktop non dipende dalla tua versione CLI
acceptEdits Accetta automaticamente le modifiche ai file e i comandi comuni del filesystem come mkdir, touch, mv e cp per i percorsi nella directory di lavoro o additionalDirectories
plan Claude legge i file ed esegue comandi shell di sola lettura per esplorare ma non modifica i tuoi file sorgente; con auto mode disponibile, i comandi approvati dal classificatore vengono eseguiti anche. Etichettato Plan nella CLI e nell'estensione VS Code
auto Viene eseguito senza prompt di routine; prima che azioni come comandi shell e richieste di rete vengano eseguite, un classificatore in background verifica che si allineino con la tua richiesta
dontAsk Nega automaticamente ogni chiamata che altrimenti richiederebbe un prompt; le letture di file nelle tue directory di lavoro e altre azioni che non richiedono approvazione vengono comunque eseguite, così come gli strumenti pre-approvati tramite /permissions o regole permissions.allow. AskUserQuestion, strumenti MCP contrassegnati requiresUserInteraction, e strumenti connector che la tua organizzazione ha impostato su ask nelle sessioni in cui tale impostazione raggiunge Claude Code vengono negati anche se li hai consentiti
bypassPermissions Salta i prompt di autorizzazione, ad eccezione delle azioni che nessuna modalità auto-approva

Per prevenire che la modalità bypassPermissions o auto venga utilizzata, imposta permissions.disableBypassPermissionsMode o permissions.disableAutoMode su "disable" in qualsiasi file di impostazioni. Questi sono più utili nelle impostazioni gestite dove non possono essere ignorati.

Sintassi delle regole di autorizzazione

Le regole di autorizzazione seguono il formato Tool o Tool(specifier). Le parentesi all'interno dello specificatore sono letterali, quindi un comando o un percorso che le contiene non necessita di escape.

Corrispondere a tutti gli utilizzi di uno strumento

Per corrispondere a tutti gli utilizzi di uno strumento, utilizzate solo il nome dello strumento senza parentesi:

Regola Effetto
Bash Corrisponde a tutti i comandi Bash
WebFetch Corrisponde a tutte le richieste di web fetch
Read Corrisponde a tutte le letture di file

Bash(*) è equivalente a Bash e corrisponde a tutti i comandi Bash. Come regola di negazione, entrambe le forme rimuovono lo strumento dal contesto di Claude.

Utilizzare gli specificatori per il controllo granulare

Aggiungete uno specificatore tra parentesi per corrispondere a utilizzi specifici dello strumento:

Regola Effetto
Bash(npm run build) Corrisponde al comando esatto npm run build
Read(./.env) Corrisponde alla lettura del file .env nella directory corrente
WebFetch(domain:example.com) Corrisponde alle richieste di fetch a example.com

Corrispondere per parametro di input

Le regole di negazione e richiesta possono corrispondere a un parametro di input di primo livello su qualsiasi strumento integrato con Tool(param:value).

Per corrispondere a un parametro su uno strumento MCP, passate una regola di negazione con --disallowedTools. Quando Claude Code carica un file di impostazioni, salta qualsiasi regola mcp__ che ha parentesi. Claude Code elenca la regola saltata nella finestra di dialogo delle impostazioni non valide quando inizia una sessione interattiva e nell'output di claude doctor.

Una regola di parametro corrisponde quando Claude chiama lo strumento con quel parametro impostato su quel valore esatto. Una regola di autorizzazione per un valore di parametro non stabilirerebbe che la chiamata è sicura nel complesso, quindi le regole di autorizzazione continuano a utilizzare la sintassi dello specificatore di ogni strumento. Questo funziona per qualsiasi parametro scalare che lo strumento accetta:

Regola Corrisponde
Agent(model:opus) Chiamate Agent che richiedono il livello di modello Opus
Agent(isolation:worktree) Chiamate Agent che richiedono un git worktree
Bash(run_in_background:true) Chiamate Bash che vengono eseguite in background

La corrispondenza dei parametri segue queste regole:

  • Il nome del parametro deve essere un campo diretto dell'input dello strumento, come model nello strumento Agent. I campi annidati all'interno di un oggetto o di un array non sono corrispondibili
  • Ogni regola nomina un parametro. Per controllare sia model che isolation, scrivete due regole, Agent(model:opus) e Agent(isolation:worktree), piuttosto che combinarle in una sola regola
  • Il valore supporta * come carattere jolly che corrisponde a qualsiasi sequenza di caratteri, quindi Agent(isolation:*) corrisponde a qualsiasi valore di isolamento esplicito. Senza * la corrispondenza è esatta
  • Un parametro che il modello omette non viene mai corrispondente, quindi Agent(model:*) non corrisponde a una chiamata che lascia model non impostato
  • Il valore viene confrontato con l'input letterale che Claude invia, prima di qualsiasi normalizzazione. Agent(model:opus) corrisponde all'alias opus ma non a un ID modello completo
  • Una regola di negazione Skill(skill:<name>) invece corrisponde alla skill sotto uno qualsiasi dei suoi nomi, come il suo alias o nome visualizzato
  • Eseguite con --verbose per vedere i nomi e i valori dei parametri esatti in ogni chiamata dello strumento
  • Lo spazio intorno ai due punti viene ignorato

Non potete corrispondere al campo di contenuto primario di uno strumento in questo modo: command per Bash e PowerShell, file_path per Read, Edit e Write, path per Grep e Glob, notebook_path per NotebookEdit, e url per WebFetch. Una regola come Bash(command:rm *) sarebbe aggirabile da un comando composto, quindi Claude Code la ignora e emette un avviso all'avvio. Utilizzate invece Bash(rm *), Read(./path), o WebFetch(domain:host).

Modelli con caratteri jolly

Un * in una regola Bash corrisponde a qualsiasi testo, inclusi gli spazi, quindi una regola copre una famiglia di comandi. Una regola senza * corrisponde a un comando esatto.

Scrivete il comando che volete che Claude esegua senza chiedere, e sostituite le parti che variano con *. Con questa configurazione, Claude Code esegue script npm e commit git senza chiedere e rifiuta comandi che iniziano con git push. Un push scritto in un altro modo, come git -C . push, non corrisponde alla regola; consultate a cosa non corrisponde una regola Bash.

{
  "permissions": {
    "allow": [
      "Bash(npm run *)",
      "Bash(git commit *)"
    ],
    "deny": [
      "Bash(git push *)"
    ]
  }
}

Un * può andare ovunque nella regola: all'inizio, nel mezzo, o alla fine. Ogni riga mostra una regola, i comandi che corrisponde, e i comandi vicini che non corrisponde:

Scrivete Corrisponde Non corrisponde
Bash(npm run build) npm run build npm run build --watch
Bash(npm run *) npm run build, npm run test --watch, npm run npm install
Bash(git log * main) git log --oneline main, git log -5 main, git log --output=<file> main git log main, git push origin main
Bash(git * main) git merge main, git push origin main, git -c core.fsmonitor=<script> diff main git log
Bash(* --version) node --version, bash -c 'echo hi' --version node -v
Bash(ls *) ls -la, ls lsof
Bash(ls*) ls -la, lsof
Bash(* --help *) npm --help x npm --help

Tre regole di corrispondenza producono quelle righe:

  • Il * sta al posto di qualsiasi testo che si trova al suo posto. In Bash(git * main), sta al posto del sottocomando, quindi Claude Code corrisponde a ogni sottocomando git e a ogni opzione prima di esso. Questo include -c, che fa eseguire a git un programma che nominate. In Bash(* --version), il * sta al posto del programma, quindi qualsiasi programma corrisponde.
  • Un * alla fine, con uno spazio prima di esso, corrisponde anche al comando nudo. Bash(ls *) corrisponde a ls, e Bash(git log *) corrisponde a git log. Questo vale solo quando il * finale è l'unico carattere jolly della regola: Bash(* --help *) corrisponde a npm --help x ma non a npm --help.
  • Lo spazio prima di un * finale fa parte della regola. Bash(ls *) richiede uno spazio dopo ls, quindi lsof non corrisponde. Bash(ls*) non ha spazio, quindi corrisponde anche a lsof.

Il suffisso :* è un modo equivalente per scrivere un carattere jolly finale, quindi Bash(ls:*) corrisponde agli stessi comandi di Bash(ls *).

La finestra di dialogo di autorizzazione scrive la forma separata da spazi quando selezionate "Sì, non chiedere più" per un prefisso di comando. La forma :* è riconosciuta solo alla fine di un modello. In un modello come Bash(git:* push), i due punti vengono trattati come un carattere letterale e non corrisponderanno ai comandi git.

Caratteri jolly nei nomi degli strumenti

Le regole di negazione e richiesta accettano anche modelli glob nella posizione del nome dello strumento. Il modello deve corrispondere al nome completo dello strumento: "*" corrisponde a ogni strumento, e "mcp__*" corrisponde a ogni strumento MCP su tutti i server. Uno strumento corrispondente a una regola di negazione con nome semplice viene rimosso dal contesto di Claude, lo stesso di un nome di strumento semplice, inclusa l'eccezione EndConversation: una negazione glob non può rimuoverlo mentre rimane qualsiasi altro strumento, e una richiesta glob non lo chiede mai. Questa configurazione nega ogni strumento MCP:

{
  "permissions": {
    "deny": [
      "mcp__*"
    ]
  }
}

Le regole di autorizzazione accettano globs nei 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_. Un glob di autorizzazione non ancorato come "*", "B*", o "mcp__*" viene saltato con un avviso e non approva automaticamente nulla.

Una regola di negazione o richiesta il cui nome dello strumento non corrisponde a nessuno strumento noto produce un avviso all'avvio per catturare gli errori di digitazione. I nomi degli strumenti contenenti _ o * sono esenti dal controllo, e così pure i nomi degli strumenti che Claude Code ha rimosso, come TaskOutput.

L'etichetta mostrata per uno strumento nella trascrizione e nella finestra di dialogo di autorizzazione può differire dal suo nome canonico. Ad esempio, lo strumento etichettato Stop Task nella trascrizione ha il nome canonico TaskStop. Le regole di autorizzazione e i matcher di hook non corrispondono all'etichetta, quindi una regola scritta come Stop Task non corrisponde. Per le regole di negazione e richiesta, l'avviso all'avvio di cui sopra cattura la mancata corrispondenza. Utilizzate i nomi canonici elencati nel riferimento degli strumenti.

Regole di permesso specifiche dello strumento

Bash

Le regole Bash corrispondono all'intero testo del comando, con * che rappresenta qualsiasi testo. Modelli con caratteri jolly mostra a quali comandi corrisponde ogni forma di regola e dove mettere il *. Il resto di questa sezione spiega come Claude Code gestisce la corrispondenza per i comandi composti e i wrapper, a cosa non corrisponde una regola, i comandi di sola lettura e i reindirizzamenti.

Comandi composti

Le regole deny e ask si applicano quando un qualsiasi sottocomando corrisponde, incluso un comando annidato all'interno di una subshell, di una sostituzione di comando o del corpo di un costrutto di controllo di flusso come un ciclo for. Una regola ask come Bash(git clean *) ti chiede comunque conferma per cd /tmp && git clean -f o echo "$(git clean -f)", anche in modalità auto.

Quando && o || non ha nulla dopo, come in npm test &&, Claude Code tratta il comando come non analizzabile e non lo divide in sottocomandi per la corrispondenza delle regole allow, quindi una regola come Bash(npm *) non lo approva.

Quando approvi un comando composto con "Sì, non chiedere più", Claude Code salva una regola separata per ogni sottocomando che richiede approvazione, anziché una singola regola per l'intera stringa composta. Ad esempio, approvando git status && npm test viene salvata una regola per npm test, quindi le future invocazioni di npm test vengono riconosciute indipendentemente da cosa precede &&. I sottocomandi come cd verso una directory al di fuori delle tue directory di lavoro generano una propria regola Read per quel percorso. Per un singolo comando composto possono essere salvate fino a 5 regole.

Wrapper

Prima di confrontare le regole Bash, Claude Code rimuove un insieme fisso di wrapper, quindi una regola come Bash(npm test *) corrisponde anche a timeout 30 npm test. I wrapper rimossi sono timeout, time, nice, nohup e stdbuf, più i builtin della shell command e builtin, e noglob di zsh. Ognuno esegue il proprio argomento come comando effettivo. Due forme correlate non vengono rimosse: la forma di interrogazione command -v, che cerca un comando anziché eseguirlo, e nocorrect di zsh.

Claude Code rimuove anche un'assegnazione iniziale di determinate variabili d'ambiente note come sicure, quindi Bash(npm test *) corrisponde a NODE_ENV=test npm test. Una regola allow non supera l'assegnazione di qualsiasi altra variabile. Una regola deny o ask supera qualsiasi assegnazione iniziale, quindi Bash(rm *) in deny corrisponde comunque a FOO=bar rm -rf tmp/.

Anche xargs senza opzioni viene rimosso, quindi Bash(grep *) corrisponde a xargs grep pattern. La rimozione si applica solo quando xargs non ha flag: un'invocazione come xargs -n1 grep pattern viene confrontata come comando xargs, quindi le regole scritte per il comando interno non la coprono.

Questo elenco di wrapper è integrato e non è configurabile. I runner di ambienti di sviluppo come direnv exec, devbox run, mise exec, npx e docker exec non sono nell'elenco. Poiché questi strumenti eseguono i propri argomenti come comando, una regola come Bash(devbox run *) corrisponde a qualsiasi cosa venga dopo run, incluso devbox run rm -rf .. Per approvare il lavoro all'interno di un runner di ambiente, scrivi una regola specifica che includa sia il runner sia il comando interno, come Bash(devbox run npm test). Aggiungi una regola per ogni comando interno che vuoi consentire.

I wrapper exec come watch, setsid, ionice e flock non possono essere approvati automaticamente da una regola di prefisso come Bash(watch *), quindi in modalità Manual chiedono sempre conferma. Lo stesso vale per find con -exec o -delete: una regola Bash(find *) non copre queste forme. Per approvare un'invocazione specifica, scrivi una regola a corrispondenza esatta per l'intera stringa del comando.

A cosa non corrisponde una regola Bash

Una regola Bash corrisponde al testo del comando che Claude scrive, dopo che Claude Code ha diviso i comandi composti e rimosso i wrapper. Non corrisponde allo stesso programma invocato in una forma diversa, quindi una regola deny o ask copre l'invocazione che Claude di solito produce e non costituisce un confine di sicurezza intorno al programma. Queste regole in deny o ask fermano la prima forma e non le altre:

Regola Ferma Non ferma
Bash(curl *) curl https://example.com /usr/bin/curl https://example.com, sh -c 'curl https://example.com'
Bash(rm *) rm -rf build/ /bin/rm -rf build/, bash -c 'rm -rf build/'
Bash(git push *) git push origin main git -C . push origin main, git -c push.default=current push origin main, git 'push' origin main

Le tue altre regole e la modalità di permesso decidono i comandi nell'ultima colonna.

Per un'applicazione dei vincoli su filesystem e rete che non dipenda dal testo del comando, usa il sandboxing. Per ispezionare l'intero testo del comando con la tua logica prima che venga eseguito, usa un hook PreToolUse.

Comandi di sola lettura

Claude Code riconosce un insieme integrato di comandi Bash come di sola lettura e li esegue senza una richiesta di permesso in ogni modalità, salvo quanto modificato da permissions.blockReadsOutsideWorkingDirectories per i percorsi al di fuori delle tue directory di lavoro. L'insieme include ls, cat, echo, pwd, head, tail, grep, find, wc, which, diff, stat, du, cd e le forme di sola lettura di git. L'insieme non è configurabile; per richiedere una conferma per uno di questi comandi, aggiungi una regola ask o deny per quel comando. In modalità auto, questi comandi possono anche attendere la revisione del classificatore; consulta come il classificatore valuta le azioni.

Un reindirizzamento come ls > out.txt aggiunge un controllo sulla destinazione. Consulta Reindirizzamenti.

I pattern glob senza virgolette sono consentiti per i comandi i cui flag sono tutti di sola lettura, quindi ls *.ts e wc -l src/*.py vengono eseguiti senza richiesta di conferma.

In modalità Manual, i comandi di questo insieme chiedono comunque conferma nei seguenti casi:

  • Glob senza virgolette per comandi con flag in grado di scrivere: i comandi con flag in grado di scrivere o eseguire, come find, sort, sed e git, chiedono conferma quando è presente un glob senza virgolette, perché il glob potrebbe espandersi in un flag come -delete.
  • docker puntato a un altro daemon: le forme di sola lettura di docker chiedono conferma quando il comando contiene un flag che seleziona un daemon diverso, come -H, --context o --url e --connection di Podman.
  • file con flag che aprono percorsi: file chiede conferma quando riceve -m/--magic-file o -f/--files-from, perché questi flag fanno sì che file apra i percorsi indicati nel valore del flag.
  • Percorsi di rete su Windows: un comando i cui argomenti includono un percorso di rete (UNC), come \\server\share\file, chiede conferma perché l'accesso a un percorso di rete può inviare le tue credenziali Windows all'host indicato. Lo stesso controllo si applica ai comandi dello strumento PowerShell.
  • Scritture su variabili speciali della shell: un comando che imposta, rimuove o itera su determinate variabili speciali della shell, come PATH o IFS, chiede conferma anche quando il resto del comando è di sola lettura.
  • Comandi che l'analisi non riesce a interpretare: quando Claude Code non riesce ad analizzare completamente un comando, chiede l'approvazione invece di trattarlo come di sola lettura. I comandi più lunghi di 10.000 caratteri chiedono sempre conferma perché superano il limite che l'analisi è in grado di interpretare.

Anche un cd verso un percorso all'interno della tua directory di lavoro o di una directory aggiuntiva è di sola lettura, e un comando composto come cd packages/api && ls viene eseguito senza richiesta di conferma quando ogni parte soddisfa i requisiti da sola. Queste combinazioni chiedono conferma anche quando ogni parte è di sola lettura:

  • cd con git: chiede conferma quando il cd passa a una directory diversa, poiché eseguire git in una nuova directory può eseguire gli hook di quella directory. Un cd la cui destinazione si risolve nella directory di lavoro corrente non ha effetto e non attiva la richiesta di conferma.
  • cd con un reindirizzamento: chiede conferma quando Claude Code non riesce a determinare rispetto a quale directory si risolve la destinazione del reindirizzamento dopo l'esecuzione del cd. Un comando la cui unica destinazione di reindirizzamento è /dev/null, come cd app; grep -r pattern . 2>/dev/null, non chiede conferma, perché /dev/null non dipende dalla directory di lavoro.

Reindirizzamenti

Quando un comando reindirizza l'output o l'input, Claude Code controlla la destinazione del reindirizzamento rispetto alle tue regole sui file come se Claude avesse scritto o letto direttamente quel file:

  • Reindirizzamenti di output: per > file, >> file o 2> file, il controllo copre le tue regole allow e deny Edit, i percorsi protetti e le directory di lavoro. Una regola come Bash(git commit *) consente il comando, non la destinazione. Una destinazione che inizia con ~ o contiene un carattere glob richiede la tua approvazione.
  • Reindirizzamenti di input: per < file, il controllo copre le tue regole allow e deny Read e le directory di lavoro. Una destinazione al di fuori delle directory di lavoro richiede la tua approvazione, a meno che una regola allow non la copra. Una destinazione che contiene un pattern glob, o un percorso relativo che segue un cd nello stesso comando, richiede la tua approvazione anche quando una regola allow la copre. Claude Code controlla le destinazioni di input dalla v2.1.257 in poi.

Le destinazioni che non corrispondono a un file non vengono controllate: /dev/null, le forme con descrittore di file come 2>&1 e <&3, e gli here-doc e here-string.

Claude Code controlla anche i file scritti da un comando tee, anche all'interno di una pipeline come make | tee build.log. Il controllo copre le tue regole allow e deny Edit, i percorsi protetti e le directory di lavoro. Una regola allow come Bash(tee *) non copre una destinazione al di fuori delle directory di lavoro. Claude Code controlla le destinazioni di tee dalla v2.1.269 in poi.

PowerShell

Le regole di permesso PowerShell hanno la stessa forma delle regole Bash. I caratteri jolly * corrispondono in qualsiasi posizione, il suffisso :* equivale a un * finale e una regola PowerShell senza argomenti o PowerShell(*) corrisponde a ogni comando. Questa configurazione consente i comandi Get-ChildItem e git commit e blocca Remove-Item:

{
  "permissions": {
    "allow": [
      "PowerShell(Get-ChildItem *)",
      "PowerShell(git commit *)"
    ],
    "deny": [
      "PowerShell(Remove-Item *)"
    ]
  }
}

Gli alias comuni vengono ricondotti alla forma canonica prima della corrispondenza. Una regola scritta per il nome del cmdlet corrisponde anche ai suoi alias, quindi PowerShell(Get-ChildItem *) corrisponde anche a gci, ls e dir. La corrispondenza non distingue tra maiuscole e minuscole.

Claude Code analizza l'AST di PowerShell e controlla ogni comando di un comando composto in modo indipendente. Gli operatori di pipeline |, i separatori di istruzione ; e, su PowerShell 7+, gli operatori di concatenazione && e || dividono un comando composto in sottocomandi. Una regola deve corrispondere a ogni sottocomando affinché il comando composto sia consentito.

Read e Edit

Per impedire agli strumenti per i file di Claude di leggere un file o una directory, aggiungi una regola deny Read per il suo percorso, come Read(./.env) o Read(./secrets/**); Escludere i file sensibili contiene un esempio pronto da incollare. Se il tuo progetto ha un file .claudeignore, questo non ha alcun effetto, quindi sposta le sue voci in regole deny Read.

Le regole Edit si applicano a tutti gli strumenti integrati che modificano i file. Claude fa il possibile per applicare le regole Read a tutti gli strumenti integrati che leggono file, come Grep e Glob, alle menzioni @file nei tuoi prompt e alla selezione e al contesto dei file aperti che un IDE connesso condivide con Claude.

Una regola deny Read blocca anche gli strumenti Edit e Write sullo stesso percorso, inclusa la creazione di un nuovo file in quella posizione. NotebookEdit non è coperto, quindi aggiungi una regola deny Edit per i percorsi che nessuno strumento deve modificare. Il controllo richiede Claude Code v2.1.208 o successiva per le modifiche, e v2.1.228 o successiva per le scritture.

Claude Code controlla i permessi sui file solo rispetto alle regole Edit(path) e Read(path). Se invece scrivi una regola di percorso per Write, NotebookEdit, Glob o lo strumento legacy MultiEdit, Claude Code accetta la regola ma non la consulta mai e mostra un avviso all'avvio, tranne nel caso di una regola Glob passata in --allowedTools. Usa Edit(docs/**) al posto di Write(docs/**), NotebookEdit(docs/**) o MultiEdit(docs/**), e Read(docs/**) al posto di Glob(docs/**). Claude Code non mostra avvisi per una regola con il solo nome dello strumento e senza percorso, come una regola deny per Write; applica quella regola a livello di strumento ovunque. Richiede Claude Code v2.1.210 o successiva.

Le regole Read e Edit usano entrambe la sintassi dei pattern gitignore con quattro tipi di pattern distinti; per i pattern di directory a segmento singolo, la profondità di corrispondenza dipende anche dal tipo di regola, come descritto più avanti in questa sezione:

Pattern Significato Esempio Corrisponde a
//path Percorso assoluto dalla radice del filesystem Read(//Users/alice/secrets/**) /Users/alice/secrets/**
~/path Percorso dalla directory home Read(~/Documents/*.pdf) /Users/alice/Documents/*.pdf
/path Percorso relativo all'origine delle impostazioni Edit(/src/**/*.ts) <primary working directory>/src/**/*.ts nelle impostazioni di progetto
path o ./path Percorso relativo alla directory corrente Read(*.env) <cwd>/*.env

Un pattern /path si ancora a una directory associata all'origine delle impostazioni che lo definisce, quindi la stessa regola corrisponde a posizioni diverse a seconda di dove la inserisci:

Regola definita in /path si risolve in
Impostazioni di progetto in .claude/settings.json <primary working directory>/path
Impostazioni locali in .claude/settings.local.json <primary working directory>/path
Impostazioni utente in ~/.claude/settings.json ~/.claude/path
Un file passato con --settings <file> <directory of file>/path
Flag CLI o regole di sessione <primary working directory>/path

Una regola che aggiungi tramite /permissions segue la riga del file di impostazioni in cui la salvi.

Dalla v2.1.211 in poi, le regole delle impostazioni locali si ancorano alla directory di lavoro principale della sessione, non alla radice del repository in cui Claude Code memorizza il file. In una sessione avviata nella radice del repository, le due directory coincidono; in una sessione in un worktree, una regola condivisa come Edit(/src/**) corrisponde alla directory src/ di quel worktree.

Una regola deny come Read(/secrets/**) nelle impostazioni utente blocca ~/.claude/secrets/**, non una directory secrets nel tuo progetto. Per scrivere nelle impostazioni utente una regola che si applichi all'interno di ogni progetto, usa invece un percorso assoluto // o un percorso relativo alla home ~/.

Su Windows, i percorsi vengono normalizzati in forma POSIX prima della corrispondenza. C:\Users\alice diventa /c/Users/alice, quindi usa //c/**/.env per corrispondere ai file .env in qualsiasi punto di quell'unità. Per la corrispondenza su tutte le unità, usa //**/.env.

Esempi:

  • Edit(/docs/**): modifiche in <primary working directory>/docs/, non in /docs/ né in <primary working directory>/.claude/docs/
  • Read(~/.zshrc): legge il file .zshrc della tua directory home
  • Edit(//tmp/scratch.txt): modifica il percorso assoluto /tmp/scratch.txt
  • Read(src/**): come regola allow, legge solo da <current-directory>/src/; come regola deny o ask, corrisponde a una directory src a qualsiasi profondità sotto la directory corrente

Una regola corrisponde solo ai file sotto il suo punto di ancoraggio; entro questo limite, la profondità di corrispondenza dipende dalla forma del pattern e, per i pattern di directory a segmento singolo, dal tipo di regola, come descritto di seguito. I nomi di file semplici seguono la semantica di gitignore e corrispondono a qualsiasi profondità, quindi Read(.env) e Read(**/.env) sono equivalenti:

Regola deny Blocca Non blocca
Read(.env) o Read(**/.env) qualsiasi .env nella directory corrente o sotto di essa .env in una directory padre o in un altro progetto
Read(//**/.env) qualsiasi .env in qualsiasi punto del filesystem nulla; la regola è ancorata alla radice del filesystem

Un pattern relativo con un singolo segmento di directory, come src/**, corrisponde a profondità diverse a seconda del tipo di regola:

  • Regole allow: Edit(src/**) corrisponde solo a <cwd>/src e ai file al suo interno. Per consentire un nome di directory a qualsiasi profondità, scrivi Edit(**/src/**).
  • Regole deny e ask: Read(secrets/**) corrisponde a una directory chiamata secrets a qualsiasi profondità sotto la directory corrente, quindi la regola si applica anche alle copie annidate.

Ogni altra forma di pattern corrisponde alla stessa profondità in ogni tipo di regola: Edit(/src/**) e Edit(src/components/**) corrispondono solo nella posizione a cui sono ancorati, mentre Edit(**/src/**) corrisponde a qualsiasi profondità.

L'esempio seguente mostra ogni forma di pattern applicata a un progetto con una directory src/ di primo livello e una copia annidata sotto vendor/:

<current-directory>/
├── src/
│   └── app.ts
└── vendor/
    └── pkg/
        └── src/
            └── lib.js
Regola Corrisponde a src/app.ts Corrisponde a vendor/pkg/src/lib.js
Edit(src/**) come regola allow Sì No
Edit(src/**) come regola deny o ask Sì Sì
Edit(/src/**) in qualsiasi tipo di regola Sì No
Edit(**/src/**) in qualsiasi tipo di regola Sì Sì

Quando approvi un percorso di file con "Sì, non chiedere più", Claude Code applica l'escape ai caratteri speciali dei pattern gitignore presenti in quel percorso, come [, ] e *, in modo che la regola generata corrisponda solo al percorso letterale che hai approvato. Le regole che scrivi tu non vengono sottoposte a escape. Prima della v2.1.202, Claude Code salvava il percorso senza escape, quindi una regola generata per una directory chiamata [2024-06] Reports poteva non corrispondere al proprio percorso o corrispondere a directory sorelle non previste.

Non è necessario applicare l'escape alle parentesi tonde in un percorso, quindi Edit(./Finance (2024)/**) corrisponde alla cartella Finance (2024) così come è scritta.

Una regola deny o ask il cui percorso non è utilizzabile come pattern gitignore protegge comunque quel percorso esatto. Una regola allow con un pattern non utilizzabile non approva nulla.

Un pattern deny o ask che inizia con ! è una negazione gitignore. Esclude i percorsi a cui corrisponde dalle regole path o ./path elencate prima di esso. Nell'elenco deny di un file di impostazioni, Read(*.env) seguito da Read(!sample.env) blocca ogni file il cui nome termina con .env a qualsiasi profondità, tranne i file chiamati sample.env. Una regola ! elencata per prima non esclude nulla.

L'esclusione si applica solo alle regole della stessa origine. Un Read(!.env) nelle impostazioni di progetto o in --disallowedTools non annulla una regola deny Read(./.env) proveniente dalle impostazioni gestite o da qualsiasi altro file di impostazioni.

Due limiti restringono ciò che un pattern ! può escludere:

  • Claude Code interpreta un pattern ! come relativo alla directory corrente anche quando /, ~/ o // segue il !, quindi il pattern non può raggiungere una regola ancorata con uno di questi prefissi. Read(!~/notes/public/**) non esclude nulla da Read(~/notes/**).
  • Un'esclusione non può riaprire un file all'interno di una directory che una regola blocca per intero. Con Read(secrets/**) e Read(!secrets/public/**), Claude Code blocca comunque secrets/public insieme al resto di secrets.

Quando un percorso di file richiesto da Claude passa attraverso un collegamento simbolico, il controllo dei permessi copre due percorsi: quello richiesto da Claude e il file in cui si risolve. Questo vale per i collegamenti simbolici su macOS, Linux e Windows, e per le giunzioni di directory su Windows.

Come le regole corrispondono a un percorso con collegamento simbolico

Le regole allow e deny trattano in modo diverso il percorso richiesto e il file in cui si risolve:

  • Regole allow: si applicano solo quando corrispondono sia il percorso richiesto sia il file in cui si risolve. Una lettura attraverso un collegamento simbolico all'interno di una directory consentita che punta al di fuori di essa non corrisponde alla regola.
  • Regole deny: si applicano quando corrisponde il percorso richiesto oppure il file in cui si risolve. Un collegamento simbolico che punta a un file negato è a sua volta negato. Ad esempio, con Read(./project/**) consentito e Read(~/.ssh/**) negato, un collegamento simbolico in ./project/key che punta a ~/.ssh/id_rsa viene bloccato: la destinazione non soddisfa la regola allow e corrisponde alla regola deny.

Su macOS e Linux, una regola deny o ask scritta attraverso una directory con collegamento simbolico con un pattern //, ~/ o / si applica anche alla posizione reale della directory. Ad esempio, su macOS, dove /etc si risolve in /private/etc, Read(//etc/**) blocca anche /private/etc/hosts. Prima della v2.1.268, una regola deny o ask scritta attraverso una directory con collegamento simbolico non si applicava a un percorso indicato tramite la sua posizione reale.

Grep e Glob eseguono la ricerca nella directory in cui si risolve l'argomento path. Claude Code applica le regole deny Read a quella directory.

Se il percorso che Claude chiede di modificare o scrivere è esso stesso un collegamento simbolico, gli strumenti Edit e Write rifiutano la scrittura e indirizzano Claude alla destinazione del collegamento.

Una scrittura può comunque passare attraverso un collegamento simbolico quando una directory lungo il percorso verso il file è un collegamento simbolico, oppure quando la scrittura viene eseguita da un comando Bash o PowerShell. Per queste scritture, ciò che accade dipende da dove si trova il file in cui si risolve la scrittura rispetto alle tue directory di lavoro e ai percorsi protetti:

  • Si risolve al di fuori delle directory di lavoro: quando il percorso richiesto è all'interno delle tue directory di lavoro e il file in cui si risolve non lo è, la scrittura non viene approvata automaticamente in modalità acceptEdits. In modalità auto, a meno che una regola allow non approvi la scrittura, ti viene chiesta conferma invece di lasciare la decisione al classificatore. La richiesta indica il percorso in cui si risolve la scrittura.
  • Si risolve in un percorso protetto che il percorso richiesto non nomina: la tabella dei percorsi protetti indica il risultato per ogni modalità di permesso, tranne che dove la tabella affida la scrittura al classificatore, questa scrittura ti chiede invece conferma.
Percorsi che non possono essere risolti o che cambiano

Quando Claude Code non riesce a determinare dove porta un percorso sul disco, ad esempio perché i collegamenti simbolici lungo di esso formano un ciclo, gli strumenti Read, Edit e Write rifiutano l'operazione.

Quando uno strumento apre poi il file approvato, conferma che il percorso si risolve ancora nella posizione approvata dal controllo dei permessi.

WebFetch

Le regole WebFetch usano un prefisso domain: e corrispondono al nome host dell'URL richiesto. La corrispondenza non distingue tra maiuscole e minuscole, supporta i caratteri jolly * e rimuove un . finale sia dalla regola sia dal nome host, così example.com. e example.com vengono trattati allo stesso modo.

  • WebFetch(domain:example.com) corrisponde alle richieste verso example.com
  • WebFetch(domain:*.example.com) corrisponde a qualsiasi sottodominio a qualsiasi profondità, come api.example.com o a.b.example.com, ma non a example.com stesso
  • WebFetch(domain:*) corrisponde a ogni dominio. Non equivale a una regola WebFetch senza argomenti; consulta Consentire o negare ogni fetch

In qualsiasi posizione diversa da un *. iniziale o da un * isolato, il carattere jolly corrisponde solo al testo compreso tra due punti. WebFetch(domain:example.*) corrisponde a example.org, dove * diventa org, ma non a example.evil.com, dove * dovrebbe diventare evil.com e attraversare un punto. In questo modo un carattere jolly finale non può corrispondere a domini che un attaccante potrebbe registrare.

I caratteri jolly nelle regole WebFetch richiedono Claude Code v2.1.172 o successiva per corrispondere ai fetch.

Consentire o negare ogni fetch

Una regola WebFetch senza argomenti è il nome dello strumento senza la parte domain:, come "deny": ["WebFetch"]. Sia questa sia WebFetch(domain:*) coprono ogni URL, ma Claude Code le applica in modo diverso, e solo la forma domain: aggiunge anche il proprio dominio all'elenco dei domini consentiti o negati della sandbox. Quella sezione elenca le forme di caratteri jolly che la sandbox rispetta e la versione che ha aggiunto il * isolato.

Ogni riga mostra cosa fa una regola nell'elenco allow e nell'elenco deny:

Regola In allow In deny
WebFetch Claude esegue i fetch senza chiederti conferma. Non cambia quali host possono raggiungere i comandi nella sandbox. Claude Code rimuove lo strumento WebFetch, quindi Claude non può eseguire alcun fetch. Non cambia quali host possono raggiungere i comandi nella sandbox.
WebFetch(domain:*) Claude esegue i fetch senza chiederti conferma e i comandi nella sandbox possono raggiungere qualsiasi host. Claude Code mantiene lo strumento e rifiuta ogni fetch, e i comandi nella sandbox non possono raggiungere alcun host.

Le due forme differiscono anche per le letture degli artefatti, le pagine che lo strumento Artifact pubblica su claude.ai. Una regola deny o ask WebFetch senza argomenti non si applica a queste letture. Una regola domain: che copre claude.ai o l'host dei contenuti *.claudeusercontent.com, come WebFetch(domain:claude.ai) o WebFetch(domain:*), nega ogni lettura o chiede conferma prima di eseguirla. Una regola Artifact fa lo stesso.

Quando una regola blocca una lettura, il rifiuto indica la regola. Prima della v2.1.268, una regola deny WebFetch senza argomenti bloccava ogni lettura di artefatti e una regola ask senza argomenti chiedeva conferma prima di ciascuna.

Per lasciare che Claude esegua i fetch liberamente mantenendo invariata l'allowlist della sandbox, usa la forma senza argomenti. Questo settings.json fa proprio questo:

{
  "permissions": {
    "allow": ["WebFetch"]
  }
}

Quando chiedi a Claude di recuperare una pagina, esegue il fetch senza chiedere conferma. Quando gli chiedi di eseguire un curl nella sandbox verso un host al di fuori dell'allowlist della sandbox, Claude Code ti chiede comunque conferma per quell'host, perché la regola senza argomenti non ha aggiunto l'host all'allowlist.

In modalità auto, Claude indica invece l'host nei domini consentiti per comando del comando, affinché il classificatore li esamini.

MCP

Le regole MCP usano il nome del server così come è configurato in Claude Code, seguito facoltativamente dal nome di uno strumento di quel server.

  • mcp__puppeteer corrisponde a qualsiasi strumento fornito dal server puppeteer
  • mcp__puppeteer__* usa la sintassi con caratteri jolly e corrisponde anch'essa a tutti gli strumenti del server puppeteer
  • mcp__puppeteer__puppeteer_navigate corrisponde allo strumento puppeteer_navigate fornito dal server puppeteer

Se la tua organizzazione ha impostato uno strumento di un connettore claude.ai su ask e tale impostazione raggiunge Claude Code nella tua sessione, le regole allow per quello strumento non hanno effetto: Claude Code chiede conferma a ogni chiamata, anche nelle modalità auto e bypassPermissions. In modalità dontAsk, che non chiede mai conferma, Claude Code nega invece la chiamata. Gli strumenti dei connettori che Claude Code recupera autonomamente compaiono come mcp__claude_ai_<server>__<tool>.

In una sessione Cowork nell'app Claude Desktop, Claude esegue i comandi shell tramite lo strumento mcp__workspace__bash di Cowork anziché tramite lo strumento integrato Bash, e allo stesso modo Cowork fornisce mcp__workspace__web_fetch per i fetch web. Claude Code applica a questi strumenti Cowork anche le regole deny che nominano l'intero strumento Bash o WebFetch, quindi una regola deny Bash gestita impedisce a Claude di eseguire comandi shell in Cowork. Quando Claude Code blocca una chiamata di questo tipo, il messaggio indica lo strumento Cowork: Permission to use mcp__workspace__bash has been denied. Le regole allow non vengono trasferite: Claude Code non applica mai una regola allow Bash a mcp__workspace__bash.

Agent (subagent)

Usa le regole Agent(AgentName) per controllare quali subagent Claude può usare:

  • Agent(Explore) corrisponde al subagent Explore
  • Agent(Plan) corrisponde al subagent Plan
  • Agent(my-custom-agent) corrisponde a un subagent personalizzato chiamato my-custom-agent

Aggiungi queste regole all'array deny nelle tue impostazioni oppure usa il flag CLI --disallowedTools per disabilitare agenti specifici. Per disabilitare l'agente Explore:

{
  "permissions": {
    "deny": ["Agent(Explore)"]
  }
}

Cd

Le regole Cd controllano in quali directory il comando /cd può spostare la sessione. Cd non è uno strumento invocabile dal modello: Claude non può chiamarlo e le regole si applicano solo quando esegui tu stesso /cd.

Una regola deny Cd senza argomenti disabilita completamente /cd. Una regola deny Cd(<path-pattern>) blocca le destinazioni corrispondenti. Le regole deny controllano ogni forma in cui è scritta la destinazione, incluso ogni passaggio attraverso collegamenti simbolici con cui si risolve, quindi una regola scritta per un percorso blocca anche le destinazioni che si risolvono in esso.

Aggiungere una qualsiasi regola allow Cd porta /cd in modalità allowlist: la directory di destinazione risolta deve corrispondere a una delle tue regole allow, altrimenti /cd si rifiuta. Senza regole Cd configurate, /cd mantiene il suo comportamento predefinito e ti chiede di considerare attendibile una directory sconosciuta.

I pattern di percorso condividono gli ancoraggi //, ~/ e / delle regole Read e Edit, ma la corrispondenza è ancorata all'intero percorso della directory anziché seguire lo stile gitignore. * corrisponde esattamente a un segmento di percorso e ** corrisponde attraverso più segmenti. Un /** finale corrisponde anche alla radice indicata.

Regola Corrisponde a Non corrisponde a
Cd(~/code/*) ~/code/app ~/code/app/src, ~/code
Cd(~/code/**) ~/code e qualsiasi directory al suo interno directory al di fuori di ~/code
Cd(**/node_modules) qualsiasi directory node_modules a qualsiasi profondità sotto la directory corrente node_modules/pkg

Estendere le autorizzazioni con hook

Gli hook di Claude Code consentono di registrare comandi shell personalizzati che valutano le autorizzazioni in fase di esecuzione. Quando Claude Code effettua una chiamata di strumento, gli hook PreToolUse vengono eseguiti prima del prompt di autorizzazione, per ogni strumento tranne EndConversation. L'output dell'hook può negare la chiamata dello strumento, forzare un prompt o saltare il prompt per consentire alla chiamata di procedere.

Le decisioni dell'hook PreToolUse non bypassano le regole di autorizzazione. Claude Code valuta le regole deny e ask indipendentemente da ciò che un hook PreToolUse restituisce: una regola deny corrispondente blocca la chiamata e una regola ask corrispondente richiede comunque un prompt anche quando l'hook ha restituito "allow" o "ask". Questo preserva la precedenza deny-first descritta in Gestire le autorizzazioni, incluse le regole deny impostate nelle impostazioni gestite.

Questa precedenza copre gli hook nei file di impostazioni e nel file hooks/hooks.json di un plugin. Un mod che installi e che gestisce tool.check risponde dopo che le regole e gli hook PreToolUse hanno deciso, e la sua risposta può sostituire la loro:

  • Regole Ask: il mod può approvare una chiamata per cui una regola ask richiederebbe un prompt
  • Un blocco da un hook PreToolUse: il mod può approvare la chiamata, a meno che l'hook non sia nelle impostazioni gestite
  • Il classificatore della modalità automatica: in modalità automatica, una chiamata che il mod approva viene eseguita senza un controllo del classificatore
  • Regole Deny: su una macchina con impostazioni gestite, o quando siete connessi con un piano Team o Enterprise, le regole deny hanno la precedenza sul mod per impostazione predefinita, e la vostra organizzazione può modificare questo comportamento. Ovunque altro, il mod può approvare una chiamata che una regola deny rifiuta.

Vedi Decidere se fidarsi di un mod, o Gestire i mod per la vostra organizzazione se distribuite impostazioni gestite.

Gli strumenti MCP contrassegnati requiresUserInteraction richiedono comunque un prompt quando un hook restituisce "allow", così come gli strumenti connector che la vostra organizzazione ha impostato su ask nelle sessioni in cui questa impostazione raggiunge Claude Code.

Un hook di blocco ha anche la precedenza sulle regole allow. Un hook che esce con codice 2 interrompe la chiamata dello strumento prima che le regole di autorizzazione vengano valutate, quindi il blocco si applica anche quando una regola allow consentirebbe altrimenti la chiamata. Per eseguire tutti i comandi Bash senza prompt tranne alcuni che desiderate bloccare, aggiungete "Bash" al vostro elenco allow e registrate un hook PreToolUse che rifiuta quei comandi specifici. Vedi Bloccare le modifiche ai file protetti per uno script di hook che potete adattare.

Directory di lavoro

Per impostazione predefinita, Claude ha accesso ai file nella directory in cui è stato avviato. Quella directory è la directory di lavoro primaria della sessione fino a quando non spostate la sessione con /cd. Potete estendere questo accesso:

  • Durante l'avvio: utilizzate l'argomento CLI --add-dir <path>
  • Durante la sessione: utilizzate il comando /add-dir
  • Configurazione persistente: aggiungete a additionalDirectories nei file di impostazioni

I file nelle directory aggiuntive seguono le stesse regole di autorizzazione della directory di lavoro originale: diventano leggibili senza prompt e le autorizzazioni di modifica dei file seguono la modalità di autorizzazione corrente.

Non potete aggiungere la maggior parte dei percorsi di rete, come la condivisione UNC \\server\share, come directory di lavoro, perché cercarli può contattare l'host che nominano. Su Windows, mappate la condivisione a una lettera di unità e passate l'unità con --add-dir all'avvio.

Impostate permissions.blockReadsOutsideWorkingDirectories per fare in modo che gli strumenti di file rifiutino i percorsi che racchiude in ogni modalità di autorizzazione. In modalità auto, Claude Code offre di attivarlo la prima volta che Claude legge al di fuori delle directory di lavoro.

Nelle sessioni in background su macOS, l'host della sessione richiede l'accesso a cartelle protette come ~/Desktop, ~/Documents e ~/Downloads separatamente dal vostro terminale quando Claude ha bisogno di leggere o scrivere file lì; se le letture lì falliscono con Operation not permitted, consultate come concedere l'accesso alle cartelle alle sessioni in background.

Spostare la sessione in un'altra directory

Per spostare la sessione in una directory di lavoro primaria diversa, piuttosto che aggiungere una directory insieme a quella attuale, eseguite /cd <path>. Claude Code mantiene la conversazione, carica il CLAUDE.md della nuova directory e vi chiede di fidarvi dell'area di lavoro se non avete mai lavorato lì prima. Successivamente, Claude Code trova la sessione spostata quando eseguite --resume dalla nuova directory.

Non appena vi spostate, Claude Code applica la configurazione del progetto della nuova directory:

  • Le sue impostazioni di progetto, incluse le loro regole di autorizzazione e hooks
  • I suoi server .mcp.json, soggetti alla stessa approvazione del server come all'avvio, e i server MCP local-scope che avete registrato in esso
  • I plugin che le sue impostazioni abilitano, le sue skills e i suoi subagents
  • I suoi valori env, applicati sopra le variabili di ambiente dalle impostazioni della directory precedente, che rimangono in vigore

Claude Code disconnette anche i server MCP local-scope e del progetto della directory precedente, e i server dei plugin che non sono più abilitati dopo lo spostamento. Prende le directory aggiuntive dalle impostazioni della nuova directory invece da quella precedente, e mantiene le directory che avete aggiunto con --add-dir o /add-dir. Gli hooks che lo spostamento attiva ricevono ancora ${CLAUDE_PROJECT_DIR} impostato alla radice del progetto dove la sessione è iniziata.

Quando la nuova directory non è ancora attendibile, Claude Code elenca nel prompt di fiducia le regole di autorizzazione, le directory aggiuntive, gli hooks e i comandi helper che le impostazioni della directory attiverebbero, così potete esaminarli prima di accettare. Se rifiutate, la sessione rimane dove si trova. Prima della v2.1.246, /cd non applicava le impostazioni, gli hooks, i server MCP o le skills della nuova directory fino a quando non riprendevano la sessione, e il suo prompt di fiducia non elencava cosa le impostazioni della directory attiverebbero.

Limitate o disabilitate i target di /cd con le regole di autorizzazione Cd.

Le directory aggiuntive concedono l'accesso ai file, non la configurazione

L'aggiunta di una directory estende dove Claude può leggere e modificare i file. Non rende quella directory una radice di configurazione completa: la maggior parte della configurazione .claude/ non viene scoperta dalle directory aggiuntive, anche se alcuni tipi vengono caricati come eccezioni.

Queste eccezioni si applicano solo alle directory aggiunte con il flag --add-dir o il comando /add-dir, incluse le directory che l'Agent SDK aggiunge attraverso il flag. Le directory elencate in permissions.additionalDirectories in un file di impostazioni concedono solo l'accesso ai file e non caricano nessuna delle configurazioni di seguito.

L'opzione additionalDirectories dell'Agent SDK in TypeScript e l'opzione add_dirs in Python ricevono anche le eccezioni, anche se l'opzione TypeScript condivide il suo nome con la chiave delle impostazioni. L'SDK passa ogni voce a Claude Code come --add-dir, quindi quelle directory si comportano come directory aggiunte tramite flag. Skills, comandi e subagents da qualsiasi directory aggiunta tramite flag vengono caricati attraverso la fonte di impostazione project, quindi non vengono caricati quando escludete quella fonte con --setting-sources sulla CLI o settingSources nell'SDK, e la modalità bare salta i comandi e i subagents tra di essi.

I seguenti tipi di configurazione vengono caricati dalle directory --add-dir:

Configurazione Caricato da --add-dir
Skills in .claude/skills/ Sì, con ricaricamento live
File di comando in .claude/commands/ Sì, senza ricaricamento live. Quando la directory aggiunta e il vostro progetto definiscono entrambi un comando con lo stesso nome, Claude Code esegue il comando del vostro progetto
Subagents in .claude/agents/ Sì, senza ricaricamento live
Impostazioni in .claude/settings.json e .claude/settings.local.json Solo le chiavi enabledPlugins e extraKnownMarketplaces
File CLAUDE.md, .claude/rules/ e CLAUDE.local.md Solo quando CLAUDE_CODE_ADDITIONAL_DIRECTORIES_CLAUDE_MD=1 è impostato. CLAUDE.local.md richiede inoltre la fonte di impostazione local, che è abilitata per impostazione predefinita

Per caricare le skills, i comandi e i subagents da una sottodirectory della vostra directory di lavoro primaria a metà sessione, eseguite /add-dir con il percorso di quella sottodirectory. Claude Code li carica per il resto della sessione senza chiedervi o aggiungere una directory di lavoro, perché la sottodirectory è già leggibile. Questo richiede Claude Code v2.1.257 o successivo.

Claude Code scopre gli stili di output dalla directory di lavoro corrente e dai suoi genitori, dalla vostra directory utente in ~/.claude/ e dalle impostazioni gestite. Gli hooks e altre chiavi .claude/settings.json vengono caricati dalla cartella .claude/ della directory di lavoro corrente senza fallback alla directory genitore, insieme al vostro ~/.claude/settings.json utente e alle impostazioni gestite. .claude/settings.local.json viene caricato dalla radice del repository git, anche quando avviate Claude Code in una sottodirectory, tranne nei casi in cui Claude Code non utilizza la radice del repository, come su Windows; prima della v2.1.211, anche esso veniva caricato solo dalla directory di lavoro corrente. Le sessioni Agent SDK lo caricano dalla directory di lavoro in tutte le versioni.

Per condividere quella configurazione tra progetti, utilizzate uno di questi approcci:

  • Configurazione a livello utente: posizionate i file in ~/.claude/agents/, ~/.claude/output-styles/ o ~/.claude/settings.json per renderli disponibili in ogni progetto
  • Plugin: pacchetto e distribuite la configurazione come plugin che i team possono installare
  • Avviate dalla directory di configurazione: eseguite Claude Code dalla directory contenente la configurazione .claude/ che desiderate

Come le autorizzazioni interagiscono con il sandboxing

Le autorizzazioni e il sandboxing sono livelli di sicurezza complementari:

  • Autorizzazioni controllano quali strumenti Claude Code può utilizzare e quali file o domini può accedere. Si applicano a Bash, Read, Edit, WebFetch, MCP e ogni altro strumento, tranne per il fatto che una regola deny o ask non può bloccare EndConversation mentre rimane qualsiasi altro strumento.
  • Sandboxing fornisce l'applicazione a livello del sistema operativo che limita l'accesso al filesystem e alla rete dei comandi Bash, PowerShell e Monitor e dei loro processi figlio.

Utilizzate entrambi per la difesa in profondità, poiché le restrizioni sandbox si applicano comunque anche se un'iniezione di prompt bypassa il processo decisionale di Claude. I percorsi e i domini dalle impostazioni sandbox e dalle regole di autorizzazione sono uniti nella configurazione sandbox finale.

Quando il sandboxing è abilitato e lasciate autoAllowBashIfSandboxed al suo valore predefinito di true, i comandi Bash in sandbox vengono eseguiti senza richiedere un prompt anche se le vostre autorizzazioni includono una regola ask bare Bash, o la forma equivalente Bash(*) : il confine della sandbox sostituisce il prompt per l'intero strumento.

In plan mode, Claude Code salta questa sostituzione. Senza una regola ask, i comandi di sola lettura incorporati vengono comunque eseguiti senza richiedere un prompt, e qualsiasi altro comando shell passa attraverso il flusso di autorizzazione regolare mentre siete ancora in fase di pianificazione; consultate plan mode per come Claude Code gestisce i comandi lì. Con una regola ask bare Bash, ogni comando Bash richiede un prompt, inclusi i comandi di sola lettura in sandbox, lo stesso che al di fuori del sandboxing. Prima della v2.1.212, la sostituzione si applicava anche in plan mode.

Questi controlli si applicano ancora:

  • Le regole ask con ambito di contenuto come Bash(git push *) forzano comunque un prompt
  • Le regole deny esplicite si applicano ancora
  • I comandi rm o rmdir che hanno come destinazione un percorso critico passano comunque attraverso il flusso di autorizzazione regolare

I comandi che non verranno eseguiti in sandbox, come i comandi esclusi, rispettano la regola ask bare Bash come al solito. Consultate modalità sandbox per modificare questo comportamento.

Impostazioni gestite

Per le organizzazioni che necessitano di un controllo centralizzato, gli amministratori distribuiscono impostazioni gestite che le impostazioni utente e di progetto non possono ignorare, ad eccezione di alcune chiavi sensibili alla sicurezza. Distribuire impostazioni gestite copre i meccanismi di consegna, la precedenza all'interno del livello gestito, e le chiavi che solo le impostazioni gestite possono impostare.

Una di queste chiavi, allowManagedPermissionRulesOnly, rende le impostazioni gestite l'unica fonte di impostazioni per le regole di autorizzazione. La sua voce elenca ogni fonte che Claude Code quindi ignora.

disableBypassPermissionsMode è tipicamente posizionato nelle impostazioni gestite per applicare la politica organizzativa, ma funziona da qualsiasi ambito. Un utente può impostarlo nelle proprie impostazioni per bloccarsi dalla modalità bypass.

Precedenza delle impostazioni

Le regole di autorizzazione seguono la stessa precedenza delle impostazioni di tutte le altre impostazioni di Claude Code, con le impostazioni gestite al livello più alto: nessun altro livello, inclusi gli argomenti della riga di comando, può ignorare una regola di autorizzazione gestita.

Se uno strumento viene negato a qualsiasi livello, nessun altro livello può consentirlo. Ad esempio, un deny delle impostazioni gestite non può essere ignorato da --allowedTools e --disallowedTools può aggiungere restrizioni oltre a quelle definite dalle impostazioni gestite.

Lo stesso vale tra gli ambiti delle impostazioni: se le impostazioni utente consentono un'autorizzazione e le impostazioni di progetto la negano, la regola di negazione la blocca. Il contrario è vero anche: un deny a livello utente blocca un allow a livello di progetto, perché le regole di negazione da qualsiasi ambito vengono valutate prima delle regole di consentimento.

Questa precedenza è tra i file di impostazioni e gli argomenti della riga di comando. Per quanto riguarda se una regola di negazione vale su un mod che installi, vedi Estendi le autorizzazioni con hooks.

Gli host di embedding possono fornire ulteriori criteri gestiti tramite l'opzione SDK managedSettings, incluse le regole di consentimento delle autorizzazioni a meno che l'amministratore non imposti i blocchi allowManaged*Only; Deliver policy to Claude Desktop sessions illustra quando la politica dell'embedder si applica.

Regole di autorizzazione del progetto e trust dell'area di lavoro

Le regole permissions.allow e le voci permissions.additionalDirectories nel file .claude/settings.json di un progetto concedono capacità, quindi Claude Code le applica solo dopo che accettate la finestra di dialogo di trust dell'area di lavoro per quella cartella. La finestra di dialogo elenca le regole e le directory che la cartella concederà, in modo che possiate esaminarle prima. Le regole deny e ask non sono interessate, poiché limitano solo.

Claude Code salva il trust che accettate in base a dove lo avviate:

  • In un repository, Claude Code salva il trust sulla radice del repository git, quindi il trust copre l'intero repository a parte qualsiasi repository git annidato al suo interno, come un submodule. In un worktree, utilizza la radice del checkout principale, come fa per le regole salvate.
  • Al di fuori di un repository, Claude Code salva il trust sulla directory da cui lo avete avviato, e il trust copre qualsiasi subdirectory di quella directory a parte un repository git annidato al suo interno, come un clone. Ogni subdirectory coperta conta quindi come una cartella il cui genitore avete fidata.
  • Quando avviate dalla vostra directory home, Claude Code mantiene il trust solo per la sessione corrente e non lo scrive su disco; consultate la nota safeguard aggiuntivi.

Claude Code mostra la finestra di dialogo di trust solo in sessioni interattive. Un'esecuzione claude -p o una sessione SDK non la mostra mai, e fidarsi di una cartella genitore non conta per queste regole, quindi Cosa viene eseguito prima di fidarsi di una cartella dice quale contenuto del repository Claude Code utilizza ancora in ognuna di quelle due situazioni.

Prima di avviare o riavviare una sessione in background, Claude Code controlla anche il trust dell'area di lavoro per la directory in cui viene eseguita la sessione. Se eseguite claude --bg da un terminale in una directory che non avete fidata, la finestra di dialogo di trust appare prima e la sessione si avvia una volta che l'accettate. Dove nessuna finestra di dialogo può apparire, come in uno script, il comando esce invece con un errore Workspace not trusted.

Quando il vostro file di impostazioni locali ha bisogno di trust

.claude/settings.local.json è normalmente il vostro file personale, quindi Claude Code applica le sue regole di autorizzazione e directory aggiuntive senza il passaggio di trust. Quando il file è tracciato in git, o .claude è un symlink, Claude Code lo tratta invece come fornito dal repository e tiene in sospeso le sue regole finché non vi fidate della cartella.

Claude Code esegue git per distinguere i due casi, ed esegue git solo dopo che avete fidata la cartella: avete accettato la finestra di dialogo di trust per essa o per una directory genitore il cui trust si estende ad essa, o siete in una sessione -p o SDK, che conta come accettata. Fino ad allora, il luogo da cui avete avviato Claude Code decide cosa succede alle regole del file:

  • Nella vostra directory di configurazione personale: Claude Code applica il .claude/settings.local.json di quella cartella subito senza eseguire git. La vostra directory di configurazione personale è la vostra directory home, o una directory il cui subdirectory .claude avete impostato come CLAUDE_CONFIG_DIR. Se quella directory CLAUDE_CONFIG_DIR si trova all'interno di un repository git e Claude Code mantiene le vostre impostazioni locali alla radice del repository invece, tiene in sospeso le regole come in qualsiasi altra posizione.
  • In qualsiasi altra posizione: Claude Code tiene in sospeso le regole del file come fa per le impostazioni del progetto. Una volta che il controllo è stato eseguito, Claude Code applica le regole di un file non tracciato, o di un file in una directory al di fuori di qualsiasi repository git, anche se non avete fidata quella cartella esatta.

Nelle versioni 2.1.196 fino a 2.1.199, Claude Code teneva in sospeso le regole del file anche nella vostra directory di configurazione personale e al di fuori dei repository git, e stampava l'avviso this workspace has not been trusted lì. Prima della v2.1.207, Claude Code applicava le regole di un file non tracciato prima che accettaste la finestra di dialogo.

Cosa viene eseguito prima di fidarsi di una cartella

Ogni riga è un tipo di contenuto che un repository può fornire. Le colonne sono le due situazioni in cui non avete fidata la cartella stessa: avete fidata solo una cartella genitore, o avete eseguito claude -p o l'SDK lì, che non mostra mai la finestra di dialogo di trust. La colonna della cartella genitore non si applica all'interno di un repository annidato: in una sessione interattiva Claude Code mostra la finestra di dialogo di trust per essa, e un'esecuzione claude -p o SDK lì segue la colonna claude -p.

Cosa fornisce il repository Avete fidata solo una cartella genitore claude -p o l'SDK, cartella mai fidata
Hooks nei file di impostazioni, il blocco env e comandi helper come apiKeyHelper, e gli hooks di una skill del progetto e allowed-tools Utilizzati Utilizzati. Il trust dell'area di lavoro non blocca mai allowed-tools di una skill in nessuna sessione
Regole permissions.allow e additionalDirectories in .claude/settings.json Non utilizzate fino a quando non accettate la finestra di dialogo di trust, che appare di nuovo elencandole Non utilizzate. Claude Code stampa un avviso this workspace has not been trusted su stderr
Hook nel frontmatter di un subagent del progetto, un plugin @skills-dir del progetto, e voci extraKnownMarketplaces dal repository o da una directory --add-dir Non utilizzate, e nessuna finestra di dialogo è offerta Non utilizzate
Inline mcpServers nel frontmatter di un subagent dal repository o da una directory --add-dir Non utilizzate, e nessuna finestra di dialogo è offerta Non utilizzate
Server in .mcp.json, inclusi quelli che il repository approva nelle sue stesse impostazioni Claude Code vi chiede prima di connettersi ad essi. Le approvazioni del repository stesso non contano Connessi senza chiedere, approvati o no. L'SDK li carica solo quando settingSources include impostazioni del progetto. claude mcp list nella stessa cartella riporta comunque tale server come in sospeso
Un headersHelper su un server in .mcp.json Non eseguito fino a quando non accettate la finestra di dialogo di trust, che appare di nuovo nominando dove l'helper è dichiarato. Claude Code connette il server con i suoi soli headers statici fino ad allora Non eseguito. Claude Code connette il server con i suoi soli headers statici e stampa una riga headersHelper not run per server su stderr

Per le righe che hanno bisogno di questa cartella esatta fidata, fidate la cartella manualmente: impostate projects["<path>"].hasTrustDialogAccepted a true in ~/.claude.json, dove <path> è la radice del repository, o la cartella stessa al di fuori di un repository. Claude Code stampa la chiave esatta nella riga del log di debug per un hook subagent saltato o un server MCP inline, nell'avviso su stderr per regole di autorizzazione saltate, e nella riga headersHelper not run per un helper saltato.

Prima di eseguire claude -p in un repository che non avete scritto, decidete cosa potrebbe eseguire sulla vostra macchina:

  • Passate --setting-sources user, o impostate settingSources dell'SDK senza impostazioni del progetto, in modo che Claude Code non legga né i file di impostazioni del progetto né il suo .mcp.json
  • Iniziate con --bare in modo che Claude Code non legga hook, skill, comandi personalizzati, subagent, plugin, o server .mcp.json dal progetto. Il blocco env del progetto e helper come awsAuthRefresh nei suoi file di impostazioni si applicano comunque, e Claude Code legge apiKeyHelper solo da --settings
  • Passate --settings '{"disableAllHooks": true}' per disattivare gli hook per quella esecuzione. Impostarlo solo nelle vostre impostazioni utente non è sufficiente, perché le impostazioni del progetto del repository hanno precedenza sulle vostre e possono impostarlo di nuovo a false
  • Aggiungete una voce disabledMcpjsonServers per rifiutare un server .mcp.json per nome in ogni tipo di sessione

Configurazioni di esempio

Questo repository include configurazioni di impostazioni iniziali per scenari di distribuzione comuni. Utilizzatele come punti di partenza e adattatele alle vostre esigenze.

Vedi anche

  • Tutte le impostazioni: ogni chiave di impostazione, incluse le chiavi di autorizzazione
  • Configurare la modalità auto: comunicate al classificatore della modalità auto quale infrastruttura la vostra organizzazione ritiene affidabile
  • Sandboxing: isolamento del filesystem e della rete a livello del sistema operativo per i comandi Bash
  • Autenticazione: configurate l'accesso utente a Claude Code
  • Sicurezza: salvaguardie di sicurezza e best practice
  • Hooks: automatizzate i flussi di lavoro ed estendete la valutazione delle autorizzazioni