Automatizzare i flussi di lavoro 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\"'"
          }
        ]
      }
    ]
  }
}

​

Cosa potete automatizzare

• Ricevere una notifica quando Claude ha bisogno di input
• Formattare automaticamente il codice dopo le modifiche
• Bloccare le modifiche ai file protetti
• Reiniettare il contesto dopo la compattazione
• Controllare le modifiche di configurazione
• Ricaricare l’ambiente quando la directory o i file cambiano
• Approvare automaticamente specifici prompt di autorizzazione

​

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\"'"
          }
        ]
      }
    ]
  }
}

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

{
  "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')

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": {
    "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": "prompt": valutazione LLM a turno singolo. Consultate Hooks basati su prompt.
• "type": "agent": verifica multi-turno con accesso agli strumenti. Consultate Hooks basati su agenti.

​

Leggere l’input e restituire l’output

​

Input dell’hook

{
  "session_id": "abc123",          // unique ID for this session
  "cwd": "/Users/sarah/myproject", // working directory when the event fired
  "hook_event_name": "PreToolUse", // which event triggered this hook
  "tool_name": "Bash",             // the tool Claude is about to use
  "tool_input": {                  // the arguments Claude passed to the tool
    "command": "npm test"          // for Bash, this is the shell command
  }
}

​

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 = let it proceed

• Exit 0: l’azione procede. Per gli hook UserPromptSubmit e SessionStart, qualsiasi cosa scriviate su stdout viene aggiunta al contesto di Claude.
• Exit 2: l’azione è bloccata. Scrivete un motivo su stderr, e Claude lo riceve come feedback in modo da poter adattarsi.
• Qualsiasi altro codice di uscita: l’azione procede. Stderr viene registrato ma non mostrato a Claude. Attivate la modalità verbose con Ctrl+O per vedere questi messaggi nella trascrizione.

​

Output JSON strutturato

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

• "allow": procedi senza mostrare un prompt di autorizzazione interattivo. Le regole di negazione e richiesta, incluse le liste di negazione gestite dall’azienda, si applicano ancora
• "deny": annulla la chiamata dello strumento e invia il motivo a Claude
• "ask": mostra il prompt di autorizzazione all’utente come al solito

​

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"
          }
        ]
      }
    ]
  }
}

​

Configurare la posizione dell’hook

​

Hooks basati su prompt

• "ok": true: l’azione procede
• "ok": false: l’azione è bloccata. Il "reason" del modello viene alimentato di nuovo a Claude in modo da poter adattarsi.

{
  "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 comando comunicano solo attraverso stdout, stderr e codici di uscita. Non possono attivare comandi o chiamate di strumenti direttamente. Gli HTTP hooks comunicano attraverso il corpo della risposta invece.
• Il timeout dell’hook è di 10 minuti per impostazione predefinita, configurabile per hook con il campo timeout (in secondi).
• Gli hook PostToolUse non possono annullare le azioni poiché lo strumento è già stato eseguito.
• Gli hook PermissionRequest non si attivano in modalità non interattiva (-p). Utilizzate gli hook PreToolUse per le decisioni di autorizzazione automatizzate.
• Gli hook Stop si attivano ogni volta che Claude finisce di rispondere, non solo al completamento dell’attività. Non si attivano su interruzioni dell’utente. Gli errori API attivano StopFailure invece.

​

Hook non si attiva

• Eseguite /hooks e confermate che l’hook appare sotto l’evento corretto
• Controllate che il modello del matcher corrisponda esattamente al nome dello strumento (i matcher sono sensibili alle maiuscole)
• Verificate che state attivando il tipo di evento corretto (ad esempio, PreToolUse si attiva prima dell’esecuzione dello strumento, PostToolUse si attiva dopo)
• Se utilizzate gli hook PermissionRequest in modalità non interattiva (-p), passate a PreToolUse invece

​

Errore dell’hook nell’output

• Il vostro script è uscito con un codice diverso da zero inaspettatamente. Testatelo manualmente inviando JSON di esempio:
  echo '{"tool_name":"Bash","tool_input":{"command":"ls"}}' | ./my-hook.sh
  echo $?  # Check the exit code
  
• Se vedete “command not found”, utilizzate percorsi assoluti o $CLAUDE_PROJECT_DIR per fare riferimento agli script
• Se vedete “jq: command not found”, installate jq o utilizzate Python/Node.js per l’analisi JSON
• Se lo script non si esegue affatto, rendetelo eseguibile: chmod +x ./my-hook.sh

​

/hooks non mostra hook configurati

• Le modifiche ai file vengono normalmente raccolte automaticamente. Se non sono apparse dopo alcuni secondi, il file watcher potrebbe aver perso il cambiamento: riavviate la vostra sessione per forzare un ricaricamento.
• Verificate che il vostro JSON sia valido (le virgole finali e i commenti non sono consentiti)
• Confermate che il file di impostazioni è nella posizione corretta: .claude/settings.json per gli hook del progetto, ~/.claude/settings.json per gli hook globali

​

L’hook Stop si esegue per sempre

#!/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

​

Convalida JSON non riuscita

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

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

​

Tecniche di debug

​

Ulteriori informazioni

• Riferimento Hooks: schemi di eventi completi, formato di output JSON, hook asincroni e hook 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