Automatizzare le azioni con hooks

​

Configurare il vostro primo hook

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write" }]
      }
    ],
    "Notification": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'" }]
      }
    ]
  }
}

​

Cosa potete automatizzare

​

Ricevere una notifica quando Claude ha bisogno di input

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

osascript -e 'display notification "test"'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "notify-send 'Claude Code' 'Claude Code needs your attention'"
          }
        ]
      }
    ]
  }
}

notify-send 'Claude Code' 'test'

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "powershell.exe -Command \"[System.Reflection.Assembly]::LoadWithPartialName('System.Windows.Forms'); [System.Windows.Forms.MessageBox]::Show('Claude Code needs your attention', 'Claude Code')\""
          }
        ]
      }
    ]
  }
}

​

Formattare automaticamente il codice dopo le modifiche

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

​

Bloccare le modifiche ai file protetti

#!/bin/bash
# protect-files.sh

INPUT=$(cat)
FILE_PATH=$(echo "$INPUT" | jq -r '.tool_input.file_path // empty')

# Normalize Windows backslash separators so the patterns below match
FILE_PATH="${FILE_PATH//\\//}"

PROTECTED_PATTERNS=(".env" "package-lock.json" ".git/")

for pattern in "${PROTECTED_PATTERNS[@]}"; do
  if [[ "$FILE_PATH" == *"$pattern"* ]]; then
    echo "Blocked: $FILE_PATH matches protected pattern '$pattern'" >&2
    exit 2
  fi
done

exit 0

chmod +x .claude/hooks/protect-files.sh

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-files.sh"
          }
        ]
      }
    ]
  }
}

​

Reiniettare il contesto dopo la compattazione

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "echo 'Reminder: use Bun, not npm. Run bun test before committing. Current sprint: auth refactor.'"
          }
        ]
      }
    ]
  }
}

​

Controllare le modifiche di configurazione

{
  "hooks": {
    "ConfigChange": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "jq -c '{timestamp: now | todate, source: .source, file: .file_path}' >> ~/claude-config-audit.log"
          }
        ]
      }
    ]
  }
}

​

Ricaricare l’ambiente quando la directory o i file cambiano

{
  "hooks": {
    "SessionStart": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ],
    "CwdChanged": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "FileChanged": [
      {
        "matcher": ".envrc|.env",
        "hooks": [
          {
            "type": "command",
            "command": "direnv export bash > \"$CLAUDE_ENV_FILE\""
          }
        ]
      }
    ]
  }
}

​

Approvare automaticamente specifici prompt di autorizzazione

{
  "hooks": {
    "PermissionRequest": [
      {
        "matcher": "ExitPlanMode",
        "hooks": [
          {
            "type": "command",
            "command": "echo '{\"hookSpecificOutput\": {\"hookEventName\": \"PermissionRequest\", \"decision\": {\"behavior\": \"allow\"}}}'"
          }
        ]
      }
    ]
  }
}

{
  "hookSpecificOutput": {
    "hookEventName": "PermissionRequest",
    "decision": {
      "behavior": "allow",
      "updatedPermissions": [
        { "type": "setMode", "mode": "acceptEdits", "destination": "session" }
      ]
    }
  }
}

​

Come funzionano gli hooks

• "type": "http": POST dei dati dell’evento a un URL. Consultate HTTP hooks.
• "type": "mcp_tool": chiama uno strumento su un server MCP già configurato. Consultate MCP tool hooks.
• "type": "prompt": valutazione LLM a turno singolo. Consultate Prompt-based hooks.
• "type": "agent": verifica multi-turno con accesso agli strumenti. Gli agent hooks sono sperimentali e potrebbero cambiare. Consultate Agent-based hooks.

​

Combinare i risultati da più hooks

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.command >> ~/.claude/bash.log"
          },
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/block-rm-rf.sh"
          }
        ]
      }
    ]
  }
}

​

Leggere l’input e restituire l’output

​

Input dell’hook

• hook_event_name: l’evento che ha attivato l’hook
• tool_name: lo strumento che Claude sta per utilizzare
• tool_input: gli argomenti che Claude ha passato allo strumento. Per Bash, il suo campo command contiene il comando shell.

