Come funzionano gli hook

Il supervisore degli hook è la parte di Pathrule che, durante le sessioni con l'IA, ti dà l'impressione che l'assistente conoscesse già le convenzioni del tuo team. Gira in locale, legge da una cache, fornisce le memorie e le regole pertinenti e propone le skill per nome prima che l'assistente compia la sua prima azione. Le istruzioni di una skill arrivano quando la invochi.

Questa pagina descrive il meccanismo dal punto di vista di chi lo usa. Non è un approfondimento sui dettagli interni del runtime.

Che cos'è un hook

Un hook è un piccolo script che il tuo client IA invoca in momenti ben definiti di un turno. Pathrule usa gli eventi di consegna e di applicazione che ciascun client espone davvero.

• SessionStart comunica all'assistente il workspace in cui si trova, il protocollo di Pathrule e il contesto del tuo team, una volta per sessione.
• UserPromptSubmit delimita l'ambito del turno successivo sui client il cui evento di prompt accetta contesto.
• PreToolUse fornisce contesto o una decisione basata su una regola vincolante prima di un'azione, quando il client lo accetta.
• PostToolUse registra gli esiti e compensa con contesto legato al percorso sui client il cui evento pre-tool accetta decisioni ma non contesto.
• Gli eventi Stop e di fine sessione chiudono il turno. Su Claude Code e Codex, un controllo obbligatorio approvato da una persona può tenere aperto il turno in questo punto finché il relativo comando non ha avuto esito positivo.

pathrule setup e pathrule sync, oppure l'estensione per VS Code, registrano questi hook per Claude Code, Codex, Cursor e GitHub Copilot. Windsurf non ha hook di Pathrule, quindi è il file di regole generato a occuparsi dell'avvio della sessione, mentre il server MCP locale fornisce contesto più approfondito su richiesta.

Profili di consegna per client

Una regola vincolante è una regola che contiene un pattern di blocco approvato da una persona. Consulta Le regole come guardrail per capire cosa blocca e cosa invece si limita a informare.

Cosa fa l'hook

Il supervisore degli hook esegue quattro operazioni, in quest'ordine.

1. Risolve il percorso. Associa la directory di lavoro a un nodo del workspace.
2. Legge la cache. La cache locale contiene un indice precalcolato di memorie, regole e skill per quel percorso.
3. Modella la porzione. Sceglie una profondità adatta all'intento. Una piccola modifica alla UI riceve un payload minimo. Una correzione di bug o un refactoring ne riceve uno mirato. I prompt di esplorazione ne sbloccano uno più approfondito.
4. Restituisce il payload. Il testo torna al client come contesto di sistema per l'azione successiva.

In modalità locale l'intero flusso gira sulla tua macchina. In un workspace Cloud, l'hook del prompt invia anche l'inizio del tuo prompt (all'incirca i primi 1.000 caratteri) a Pathrule Cloud, così da poter dare priorità alla conoscenza in base al significato. Se quella chiamata è lenta o fallisce, l'hook ripiega sul confronto con l'indice locale, quindi un problema di rete non lascia il turno senza contesto.

Cosa vedi

L'area di contesto dell'assistente (quella esposta dal tuo editor) si arricchisce di una sezione Pathrule, che elenca:

• Il percorso risolto dall'hook, più i percorsi in cui è più probabile che si trovi il lavoro: un itinerario che l'assistente deve aprire prima di mettersi a cercare. Pathrule registra se lo ha fatto.
• Le regole corrispondenti, con la rispettiva priorità.
• Le memorie più pertinenti al tuo prompt, fornite come corpi completi su cui l'assistente può agire direttamente. Le corrispondenze meno certe arrivano comunque come titoli con id, che puoi leggere per intero se vuoi.
• Le skill adatte a questo ambito, per nome, pronte da invocare con ::skill-name.

Se l'hook non ha nulla di nuovo e pertinente per il percorso corrente, non aggiunge niente: un turno senza novità non consuma contesto.

Due canali di consegna

La conoscenza raggiunge l'assistente attraverso due canali di hook con compiti diversi.

• Il canale per prompt viene eseguito una volta, quando invii un prompt, sui client dotati di hook di invio del prompt (Claude Code e Codex). È qui che sta la profondità: le regole adatte al prompt, le memorie con la corrispondenza più forte come corpi completi su cui l'assistente può agire direttamente e le skill che sembrano pertinenti, proposte per nome. Una skill è una procedura, quindi non viene mai imposta come istruzione; il suo corpo completo arriva quando la invochi con ::skill-name.
• Il canale per chiamata a strumento viene eseguito prima o dopo ogni azione su file o shell, molte volte per turno. Resta volutamente leggero: i nomi e i riepiloghi di una riga delle regole e delle memorie che si applicano al percorso su cui si sta lavorando, così l'assistente sa cosa esiste lì e, se gli serve, può leggerne il corpo con una sola chiamata.

