Hook di Cursor: la guida completa, e perché a volte non si attivano

Gli hook di Cursor permettono a uno script di osservare o bloccare ciò che fa l'agente: ogni comando shell, ogni chiamata MCP, ogni lettura e modifica di file. Sono potenti, e falliscono in silenzio. Questo è tutto ciò che abbiamo imparato configurandoli sul serio.

Cosa sono gli hook di Cursor

Un hook è un comando che Cursor esegue in un punto preciso del ciclo dell'agente. Cursor invia sullo standard input del comando un oggetto JSON che descrive ciò che sta per succedere, attende e legge una risposta JSON dal suo standard output. Alcuni hook si limitano a osservare (registrare la modifica, formattare il file). Altri decidono: un hook beforeShellExecution può lasciar eseguire un comando, fermarlo o chiedere prima a te.

Questo rende gli hook lo strumento giusto per tre compiti: protezioni (mai eseguire rm -rf o git push --force senza una persona), automazione (formattare o eseguire il lint dopo ogni modifica) e visibilità (registrare o inoltrare ciò che fa l'agente per sapere quando ha bisogno di te).

Dove si trova hooks.json

Cursor legge gli hook da quattro posizioni e li esegue tutti. Ogni hook corrispondente di ogni origine viene eseguito, e Cursor unisce le loro risposte.

Quando le risposte non concordano, vince la più restrittiva: un deny da qualsiasi origine prevale su ask, e ask prevale su allow. Il file funzionante più piccolo ha questo aspetto (è l'esempio della documentazione di Cursor):

version deve essere 1. Cursor osserva il file e lo ricarica quando salvi. Se una modifica non ha effetto, riavvia Cursor. Già questo risolve un numero sorprendente di segnalazioni nel forum.

Gli eventi che puoi intercettare

L'elenco attuale dalla documentazione di Cursor, raggruppato per scopo:

Ogni evento riceve alcuni campi comuni (conversation_id, generation_id, model, hook_event_name, cursor_version, workspace_roots) più i propri. beforeShellExecution riceve il command completo e la sua cwd; stop riceve uno status che vale completed, aborted o error.

Consentire, negare e chiedere

Un hook decisionale stampa un solo oggetto JSON. Per l'hook della shell ha questo aspetto:

• permission è allow, deny o ask.
• user_message è ciò che vedi in Cursor.
• agent_message è ciò che viene detto all'agente, così può cambiare strada invece di riprovare lo stesso comando.

I codici di uscita contano quanto il JSON. L'uscita 0 significa “usa il mio JSON”. L'uscita 2 blocca l'azione, come deny. Qualsiasi altro codice di uscita viene trattato come un hook fallito, e l'azione prosegue, a meno che tu non imposti failClosed. Per gli hook di autorizzazione, un JSON non valido o non conforme allo schema blocca l'azione.

failClosed e timeout

Ogni voce di hook può avere delle opzioni accanto a command:

• failClosed: true trasforma un crash, un timeout, un'uscita diversa da zero o un output vuoto in un blocco. Il valore predefinito è false: un controllo guasto lascia passare tutto in silenzio. Per un hook di sicurezza, quasi sempre vuoi true.
• timeout è in secondi. Lascia abbastanza margine se il tuo hook attende una persona: chi legge un diff ha bisogno di più di cinque secondi.
• matcher filtra quando viene eseguito l'hook. Per gli hook della shell viene confrontato con la stringa del comando completa; per gli hook degli strumenti con il tipo di strumento, come Shell, Read, Write o MCP:<tool_name>.

C'è un compromesso. A luglio 2026 un utente su macOS si è imbattuto in “MainThreadShellExec not initialized”: l'host della shell di Cursor non era pronto e, poiché l'hook era fail-closed, la shell dell'agente veniva bloccata. Lo staff di Cursor ha detto che la correzione era stata rilasciata e ha consigliato di mantenere failClosed: true. Se vedi quell'errore su una build più vecchia, la soluzione temporanea era “Developer: Reload Window”.

Gli hook su Windows

Su Windows, l'app desktop di Cursor esegue i comandi degli hook tramite PowerShell e passa il JSON in pipe. Uno script PowerShell lo legge da $input; qualsiasi altro programma legge lo standard input come di consueto. Tre cose creano spesso problemi:

1. Gli script bash non funzionano così come sono. Un guard.sh di un collega su macOS fallisce in PowerShell. Usa uno script .ps1, un programma compilato, oppure chiama esplicitamente l'interprete (python .cursor/hooks/guard.py). Una discussione nel forum di gennaio 2026 mostra una configurazione con Git Bash che fallisce con syntax error near unexpected token '[Convert]::FromBase64String', cioè codice PowerShell che arriva a bash.
2. Criteri di esecuzione. Se PowerShell si rifiuta di eseguire script, avviali con powershell -NoProfile -ExecutionPolicy Bypass -File …, stampa il JSON e termina con exit 0.
3. I programmi GUI restituiscono il controllo troppo presto. Questo ci è costato una giornata. Se il tuo hook è un programma Windows compilato per il sottosistema GUI, PowerShell lo avvia e prosegue senza attendere. Cursor legge un output vuoto, quindi l'hook sembra non aver fatto nulla (oppure, con failClosed, blocca tutto). Compila l'hook come programma console, oppure avvolgilo in modo che PowerShell ne attenda la chiusura.

Anche gli hook di progetto richiedono un workspace attendibile. Un membro dello staff di Cursor ha elencato cosa controllare quando non fanno nulla: la riga del log Hooks “Hook N produced no output”, il workspace indicato come attendibile in Settings → Hooks ed errori come spawn, ENOENT, EPERM o ExecutionPolicy nella console.

Gli hook nella CLI di Cursor

La CLI di Cursor (cursor-agent) legge gli stessi ~/.cursor/hooks.json e .cursor/hooks.json, ma non ha mai inviato tutti gli eventi che invia l'editor. A gennaio 2026 si attivavano solo i due hook della shell. Ad aprile lo staff di Cursor ha confermato che beforeShellExecution, afterShellExecution, afterFileEdit, postToolUse, stop e sessionStart funzionavano nella CLI, mentre afterAgentResponse e afterAgentThought ancora no (confermato di nuovo a maggio). Per qualsiasi evento non presente in questo elenco, fai una prova prima di farci affidamento.

Gli agenti cloud sono ancora più restrittivi: gli hook a livello utente di ~/.cursor/hooks.json lì non vengono eseguiti affatto.

Quando un hook non si attiva: una checklist

1. Apri il canale di output Hooks (View → Output → Hooks) o la scheda Hooks in Customize. Mostra quali hook sono stati caricati, ogni esecuzione e gli errori.
2. Controlla il file JSON. "version": 1 presente, nomi degli eventi scritti esattamente (distinguono tra maiuscole e minuscole), JSON valido.
3. Controlla il percorso. I comandi relativi vengono risolti dalla radice del progetto per gli hook di progetto e da ~/.cursor/ per gli hook utente.
4. Considera attendibile il workspace. Gli hook di progetto non vengono eseguiti in una cartella non attendibile.
5. Esegui l'hook a mano. Passagli in pipe un JSON di esempio e guarda stdout. Qualsiasi cosa diversa da un unico oggetto JSON (un echo di troppo, un avviso) rompe il parsing.
6. Riavvia Cursor. Il salvataggio ricarica il file, ma diverse segnalazioni nel forum sono state risolte solo con un riavvio completo.
7. Conosci le lacune. ask e allow sono stati segnalati come ignorati insieme all'elenco dei comandi consentiti e alla sandbox; subagentStart/subagentStop sono stati segnalati come non attivati in alcune versioni; la CLI salta alcuni eventi. I commit dal pannello Source Control integrato non vengono intercettati: non esiste un evento di hook pre-commit.

Hook, auto-run e Auto-review

Gli hook sono separati dalle impostazioni di approvazione di Cursor (Settings → Agents → Approvals & Execution). Auto-run e Auto-review decidono se Cursor ti chiede conferma nel suo pannello; il tuo hook vi sovrappone la propria decisione. Ecco perché “il mio hook ha detto ask, ma il comando è stato eseguito” è una segnalazione così comune: un altro percorso di autorizzazione lo aveva già consentito.

Un'altra cosa che abbiamo imparato a nostre spese: con Auto-review, Cursor può chiedere di alcuni comandi nella sua finestra. Un hook non vede mai quella domanda. Avviene dentro Cursor, non nella pipeline degli hook.

Dove si inserisce Pet Island

Se dagli hook vuoi “mostrami ogni comando rischioso e fammi decidere senza cambiare finestra”, è quello che fa Pet Island con Cursor. Installa gli hook per te (beforeShellExecution e beforeMCPExecution, con failClosed attivo così un helper fermo non lascia mai passare un comando) e mette ogni richiesta su una piccola isola nella parte alta dello schermo, con il comando completo. Lo consenti o lo neghi lì; l'agente di Cursor attende.

I comandi e le modifiche ai file dall'editor di Cursor funzionano dall'isola. Domande e piani compaiono sull'isola, e rispondi da Cursor. Nella CLI di Cursor i comandi funzionano dall'isola; gli altri eventi dipendono da ciò che invia la CLI. La disinstallazione rimuove solo le voci aggiunte da Pet Island; i tuoi hook restano.

FAQ

Fonti

Ogni impostazione e comportamento descritti in questa pagina sono stati verificati su queste pagine il 26 ottobre 2026. Gli agenti cambiano in fretta: se qualcosa non corrisponde più, fa fede la pagina ufficiale.

• Documentazione di Cursor: Hooks
• Forum di Cursor: gli hook di Cursor non vengono eseguiti come previsto (staff: viene applicato solo deny)
• Forum di Cursor: allow/ask di beforeShellExecution ignorati, l'elenco dei comandi consentiti ha la precedenza
• Forum di Cursor: hook fail-closed e MainThreadShellExec not initialized
• Forum di Cursor: un JSON malformato restituito da un hook consentiva il comando in silenzio (corretto)
• Forum di Cursor: la CLI di Cursor non invia tutti gli eventi degli hook
• Forum di Cursor: gli hook di progetto non vengono eseguiti su Windows
• Forum di Cursor: gli hook di progetto falliscono su Windows con Git Bash
• Forum di Cursor: subagentStart e subagentStop non si attivano mai

CONTINUA A LEGGERE