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. Si tratta di una funzionalità distinta dagli hooks dichiarativi nella definizione di un agente personalizzato e dal caricamento degli hook basati su file. Per la configurazione per agente consulta Agenti personalizzati.

Rilevamento degli hook basati su file

In hookDirectories puoi specificare radici esplicite in cui rilevare gli hook basati su file. Serve solo per il rilevamento e non concede all’agente permessi generali di accesso ai file. Le radici esplicite sono utilizzabili anche se enableConfigDiscovery o enableFileHooks sono disabilitati. I percorsi relativi vengono risolti una sola volta rispetto alla workingDirectory effettiva al momento della specifica.

Omesso o null: non modifica le altre fonti di rilevamento
[]: cancella solo le radici SDK specificate esplicitamente

Le impostazioni di disabilitazione delle fonti degli hook e le Managed Settings continuano ad applicarsi. enableFileHooks controlla gli hook su file provenienti dal repository (.github/hooks/ e le radici delle impostazioni di repository attendibili). Non disabilita le hookDirectories esplicite né gli hooks con callback PHP.

use Revolution\Copilot\Types\SessionConfig;

$config = new SessionConfig(
    workingDirectory: '/workspace/project',
    enableFileHooks: false,
    hookDirectories: ['../shared-hooks'],
);

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.

Blocco del prompt

onUserPromptSubmitted può rifiutare il prompt restituendo decision: 'block'. In caso di rifiuto, il turn del modello non viene avviato e il messaggio dell’utente non viene registrato. Se specifichi reason, il suo contenuto viene incluso in un evento temporaneo session.warning con warningType: "policy_blocked".

onUserPromptSubmitted: function (UserPromptSubmittedHookInput $input): ?UserPromptSubmittedHookOutput {
    if (str_contains($input->prompt, 'restricted')) {
        return new UserPromptSubmittedHookOutput(
            decision: 'block',
            reason: 'Questo prompt non è consentito.',
        );
    }

    return null;
},

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
`sessionId`	`string`	ID della sessione runtime correlata. Negli hook degli strumenti figli è la sessione figlia, negli hook di avvio/arresto dei subagent è l’ID della sessione padre
`timestamp`	`int`	Timestamp di attivazione (Unix ms)
`cwd`	`string`	Directory di lavoro corrente
`agentId`	`?string`	ID attore del subagent che esegue l’hook
`agentType`	`?string`	Tipo di subagent
`parentAgentId`	`?string`	ID dell’attore padre diretto

agentId / agentType / parentAgentId sono disponibili negli hook in cui l’attore è un subagent. Non sono inclusi negli hook dell’agente root. Nei runtime meno recenti, se l’informazione non è disponibile, il campo stesso viene omesso. Per questo motivo, ciascuno di essi può essere null.

onPreToolUse: function (PreToolUseHookInput $input): ?PreToolUseHookOutput {
    if ($input->agentId !== null) {
        logger()->info('Subagent tool use', [
            'agentId' => $input->agentId,
            'agentType' => $input->agentType,
            'parentAgentId' => $input->parentAgentId,
            'tool' => $input->toolName,
        ]);
    }

    return null;
},

`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
`decision`	`?string`	Con `block` rifiuta il prompt e impedisce il turn del modello e la registrazione del messaggio utente
`reason`	`?string`	Motivo del rifiuto. Incluso nell’evento `session.warning`

`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. Se il runtime passa un oggetto errore, il valore di `message` se è una stringa, altrimenti la stringa JSON dell’oggetto

`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. Se il runtime passa un oggetto errore, il valore di `message` se è una stringa, altrimenti la stringa JSON dell’oggetto
`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.

GitHub Copilot

SDK

AI SDK

VOICEVOX

Starter kit

Feed e RSS

Middleware

Hook di sessione

Hook di sessione

Rilevamento degli hook basati su file

Flusso degli hook

Uso di base

Hook disponibili

Blocco del prompt

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

​Rilevamento degli hook basati su file

​Flusso degli hook

​Uso di base

​Hook disponibili

​Blocco del prompt

​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

Rilevamento degli hook basati su file

Flusso degli hook

Uso di base

Hook disponibili

Blocco del prompt

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