Hook di sessione

Con SessionHooks intercetti il ciclo di vita di una sessione Copilot per implementare controllo di esecuzione, audit e logica di ripristino.

​

Hook di sessione

Con hooks puoi inserire logica in ciascuna fase del ciclo di vita di una sessione Copilot. Puoi aggiungere controllo dell’esecuzione degli strumenti, log di audit, arricchimento del prompt, gestione degli errori e altro senza modificare l’implementazione core.

​

Flusso degli hook

​

Uso di base

use Revolution\Copilot\Contracts\CopilotSession;
use Revolution\Copilot\Facades\Copilot;
use Revolution\Copilot\Types\SessionHooks;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookInput;
use Revolution\Copilot\Types\Hooks\ErrorOccurredHookOutput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PostToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookInput;
use Revolution\Copilot\Types\Hooks\PreToolUseHookOutput;
use Revolution\Copilot\Types\Hooks\SessionEndHookInput;
use Revolution\Copilot\Types\Hooks\SessionEndHookOutput;
use Revolution\Copilot\Types\Hooks\SessionStartHookInput;
use Revolution\Copilot\Types\Hooks\SessionStartHookOutput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookInput;
use Revolution\Copilot\Types\Hooks\UserPromptSubmittedHookOutput;

Copilot::start(function (CopilotSession $session) {
    $response = $session->sendAndWait(prompt: 'Riassumi i punti chiave del README');
    dump($response->content());
}, config: [
    'model' => 'gpt-5',
    'hooks' => new SessionHooks(
        onSessionStart: function (SessionStartHookInput $input): ?SessionStartHookOutput {
            return new SessionStartHookOutput(
                additionalContext: "Project root: {$input->cwd}",
            );
        },

        onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
            if (str_starts_with($input->prompt, '/fix')) {
                return new UserPromptSubmittedHookOutput(
                    modifiedPrompt: 'Correggi l\'errore corrente e riassumi le modifiche.',
                );
            }

            return null;
        },

        onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
            $blocked = ['bash', 'shell', 'delete_file'];

            if (in_array($input->toolName, $blocked, true)) {
                return new PreToolUseHookOutput(
                    permissionDecision: 'deny',
                    permissionDecisionReason: "{$input->toolName} non è consentito in questo ambiente",
                );
            }

            return new PreToolUseHookOutput(permissionDecision: 'allow');
        },

        onPostToolUse: function (PostToolUseHookInput $input): ?PostToolUseHookOutput {
            if ($input->toolName === 'read_file') {
                return new PostToolUseHookOutput(
                    additionalContext: 'Se necessario, esplora anche i file correlati e confrontali.',
                );
            }

            return null;
        },

        onErrorOccurred: function (ErrorOccurredHookInput $input): ?ErrorOccurredHookOutput {
            if ($input->errorContext === 'model_call' && $input->recoverable) {
                return new ErrorOccurredHookOutput(
                    errorHandling: 'retry',
                    retryCount: 2,
                    userNotification: 'Errore temporaneo del modello, si tenta di nuovo.',
                );
            }

            return null;
        },

        onSessionEnd: function (SessionEndHookInput $input): ?SessionEndHookOutput {
            if ($input->reason !== 'complete') {
                return new SessionEndHookOutput(
                    sessionSummary: "Session ended with reason: {$input->reason}",
                );
            }

            return null;
        },
    ),
]);

​

Hook disponibili

Hook	Momento di attivazione	Uso principale
onSessionStart	Avvio sessione (new / resume / startup)	Iniezione di contesto iniziale, override di configurazione
onUserPromptSubmitted	All’invio di un prompt utente	Arricchimento prompt, espansione template, filtro input
onPreToolUse	Prima dell’esecuzione dello strumento	Consenti/nega/chiedi, modifica argomenti, sopprimi output
onPostToolUse	Dopo l’esecuzione dello strumento	Modifica risultato, mascheramento dati sensibili, audit log
onErrorOccurred	All’occorrenza di un errore in sessione	Retry, notifiche, classificazione degli errori
onSessionEnd	Alla chiusura della sessione	Cleanup, metriche, riepilogo finale

Restituendo null prosegue il comportamento predefinito.

​

Casi d’uso tipici

​

1) Permission control (controllo esecuzione)

• Usa onPreToolUse per applicare una allow-list di strumenti
• Le operazioni distruttive richiedono approvazione umana con permissionDecision: 'ask'
• Motiva il rifiuto con permissionDecisionReason
• Consulta l’elenco di Tools per i possibili toolName (es. view, glob, bash)

​

2) Auditing / compliance

• Combina gli hook del ciclo di vita per raccogliere eventi di audit
• Persisti i dati raccolti per singolo ID sessione

​

