SessionStart: contesto dopo compaction

SessionStart è l’evento di Claude Code utile per aggiungere contesto dinamico quando una sessione parte o riprende. Può essere filtrato sul motivo di avvio, incluso compact, per fornire un orientamento dopo la compaction. È adatto a informazioni piccole e verificabili, come il branch corrente o il riferimento alla checklist del lavoro; le istruzioni statiche hanno già il loro percorso nei file di memoria. SessionStart nella reference.

L’obiettivo non è ricostruire tutta la conversazione a ogni ripresa. Un hook dovrebbe recuperare ciò che serve dal progetto e indicarne la provenienza. Copiare grandi log, tutte le variabili ambiente o cartelle intere può aggiungere rumore e rendere disponibili dati inutili. La guida ai Claude Code Hooks introduce evento, matcher e handler; qui il tema è il contesto che vale la pena reinserire.

Fonti verificate il 9 ottobre 2026. Gli esempi sono ipotetici e gli snippet non sono stati eseguiti in questa guida. Non viene attribuita ai hook una memoria perfetta né una riduzione misurata dei costi.

Che cosa cambia quando il contesto viene compattato?

La compaction produce una rappresentazione sintetica del lavoro per consentire la continuazione della sessione. Non deve essere confusa con un archivio completo e nemmeno con una cancellazione universale delle istruzioni persistenti. La documentazione della memoria descrive caricamento dei file e comportamento dopo la compaction; partire dall’idea che tutto sia perduto porta spesso a copie inutili. Memoria di Claude Code.

Il problema pratico è orientarsi correttamente: quale obiettivo resta attivo, quali file contengono lo stato e quali controlli sono davvero conclusi? Un piccolo riferimento può essere più utile di una ripetizione del riassunto. Se il repository conserva un documento del task, l’agente può leggerlo invece di ricevere una copia parziale generata da uno script.

Le informazioni durevoli devono essere aggiornate quando avvengono i fatti. Un hook eseguito alla ripresa non può inventare un risultato di test mai registrato né sapere quale decisione sia stata presa fuori dal progetto. Per questo la qualità dello stato scritto conta prima della qualità del messaggio inserito dal hook.

Quali informazioni appartengono a CLAUDE.md?

Istruzioni stabili come comandi del progetto, responsabilità dei moduli e convenzioni possono vivere in un file di memoria. Sono diverse da un branch che cambia durante il lavoro o da una suite ancora in esecuzione. La documentazione raccomanda il percorso di memoria per contesto statico che non necessita di script. SessionStart e contesto statico.

Non trasformare il hook in una seconda fonte di verità contraddittoria. Se il documento del progetto dice di usare un package manager e lo script suggerisce un altro comando, la ripresa riceve due istruzioni incompatibili. Conserva le regole in un luogo e fai aggiungere al hook soltanto il riferimento o il dato dinamico necessario.

Una convenzione nel file di istruzioni rimane contesto. Per impedire una classe di operazioni serve un controllo effettivo, come una regola di permessi o PreToolUse per i file protetti. Rileggere “non modificare questa cartella” dopo compaction non equivale a bloccare tecnicamente una tool call.

Come distinguere stato, prova e promemoria?

Un dato di stato descrive la situazione del progetto: branch, file modificati, task attivo. Una prova documenta un controllo concluso, con comando e revisione pertinente. Un promemoria indica un’attività da svolgere. Mescolare questi tre elementi rende facile interpretare “esegui i test” come “i test sono stati eseguiti”.

Il messaggio deve conservare la distinzione. “Risultato precedente da riconfermare se i file sono cambiati” è più preciso di “test verdi”. Per il feedback dopo gli edit, PostToolUse per formatter e test spiega come raccogliere un esito che appartenga al lavoro corrente.

Un piccolo hook che legge soltanto il branch

Questo esempio shell aggiunge un dato dinamico limitato. Richiede Git e CLAUDE_PROJECT_DIR, non legge file del cliente e non stampa lo stato completo dell’ambiente. È un esempio didattico non eseguito. In un progetto reale va provato anche il caso di detached HEAD e quello di una directory non Git.