{
  "session_id": "abc123",
  "cwd": "/Users/sarah/myproject",
  "hook_event_name": "PreToolUse",
  "tool_name": "Bash",
  "tool_input": {
    "command": "npm test"
  }
}

​

Output dell’hook

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

if echo "$COMMAND" | grep -q "drop table"; then
  echo "Blocked: dropping tables is not allowed" >&2  # stderr becomes Claude's feedback
  exit 2 # exit 2 = block the action
fi

exit 0  # exit 0 = no decision; the normal permission flow applies

• Exit 0: il vostro hook non riporta obiezioni attraverso il suo codice di uscita.
  • Per un hook PreToolUse questo non approva la chiamata dello strumento: il normale flusso di autorizzazione si applica ancora.
  • Per gli hook UserPromptSubmit, UserPromptExpansion, SessionStart e PostModelSwitch, Claude Code aggiunge stdout che tratta come testo semplice al contesto di Claude.
• Exit 2: Claude Code blocca l’azione. Scrivete un motivo su stderr. Dove finisce dipende dall’evento: alcuni eventi lo alimentano a Claude come feedback in modo che possa adattarsi, altri lo mostrano all’utente, e alcuni, come ConfigChange e Elicitation, non mostrano alcun messaggio. Alcuni eventi non possono essere bloccati: per SessionStart e altri, exit 2 mostra stderr all’utente e l’esecuzione continua. Consultate exit code 2 behavior per evento per l’elenco completo.
• Qualsiasi altro codice di uscita: per la maggior parte degli eventi, il risultato dipende da quello che il vostro hook ha stampato su stdout:
  • Un oggetto analizzato che passa la validazione dello schema: Claude Code ignora il codice di uscita, il JSON da solo decide il risultato, e l’hook non viene segnalato come errore. Le eccezioni per evento, come WorktreeCreate che fallisce su qualsiasi uscita diversa da zero, sono elencate nella sezione Exit code output del riferimento.
  • Un oggetto analizzato che fallisce la validazione dello schema, o stdout che Claude Code tenta di analizzare come JSON ma che non è JSON valido: un errore non bloccante; l’avviso contiene il messaggio di validazione o analisi.
  • Stdout che Claude Code tratta come testo semplice, o stdout vuoto: l’azione procede come errore non bloccante. La trascrizione mostra un avviso <hook name> hook error, quindi la prima riga di stderr con prefisso Failed with non-blocking status code:. Per catturare lo stderr completo, abilitate il debug logging con claude --debug o eseguendo /debug durante la sessione.

​

Output JSON strutturato

{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Use rg instead of grep for better performance"
  }
}

• "allow": salta il prompt di autorizzazione interattivo. Le regole di negazione e richiesta, incluse le liste di negazione gestite dall’azienda, si applicano ancora, così come i prompt per gli strumenti MCP contrassegnati requiresUserInteraction e per gli strumenti connettore che la vostra organizzazione ha impostato su ask nelle sessioni dove quella impostazione raggiunge Claude Code
• "deny": annulla la chiamata dello strumento e invia il motivo a Claude
• "ask": mostra il prompt di autorizzazione all’utente come al solito

{
  "hookSpecificOutput": {
    "hookEventName": "UserPromptSubmit",
    "additionalContext": "Current branch: release-42. Deploy freeze until Friday."
  }
}

​

Filtrare gli hooks con i matcher

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          { "type": "command", "command": "prettier --write ..." }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.command' >> ~/.claude/command-log.txt"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "mcp__github__.*",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"GitHub tool called: $(jq -r '.tool_name')\" >&2"
          }
        ]
      }
    ]
  }
}

{
  "hooks": {
    "SessionEnd": [
      {
        "matcher": "clear",
        "hooks": [
          {
            "type": "command",
            "command": "rm -f /tmp/claude-scratch-*.txt"
          }
        ]
      }
    ]
  }
}

​

Filtrare per nome dello strumento e argomenti con il campo if

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "if": "Bash(git *)",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/check-git-policy.sh"
          }
        ]
      }
    ]
  }
}

​

Configurare la posizione dell’hook

​

Hooks basati su prompt