Su Claude Code e Codex arrivano all'assistente sia il canale del prompt sia quello pre-tool. Cursor e GitHub Copilot non accettano contesto sul loro evento di prompt, quindi l'avvio passa dall'hook di inizio sessione e i nomi legati al percorso dall'hook post-tool.

Nessuno dei due canali si ripete. Un corpo già fornito nella sessione non viene riproposto, mentre uno modificato torna la volta successiva in cui è rilevante.

Cosa resta su disco

Un client con l'hook di Pathrule installato riceve il protocollo e il contesto del team dall'hook di inizio sessione anziché dal proprio file di istruzioni. Su Claude Code il contesto di inizio sessione entra nel prompt di sistema, quindi sopravvive alla compattazione della conversazione. Il file di istruzioni (CLAUDE.md, AGENTS.md, la regola di Cursor o le istruzioni di Copilot) conserva solo una breve nota di Pathrule, e Pathrule rimuove le copie del protocollo e i file di conoscenza per directory che aveva scritto nelle versioni precedenti. I tuoi contenuti in quei file restano dove sono.

In due casi i file compilati vengono mantenuti:

• Un client senza hook di Pathrule, come Windsurf, o un client il cui hook non è installato, conserva il protocollo completo e i file di conoscenza per percorso, perché nient'altro li fornirebbe.
• Se una versione precedente di Pathrule ha spostato il tuo file di istruzioni in un backup non ancora ripristinato, Pathrule mantiene il file completo finché quel backup non viene gestito, così non ti ritrovi mai davanti a una breve nota mentre le tue istruzioni si trovano altrove.

Per mantenere i file compilati anche con l'hook installato, imposta PATHRULE_SIGNATURE_MODE=off nell'ambiente del runtime di Pathrule.

Quando l'hook non basta

Gli hook sono pensati per il caso più comune. Quando serve di più, l'assistente può sempre ricorrere agli strumenti MCP.

• Per i prompt di esplorazione ("elenca tutto quello che sappiamo sulla fatturazione"), l'assistente chiama direttamente pathrule_get_context.
• Per il corpo completo di una memoria, l'assistente chiama pathrule_read_memory con l'id mostrato dall'hook.
• Per le scritture (l'utente chiede di salvare una convenzione o una regola), l'assistente usa lo strumento di scrittura corrispondente.

L'hook è la via rapida. MCP è la via approfondita. Entrambi attingono alla stessa fonte di verità.

L'ambito del percorso mantiene tutto compatto

L'hook restituisce una porzione modellata in base alla directory di lavoro.

• Una modifica in apps/web/dashboard non si porta dietro le regole sulle migrazioni del database.
• Una modifica in services/billing/webhooks porta con sé le regole sulla fatturazione e la skill per la riproduzione dei webhook, non le convenzioni del sito marketing.
• Un prompt di esplorazione alla radice del repository porta una panoramica del workspace, non tutti i corpi.

È l'ambito del percorso a mantenere ridotto il contesto fornito, rispetto a un unico file di istruzioni globale che ogni sessione carica per intero.

Quando non compare nulla

Se apri una sessione e la sezione Pathrule è vuota, esegui il doctor.

pathrule doctor

Funziona in sola lettura e verifica:

• L'accesso, l'organizzazione e il workspace.
• Se la cartella corrente è collegata a un workspace.
• Se la voce MCP di Pathrule è installata per ciascun client IA.
• Quali file gestiti da Pathrule si trovano nella cartella, e quale componente e quale versione di Pathrule li hanno scritti.

L'output termina con il comando da eseguire quando qualcosa richiede attenzione. Aggiungi --json per il report completo, che copre anche la versione di Node e segnala le voci MCP che puntano a un runtime che non esiste più.

Per rimettere in ordine i componenti locali, esegui:

pathrule repair

Il repair riscrive le voci MCP obsolete, reinstalla lo script dell'hook e la registrazione dell'hook di ciascun client, risincronizza i file di supporto e la cache locale letta dall'hook, quindi esegue di nuovo il doctor.

Se vuoi disattivare in un colpo solo tutti gli hook di Pathrule, crea ~/.pathrule/kill-hooks. La chiamata successiva a un hook passa oltre senza fare nulla; rimuovi il file per riattivare gli hook.

Cosa leggere dopo

• Panoramica di MCP per gli strumenti su cui si basa la via approfondita.
• Concetti fondamentali per il modello dei dati da cui legge l'hook.
• Installazione della CLI per installare il runtime che ospita il supervisore degli hook.