#!/bin/sh
set -eu
project_dir=${CLAUDE_PROJECT_DIR:?Progetto non disponibile}
if branch=$(git -C "$project_dir" branch --show-current 2>/dev/null); then
  if [ -n "$branch" ]; then
    printf 'Contesto dinamico: branch corrente %s.\n' "$branch"
  else
    printf 'Contesto dinamico: nessun branch nominato attivo.\n'
  fi
else
  printf 'Contesto dinamico: branch non disponibile.\n'
fi

Lo script restituisce un orientamento, non la garanzia che quel branch sia pulito o pronto per un merge. Anche il nome del branch può contenere informazioni riservate: nel progetto reale usa nomi che non riportino dati personali e valuta se sia necessario inserirlo nel contesto del modello.

La registrazione seguente seleziona la ripresa dopo compaction. Integra il blocco nei settings del progetto e richiama lo script nel percorso dichiarato. Reinserimento del contesto.

{
  "hooks": {
    "SessionStart": [
      {
        "matcher": "compact",
        "hooks": [
          {
            "type": "command",
            "command": "sh \"$CLAUDE_PROJECT_DIR/.claude/hooks/session_context.sh\""
          }
        ]
      }
    ]
  }
}

Startup, resume e compact: quando usare ciascun filtro?

Un’informazione necessaria a ogni avvio può essere associata al motivo appropriato o a un matcher più ampio. Un orientamento richiesto soltanto dopo compaction può usare compact. La reference elenca i motivi supportati e il campo su cui il matcher opera; la scelta va confrontata con la sessione e la versione del lettore. Matcher SessionStart.

Non duplicare lo stesso output in più handler senza ragione. Le configurazioni possono essere distribuite fra scope utente, progetto e locale: una copia personale dello script e una copia condivisa possono produrre due messaggi identici. In /hooks controlla quali registrazioni sono effettivamente presenti.

La prova utile include avvio nuovo, ripresa e compaction pertinente. Non basta vedere il messaggio una volta: se il requisito riguarda compact, devi osservare quel percorso. Quando il hook non compare o parte al momento sbagliato, debug dei Hooks aiuta a controllare il filtro prima di cambiare lo script.

Che cosa sono PreCompact e PostCompact?

Gli eventi legati direttamente alla compaction hanno un contratto distinto da SessionStart. Possono essere utili per reagire prima o dopo il passaggio, ma non sono un invito a stampare automaticamente l’intero transcript. La reference descrive quali dati ed esiti sono supportati da ogni evento. PreCompact e PostCompact.

La scelta dipende dall’effetto. Se vuoi un dato dinamico al momento di riprendere il lavoro, SessionStart può essere sufficiente. Se devi osservare il passaggio di compaction per un processo locale, usa l’evento corrispondente e un handler compatibile. Non presumere che un JSON di risposta valido per un evento abbia la stessa funzione in un altro.

Un messaggio prima della compaction non è automaticamente memoria persistente. Se il fatto deve sopravvivere, salvalo nel documento adatto con una procedura esplicita. Non eseguire salvataggi indiscriminati dei dati della conversazione: spesso contengono informazioni che non devono essere replicate in altri file o servizi.

Come limitare l’output senza perdere informazioni importanti?

Parti dalla domanda che il messaggio deve risolvere: “Dove leggo lo stato del task?” oppure “Quale branch è attivo?”. Se bastano due righe, non aggiungere un elenco di tutti i file del repository. Un riferimento a un documento aggiornato consente una lettura mirata; una copia lunga può diventare obsoleta appena riprende il lavoro.

Per misurare il volume, salva l’output sintetico in un file di prova e conta caratteri o parole. Questo misura quanto testo aggiunge lo script, non quanti token verranno fatturati né il risparmio del processo. I costi dipendono dall’uso complessivo; la documentazione non offre una percentuale universale di riduzione attraverso un hook. Gestione dei costi.

Chi vuole osservare il contesto può leggere Token Weather. La visualizzazione riguarda indicatori della finestra di contesto e soglie: non deve essere usata per dedurre che le istruzioni siano corrette o che tutte le informazioni del task siano state conservate.

Come usare CLAUDE_ENV_FILE con un confine chiaro?

CLAUDE_ENV_FILE è un percorso fornito per rendere disponibili variabili alle successive operazioni Bash della sessione, secondo il contratto documentato. Non significa modificare permanentemente il profilo della shell personale. Il suo utilizzo va separato dall’output che diventa contesto per Claude. Persistenza delle variabili di sessione.