• "ok": true: l’azione procede
• "ok": false: ciò che accade dipende dall’evento:
  • Stop e SubagentStop: il reason viene alimentato di nuovo a Claude in modo che continui a lavorare, a meno che la risposta non imposti anche "impossible": true per contrassegnare la condizione come una che non può mai essere soddisfatta, nel qual caso Claude Code consente lo stop e il turno termina
  • PreToolUse: la chiamata dello strumento viene negata; per impostazione predefinita il turno termina e il reason di negazione appare nella chat come una riga di avviso. Impostate continueOnBlock: true sull’hook per restituire invece il reason a Claude come errore dello strumento, in modo che possa adattarsi e continuare. Prima della v2.1.210, il reason di negazione veniva restituito a Claude come errore dello strumento e il turno continuava
  • PostToolUse: per impostazione predefinita il turno termina e il reason appare nella chat come una riga di avviso. Impostate continueOnBlock: true per alimentare il reason di nuovo a Claude e continuare il turno invece
  • PostToolBatch, UserPromptSubmit e UserPromptExpansion: il turno termina e il reason appare nella chat come una riga di avviso

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

​

Hooks basati su agenti

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

​

HTTP hooks

{
  "hooks": {
    "PostToolUse": [
      {
        "hooks": [
          {
            "type": "http",
            "url": "http://localhost:8080/hooks/tool-use",
            "headers": {
              "Authorization": "Bearer $MY_TOKEN"
            },
            "allowedEnvVars": ["MY_TOKEN"]
          }
        ]
      }
    ]
  }
}

​

Limitazioni e risoluzione dei problemi

​

Limitazioni

• Gli hook di tipo command comunicano solo tramite stdout, stderr e codici di uscita. Non possono attivare comandi / o chiamate agli strumenti. Il testo restituito tramite additionalContext viene inserito come promemoria di sistema che Claude legge come testo semplice. Gli hook HTTP comunicano invece tramite il corpo della risposta.
• I timeout degli hook variano in base al tipo. Puoi sovrascriverli per ciascun hook con il campo timeout in secondi.
  • command, http, mcp_tool: 10 minuti. Claude Code abbassa questo valore predefinito a 30 secondi per gli hook UserPromptSubmit, PreModelSwitch e PostModelSwitch, e a 10 secondi per MessageDisplay.
  • prompt: 30 secondi.
  • agent: 60 secondi.
  • Gli hook SessionEnd di qualsiasi tipo condividono un budget di 1,5 secondi. Se le tue impostazioni definiscono un timeout per hook più lungo, Claude Code aumenta il budget di conseguenza, fino a 60 secondi.
• Gli hook PostToolUse non possono annullare le azioni, poiché lo strumento è già stato eseguito.
• Gli hook PermissionRequest si attivano quando Claude Code sta per chiederti un permesso, oppure quando altrimenti negherebbe automaticamente una chiamata che non può mostrare una richiesta di permesso. In modalità non interattiva con il flag -p, vengono comunque eseguiti al di fuori della modalità dontAsk, e una chiamata su cui nessun hook decide e a cui nient’altro può rispondere viene negata.
• Gli hook Stop si attivano ogni volta che Claude termina di rispondere, non solo al completamento di un’attività. Non si attivano in caso di interruzioni da parte dell’utente. Gli errori API attivano invece StopFailure.
• Quando più hook PreToolUse restituiscono updatedInput per riscrivere gli argomenti di uno strumento, ha effetto l’ultimo che termina. Poiché gli hook vengono eseguiti in parallelo, l’ordine non è deterministico. Evita di avere più di un hook che modifica l’input dello stesso strumento.

​

Hook e modalità di permesso

​

L’hook non si attiva

• Esegui /hooks e verifica che l’hook compaia sotto l’evento corretto
• Controlla che il pattern del matcher corrisponda esattamente al nome dello strumento. I matcher distinguono tra maiuscole e minuscole
• Verifica di attivare il tipo di evento corretto: PreToolUse si attiva prima dell’esecuzione dello strumento, PostToolUse dopo. Un hook PermissionRequest si attiva quando Claude Code sta per chiederti un permesso; consulta le limitazioni per i casi non interattivi

​

Errore dell’hook nell’output

