> ## Documentation Index
> Fetch the complete documentation index at: https://kawax.biz/llms.txt
> Use this file to discover all available pages before exploring further.

# 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

```mermaid theme={null}
flowchart LR
    A[Session starts] -->|onSessionStart| B[User prompt]
    B -->|onUserPromptSubmitted| C[Pre tool]
    C -->|onPreToolUse| D[Tool execution]
    D -->|onPostToolUse| E{Continue?}
    E -->|yes| C
    E -->|no| F[Session ends]
    F -->|onSessionEnd| G((Done))
    C -. error .-> H[onErrorOccurred]
    D -. error .-> H
```

## Uso di base

```php theme={null}
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](/it/packages/laravel-copilot-sdk/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`.

<Info>
  Per le informazioni più recenti fai riferimento al [repository GitHub](https://github.com/invokable/laravel-copilot-sdk).
</Info>


## Related topics

- [Loop dell'agente](/it/packages/laravel-copilot-sdk/agent-loop.md)
- [Eventi del ciclo di vita della sessione](/it/packages/laravel-copilot-sdk/session-lifecycle-event.md)
- [⚡Introduzione a Livewire 4 — creare UI reattive senza JavaScript](/it/blog/livewire-introduction.md)
- [Test HTTP](/it/http-tests.md)
- [Ripresa della sessione](/it/packages/laravel-copilot-sdk/resume.md)