Non stampare tutte le variabili per capire se il meccanismo funziona. Potrebbero contenere segreti o credenziali. Se il progetto ha bisogno di una variabile non sensibile, definiscine il nome, il valore consentito e il punto in cui deve essere disponibile. Usa una lista esplicita invece di copiare l’ambiente del computer.

Anche la scrittura in un file di ambiente richiede quoting corretto. Un valore proveniente da un file del progetto non deve essere eseguito come shell arbitraria. Quando il requisito riguarda davvero bootstrap e prerequisiti, valuta se un comando di setup dedicato sia più chiaro del lavoro ripetuto a ogni SessionStart.

Due riprese di lavoro in aziende italiane

Esempio ipotetico, non testato: un’agenzia digitale di Genova sviluppa un portale con più branch attive. Dopo compaction vuole che Claude legga la checklist della richiesta corrente, invece di ricostruirla dal nome dei file. Il hook inserisce il branch e il riferimento al documento del task. La checklist distingue verifiche concluse e attività pendenti; nuovi edit possono rendere superata una prova precedente e vanno annotati.

Esempio ipotetico, non testato: una PMI di Vicenza lavora su un importatore per dati di magazzino sintetici. Alcune operazioni richiedono un servizio locale, altre no. Il team conserva nel task quali prove richiedono il servizio e quale ambiente è attivo. SessionStart aggiunge un orientamento breve; non stampa configurazioni, password o il dataset. Alla ripresa l’agente sa dove leggere i prerequisiti, senza ricevere l’intero archivio.

La differenza fra i casi è il dato dinamico utile: nel primo branch e richiesta, nel secondo ambiente e prove disponibili. Non esiste un messaggio universale da copiare in tutte le aziende. La ripresa deve seguire la struttura del processo che il team ha scelto.

Quali errori rendono il contesto incoerente?

Il più comune è usare due fonti di verità: un documento e uno script che descrivono lo stesso stato con parole diverse. Altri sono copiare risultati precedenti come attuali, stampare grandi log, confondere output di contesto e variabili di ambiente, e attribuire a un hook un blocco tecnico che non possiede.

Una prova di ripresa con informazioni contraddittorie

In un repository sintetico prepara una checklist che indica un test pendente e un output di prova precedente. Dopo la ripresa verifica che il messaggio del hook non trasformi il test pendente in un esito positivo. Il documento deve conservare chiaramente provenienza e stato delle informazioni.

Se il flusso usa agenti, Hooks per subagent e team aggiunge il problema della responsabilità: ciascuno deve sapere quali file di stato può aggiornare. Per la conclusione, Stop hook senza loop descrive come chiedere una verifica finita senza fare della memoria incompleta una richiesta infinita di continuare.

Quando un dato reinserito diventa obsoleto?

Il branch letto alla ripresa può cambiare più avanti nella stessa sessione. Un riferimento al task può restare corretto mentre il suo contenuto viene aggiornato. Il messaggio del hook descrive il momento in cui è stato prodotto: non è un flusso continuo di sincronizzazione.

Indica quindi la provenienza e non attribuire al testo una validità permanente. Quando la prossima decisione dipende da quel dato, rileggilo dalla fonte. SessionStart orienta il lavoro; Git e il documento del task restano i luoghi in cui verificare lo stato attuale.

Come adottare SessionStart senza appesantire il workflow?

Parti da un’informazione dinamica e da un percorso di ripresa. Prova il caso positivo, quello senza dato e quello in cui il comando fallisce. Controlla che il testo sia piccolo e che non replichi istruzioni già caricate. Aggiungi nuove informazioni soltanto se risolvono un’incertezza osservata, e conserva il motivo della scelta nel repository.

Mods di Claude può offrire interfacce per osservare lo stato della sessione, ma non serve introdurre un plugin per un orientamento di poche righe. La forma più semplice rimane utile quando produce dati corretti e ha un limite comprensibile.

Per progetti in cui agenti e persone condividono molti task, la progettazione di agenti AI può includere file di stato, responsabilità e controlli di ripresa. Il risultato da cercare è una continuazione consapevole: istruzioni stabili nel posto giusto, dati dinamici attuali e prove che conservano il loro significato.