Hook e permission

Personalizza il comportamento di Claude e imposta limiti di sicurezza

⏱ Stima ~6 min

01 · Leggi

Gli hook ti permettono di eseguire il tuo codice in momenti specifici del flusso di Claude. Prima che uno strumento venga usato? Dopo una modifica? All'avvio della sessione? Puoi intercettare questi eventi e aggiungere la tua logica — formattazione automatica, controlli di sicurezza, notifiche, validazioni personalizzate.

Le permission controllano cosa Claude è autorizzato a fare. Per impostazione predefinita, Claude chiede conferma prima di eseguire comandi o modificare file. Ma puoi pre-approvare azioni sicure (come npm test), bloccare quelle pericolose (come git push --force) e lasciare che Claude lavori più velocemente sui task di routine mantenendo al sicuro quelli rischiosi.

💡 Immagina cosìGli hook sono come i checkpoint in una linea di produzione. A ogni stazione, l'ispettore (il tuo script) controlla il lavoro, lascia passare (exit 0) o rimanda indietro (exit 2). Le permission sono come un sistema di badge di sicurezza — alcune porte sono sempre aperte (leggere file), alcune richiedono il badge (comandi), alcune sono chiuse a chiave (operazioni pericolose).

Punti chiave

Hook: esegui il tuo codice in momenti specifici del flusso di Claude
Permission: controlla cosa Claude può e non può fare
Gli hook intercettano eventi; le permission impostano regole generali
Insieme personalizzano e proteggono Claude nel tuo flusso di lavoro

02 · Leggi

Ecco gli eventi hook più utili: - PreToolUse — Si attiva prima che Claude usi uno strumento (Read, Edit, Bash ecc.). Puoi controllare cosa sta per fare e bloccarlo. - PostToolUse — Si attiva dopo che uno strumento ha avuto successo. Ideale per formattare automaticamente i file modificati o registrare le modifiche. - SessionStart — Si attiva all'avvio della sessione. Usalo per iniettare promemoria di context, specialmente dopo una compressione. - Notification — Si attiva quando Claude ha bisogno della tua attenzione. Ideale per notifiche desktop. - Stop — Si attiva quando Claude ha finito di rispondere.

Gli hook comunicano tramite exit code: exit 0 significa consenti l'azione, exit 2 significa bloccala (il messaggio di errore su stderr diventa il feedback per Claude).

Punti chiave

PreToolUse: controlla lo strumento prima dell'esecuzione, bloccalo se necessario
PostToolUse: reagisce dopo il successo dello strumento (formattazione automatica, log)
SessionStart: inietta promemoria di context all'avvio della sessione o dopo la compressione
Exit 0 = consenti, Exit 2 = blocca (stderr diventa feedback)

03 · Esempio di codice

Ecco un hook PostToolUse che formatta automaticamente i file dopo che Claude li ha modificati. Risiede nel file .claude/settings.json del tuo progetto.

.claude/settings.json — hook di formattazione automatica

{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
      }]
    }]
  }
}

Il campo matcher usa una regex per abbinare il nome dello strumento — Edit|Write significa che questo hook si attiva dopo qualsiasi chiamata agli strumenti Edit o Write. Il comando riceve JSON su stdin con i dettagli della chiamata, estrae il percorso del file ed esegue Prettier su di esso. Ogni file modificato da Claude viene formattato automaticamente.

04 · Esempio di codice

Ecco un hook PreToolUse che blocca i comandi Bash pericolosi.

.claude/hooks/protect.sh

#!/bin/bash
INPUT=$(cat)
CMD=$(echo "$INPUT" | jq -r '.tool_input.command')

if [[ "$CMD" =~ "rm -rf" ]]; then
  echo "Blocked: rm -rf is not allowed" >&2
  exit 2  # Block the action
fi

exit 0  # Allow everything else

.claude/settings.json

{
  "hooks": {
    "PreToolUse": [{
      "matcher": "Bash",
      "hooks": [{
        "type": "command",
        "command": ".claude/hooks/protect.sh"
      }]
    }]
  }
}

Questo hook intercetta ogni comando Bash che Claude prova a eseguire. Legge il comando da stdin (come JSON), controlla se contiene 'rm -rf' e lo blocca con exit code 2. Il messaggio di errore su stderr dice a Claude perché è stato bloccato, e Claude rispetterà il limite.

05 · Leggi

Le permission ti danno regole generali di consenso/rifiuto senza dover scrivere script. Usano wildcard per abbinamenti flessibili.

Regole Allow pre-approvano azioni, così Claude non deve chiedere: - Bash(npm run ) — qualsiasi script npm - Bash(git commit ) — fare commit delle modifiche - Read(*.env) — leggere file env

Regole Deny bloccano le azioni del tutto: - Bash(git push --force ) — niente push forzati - Edit(package-lock.json) — non toccare il lockfile - Bash(rm -rf ) — niente eliminazioni ricorsive

Le regole Deny vincono sempre sulle Allow. La configurazione viene controllata dal più specifico al meno specifico: local project > project > user.

Punti chiave

Regole Allow: pre-approva azioni sicure (niente prompt di permission)
Regole Deny: bloccano le azioni del tutto
Wildcard: Bash(npm *) abbina qualsiasi comando npm
In caso di conflitto, Deny vince sempre su Allow
La configurazione locale ha precedenza su quella di progetto, che ha precedenza su quella utente

06 · Quiz

Il tuo hook PreToolUse rileva che Claude sta per eseguire rm -rf /tmp/build. Quale exit code deve restituire il tuo script per bloccare questa azione?

Exit code 0 — successo
Exit code 2 — blocca l'azione
Exit code 1 — errore generico
Exit code 255 — errore critico

07 · Abbina

Abbina ogni evento hook a ciò per cui è più adatto.

(Questa sezione è interattiva — attiva JavaScript per usarla.)

Altre lezioni di questo capitolo

⚠ L'esperienza interattiva completa richiede JavaScript. Attivalo e ricarica la pagina.

※ Questo è un progetto educativo indipendente — non è un prodotto ufficiale di Anthropic. Claude™ è un marchio di Anthropic, PBC.