3) Prompt enrichment (arricchimento input)

• In onSessionStart aggiungi le informazioni del progetto (linguaggio, framework, convenzioni) in additionalContext
• In onUserPromptSubmitted espandi shortcut (/fix, /test)

​

4) Result filtering (formattazione dei risultati)

• In onPostToolUse maschera API key / token / password ecc.
• Sintetizza i risultati troppo lunghi e restituisci i dettagli solo se necessario

​

5) Error recovery (ripristino)

• In onErrorOccurred esegui retry solo quando model_call e recoverable=true
• Per errori non recuperabili notifica in modo conciso l’utente tramite userNotification

​

6) Session metrics (misurazione)

• In onSessionStart registra l’orario di inizio
• In onPreToolUse / onUserPromptSubmitted aggiorna i contatori
• In onSessionEnd emetti durata, numero di strumenti e motivo di terminazione

​

Tipi di input / output degli hook

​

Input comune (BaseHookInput)

Proprietà	Tipo	Descrizione
timestamp	int	Timestamp di attivazione (Unix ms)
cwd	string	Directory di lavoro corrente

​

PreToolUseHookInput

Proprietà	Tipo	Descrizione
toolName	string	Nome dello strumento che sta per essere eseguito
toolArgs	mixed	Argomenti previsti per l’esecuzione

​

PreToolUseHookOutput

Proprietà	Tipo	Descrizione
permissionDecision	?string	allow / deny / ask
permissionDecisionReason	?string	Motivo in caso di rifiuto/conferma
modifiedArgs	mixed	Argomenti dopo l’override
additionalContext	?string	Contesto aggiuntivo
suppressOutput	?bool	Sopprime l’output dello strumento

​

PostToolUseHookInput

Proprietà	Tipo	Descrizione
toolName	string	Nome dello strumento eseguito
toolArgs	mixed	Argomenti dell’esecuzione
toolResult	ToolResultObject|array	Risultato dello strumento

​

PostToolUseHookOutput

Proprietà	Tipo	Descrizione
modifiedResult	ToolResultObject|array|null	Risultato dopo la modifica
additionalContext	?string	Contesto aggiuntivo
suppressOutput	?bool	Sopprime la visualizzazione del risultato

​

UserPromptSubmittedHookInput

Proprietà	Tipo	Descrizione
prompt	string	Prompt inserito dall’utente

​

UserPromptSubmittedHookOutput

Proprietà	Tipo	Descrizione
modifiedPrompt	?string	Prompt modificato
additionalContext	?string	Contesto integrativo
suppressOutput	?bool	Sopprime la visualizzazione della risposta

​

SessionStartHookInput

Proprietà	Tipo	Descrizione
source	string	startup / resume / new
initialPrompt	?string	Prompt iniziale

​

SessionStartHookOutput

Proprietà	Tipo	Descrizione
additionalContext	?string	Contesto iniziale della sessione
modifiedConfig	?array	Override parziale della configurazione

​

SessionEndHookInput

Proprietà	Tipo	Descrizione
reason	string	complete / error / abort / timeout / user_exit
finalMessage	?string	Messaggio finale
error	?string	Errore al termine

​

SessionEndHookOutput

Proprietà	Tipo	Descrizione
suppressOutput	?bool	Sopprime l’output finale
cleanupActions	?array	Informazioni sulle azioni di cleanup eseguite
sessionSummary	?string	Riepilogo della sessione

​

ErrorOccurredHookInput

Proprietà	Tipo	Descrizione
error	string	Messaggio d’errore
errorContext	?string	Uno tra model_call / tool_execution / system / user_input
recoverable	bool	Se è recuperabile

​

ErrorOccurredHookOutput

Proprietà	Tipo	Descrizione
suppressOutput	?bool	Sopprime la visualizzazione dell’errore
errorHandling	?string	retry / skip / abort
retryCount	?int	Numero di retry
userNotification	?string	Testo di notifica all’utente

​

ToolResultObject

Oggetto standard per il risultato di uno strumento.

Proprietà	Tipo	Descrizione
textResultForLlm	?string	Risultato testuale da passare all’LLM
resultType	?string	success / failure / rejected / denied
resultForAssistant	?array	Dati di risultato per l’assistente

​

Best practice

1. Non eseguire troppi processi sincroni pesanti direttamente negli hook. Se necessario, rendili asincroni.
2. Quando non sono necessarie modifiche, restituisci null e lascia il comportamento predefinito.
3. Rendi esplicito permissionDecision quando possibile.
4. Non sopprimere eccessivamente gli errori critici: prevedi percorsi di log/notifica.
5. Gestisci lo stato per sessione basandoti sull’ID e ripulisci in onSessionEnd.

Per le informazioni più recenti fai riferimento al repository GitHub.