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

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

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

​Hook di sessione

​Flusso degli hook

​Uso di base

​Hook disponibili

​Casi d’uso tipici

​1) Permission control (controllo esecuzione)

​2) Auditing / compliance

​3) Prompt enrichment (arricchimento input)

​4) Result filtering (formattazione dei risultati)

​5) Error recovery (ripristino)

​6) Session metrics (misurazione)

​Tipi di input / output degli hook

​Input comune (BaseHookInput)

​PreToolUseHookInput

​PreToolUseHookOutput

​PostToolUseHookInput

​PostToolUseHookOutput

​UserPromptSubmittedHookInput

​UserPromptSubmittedHookOutput

​SessionStartHookInput

​SessionStartHookOutput

​SessionEndHookInput

​SessionEndHookOutput

​ErrorOccurredHookInput

​ErrorOccurredHookOutput

​ToolResultObject

​Best practice

Hook di sessione

Flusso degli hook

Uso di base

Hook disponibili

Casi d’uso tipici

1) Permission control (controllo esecuzione)

2) Auditing / compliance

3) Prompt enrichment (arricchimento input)

4) Result filtering (formattazione dei risultati)

5) Error recovery (ripristino)

6) Session metrics (misurazione)

Tipi di input / output degli hook

Input comune (`BaseHookInput`)

`PreToolUseHookInput`

`PreToolUseHookOutput`

`PostToolUseHookInput`

`PostToolUseHookOutput`

`UserPromptSubmittedHookInput`

`UserPromptSubmittedHookOutput`

`SessionStartHookInput`

`SessionStartHookOutput`

`SessionEndHookInput`

`SessionEndHookOutput`

`ErrorOccurredHookInput`

`ErrorOccurredHookOutput`

ToolResultObject

Best practice