• Il tuo script è terminato inaspettatamente con un codice diverso da zero. Testalo manualmente passandogli un JSON di esempio tramite pipe:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• Se vedi “command not found”, usa percorsi assoluti o ${CLAUDE_PROJECT_DIR} per fare riferimento agli script. Per evitare del tutto il quoting della shell, aggiungi "args": [] per passare alla forma exec, che avvia lo script direttamente senza una shell
• Se vedi “jq: command not found”, installa jq oppure usa Python/Node.js per il parsing del JSON
• Se l’avviso mostra un messaggio di convalida JSON, lo stdout del tuo hook è stato interpretato come JSON ma non ha superato la convalida dello schema. Se mostra un messaggio di parsing JSON, lo stdout sembrava un oggetto JSON ma non era JSON valido. Entrambi i casi si verificano anche con uscita 0. Per correggere un errore di parsing, crea il payload con un encoder JSON come jq invece di concatenare stringhe, in modo che virgolette e barre rovesciate all’interno dei valori vengano sottoposte a escape. La sezione Output del codice di uscita del riferimento descrive le combinazioni di codice di uscita e JSON
• Se lo script non viene eseguito affatto, rendilo eseguibile: chmod +x ./my-hook.sh

​

/hooks non mostra hook configurati

• Le modifiche ai file vengono normalmente rilevate in automatico. Se non sono comparse dopo qualche secondo, il file watcher potrebbe non aver rilevato la modifica: riavvia la sessione per forzare il ricaricamento.
• Verifica che il tuo JSON sia valido: virgole finali e commenti non sono consentiti
• Conferma che il file di impostazioni si trovi nella posizione corretta: .claude/settings.json per gli hook di progetto, ~/.claude/settings.json per gli hook globali
• Se il menu mostra Only hooks from managed settings run here, la tua organizzazione ha impostato allowManagedHooksOnly. Gli hook nei tuoi file di impostazioni utente, di progetto e locali non vengono eseguiti e non sono elencati

​

L’hook Stop raggiunge il limite di blocchi

#!/bin/bash
INPUT=$(cat)
if [ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ]; then
  exit 0  # Allow Claude to stop
fi
# ... rest of your hook logic

​

Il JSON dell’hook non ha effetto

• Output aggiuntivo prima del JSON: qualcos’altro scrive prima su stdout, di solito un echo incondizionato nel profilo della tua shell, quindi l’output non inizia più con { e Claude Code non lo interpreta come JSON. La causa e la soluzione sono descritte dopo questo elenco.
• Un campo al livello sbagliato: confronta la posizione di ciascun campo con il formato dell’output JSON. Ad esempio, permissionDecision va all’interno di hookSpecificOutput, non al livello superiore.

Shell ready on arm64
{"decision": "block", "reason": "Not allowed"}

# In ~/.zshrc or ~/.bashrc
if [[ $- == *i* ]]; then
  echo "Shell ready"
fi

​

Tecniche di debug

• Esecuzione riuscita: non vedi nulla, a meno che il JSON dell’hook non faccia emergere qualcosa, come systemMessage o il feedback di un hook Stop.
  • Per confermare che un hook è stato eseguito, verificane l’effetto, ad esempio un file riformattato, oppure attiva il logging di debug come descritto di seguito e attiva nuovamente l’hook
• Errore bloccante: nella maggior parte degli eventi vedi il feedback dell’hook. Quando il JSON dell’hook ha preso una decisione bloccante, il feedback è il motivo di quella decisione; altrimenti è lo stderr dell’hook. In alcuni eventi, come ConfigChange ed Elicitation, un blocco non mostra alcun messaggio.
• Errore non bloccante: l’azione è proseguita e vedi un avviso <hook name> hook error con una breve spiegazione, come la prima riga dello stderr preceduta da Failed with non-blocking status code:, oppure un messaggio di convalida o di parsing JSON.

​

Ulteriori informazioni

• Riferimento Hooks: schemi di eventi completi, formato di output JSON, hooks asincroni e hooks di strumenti MCP
• Considerazioni sulla sicurezza: esaminate prima di distribuire gli hooks in ambienti condivisi o di produzione
• Esempio di validatore di comandi Bash: implementazione di riferimento completa