Hook di Claude Code: controllo deterministico su ciò che fa l'agente

Struttura di un hook

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

Tre parti: l'evento, un matcher (una regex sul nome dello strumento per gli eventi degli strumenti; omettilo per includere tutto) e uno o più comandi. Il comando riceve su stdin un oggetto JSON che descrive l'evento; per gli eventi degli strumenti include tool_name e tool_input, che permette all'esempio precedente di individuare il file appena modificato. Inseriscilo in .claude/settings.json per condividerlo con il repository, ~/.claude/settings.json per uso personale, oppure esegui /hooks e lascia che sia Claude Code a scriverlo.

Gli eventi

• PreToolUse — prima dell'esecuzione di uno strumento. L'unico evento che può bloccare: il codice di uscita 2 annulla la chiamata e Claude legge stderr come motivo.
• PostToolUse — dopo che uno strumento ha completato l'operazione con successo. Formattatori, linter e controlli dei tipi sul file modificato.
• UserPromptSubmit — quando invii un prompt; può aggiungere contesto o rifiutare il prompt.
• Stop / SubagentStop — quando l'agente (o un sottoagente) sta per terminare. Qui il codice di uscita 2 significa "non è ancora finita": l'uso classico è impedire l'arresto finché i test falliscono.
• PreCompact — prima di /compact; salva tutto ciò che ti serve dalla trascrizione completa.
• SessionStart — quando una sessione inizia o riprende; carica l'ambiente, stampa promemoria.
• Notification — quando Claude Code richiede la tua attenzione (richiesta di autorizzazione, inattività); collegalo a una notifica desktop o Slack.

Bloccare i comandi pericolosi

#!/usr/bin/env bash
# .claude/hooks/guard.sh  -- PreToolUse, matcher: Bash
cmd=$(jq -r '.tool_input.command')
if echo "$cmd" | grep -Eq 'rm -rf|git push --force|DROP TABLE|--no-verify'; then
  echo "blocked by guard.sh: $cmd" >&2
  exit 2
fi
exit 0

Il codice di uscita 2 definisce il comportamento: la chiamata allo strumento non viene eseguita e tutto ciò che l'hook ha scritto su stderr diventa la spiegazione mostrata a Claude, che può così scegliere un approccio diverso anziché riprovare la stessa operazione. Qualsiasi altro codice di uscita diverso da zero viene registrato, ma non blocca l'operazione.

"Non fermarti finché i test non passano"

#!/usr/bin/env bash
# Stop hook: refuse to finish while the suite is red
if ! npm test --silent >/tmp/claude-test.log 2>&1; then
  echo "Tests are failing; fix them before finishing:" >&2
  tail -n 40 /tmp/claude-test.log >&2
  exit 2
fi

Abbinalo a un limite di --max-turns nelle esecuzioni senza interfaccia, così un errore davvero irrisolvibile non genera un ciclo infinito.

Hook, CLAUDE.md e autorizzazioni a confronto

CLAUDE.md contiene indicazioni che il modello legge; /permissions è un elenco di ciò che può fare senza chiedere; gli hook sono codice che viene eseguito in ogni caso. Usa CLAUDE.md per lo stile e il contesto, le autorizzazioni per stabilire cosa è consentito e cosa richiede conferma, e gli hook per tutto ciò che deve essere garantito ogni volta: formattazione, scansione dei segreti, controlli obbligatori dei test, log di audit. Si combinano: un'autorizzazione consente l'esecuzione di Bash(git *) , mentre un hook PreToolUse blocca comunque git push --force.

Gli hook e il gateway

Gli hook vengono eseguiti localmente e non accedono mai all'API, quindi non cambia nulla quando Claude Code punta a ANTHROPIC_BASE_URL=https://aiprimetech.io. Una combinazione utile: un hook Stop che stampa /costcome riepilogo dell'utilizzo ricavato dai tuoi log, così un team che usa crediti a consumo vede il costo di ogni sessione alla sua conclusione.

export ANTHROPIC_BASE_URL=https://aiprimetech.io
export ANTHROPIC_API_KEY=your_key

Domande frequenti

AI Prime Tech è un gateway API indipendente e non è affiliato ad Anthropic, né approvato o sponsorizzato da Anthropic. «Claude» e «Claude Code» sono marchi di Anthropic. Le funzionalità di Claude Code descritte qui rispecchiano la documentazione pubblica di Anthropic al momento della stesura e cambiano frequentemente; i prezzi e gli elenchi dei modelli presenti in questa pagina vengono letti dalle impostazioni attuali di questo gateway.