Automatizzare i flussi di lavoro con hooks

Documentation Index

Fetch the complete documentation index at: https://code.claude.com/docs/llms.txt

Use this file to discover all available pages before exploring further.

​

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

osascript -e 'display notification "test"'

{
  "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": {
    "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à connesso. 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

{
  "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, UserPromptExpansion 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. Alcuni eventi non possono essere bloccati: per SessionStart, Setup, Notification 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: l’azione procede. La trascrizione mostra un avviso <hook name> hook error seguito dalla prima riga di stderr; lo stderr completo va al debug log.

​

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

​

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
  • PreToolUse: la chiamata dello strumento viene negata e il reason viene restituito a Claude come errore dello strumento, in modo che possa adattarsi e continuare
  • PostToolUse, 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 comando comunicano solo attraverso stdout, stderr e codici di uscita. Non possono attivare comandi / o chiamate di strumenti. Il testo restituito tramite additionalContext viene iniettato come un promemoria di sistema che Claude legge come testo semplice. Gli HTTP hooks comunicano attraverso il corpo della risposta invece.
• I timeout dell’hook variano in base al tipo. Sovrascrivete per hook con il campo timeout in secondi.
  • command, http, mcp_tool: 10 minuti. UserPromptSubmit riduce questi a 30 secondi.
  • prompt: 30 secondi.
  • agent: 60 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.
• Quando più hook PreToolUse restituiscono updatedInput per riscrivere gli argomenti di uno strumento, l’ultimo a terminare vince. Poiché gli hook si eseguono in parallelo, l’ordine è non deterministico. Evitate di avere più di un hook che modifica l’input dello stesso strumento.

​

Hooks e modalità di autorizzazione

​

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. Per evitare completamente le virgolette della shell, aggiungete "args": [] per passare alla forma exec, che genera lo script direttamente senza una shell
• 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, 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