31| Variabile | Descrizione |31| Variabile | Descrizione |
32| :- | :- |32| :- | :- |
33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il JWT della sessione, con prefisso `sk-ant-cc-`. Il suo claim `act` identifica il creatore della sessione, con l'email del creatore quando la superficie di creazione l'ha registrata. Il valore è il token al momento dello spawn; gli aggiornamenti arrivano sullo stdin del figlio, quindi un wrapper vede solo il valore iniziale. Consulta [Verify session identity](/docs/it/self-hosted-environments-identity). |33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il JWT della sessione, con prefisso `sk-ant-cc-`. Il suo claim `act` identifica il creatore della sessione, con l'email del creatore quando la superficie di creazione l'ha registrata. Il valore è il token al momento dello spawn; gli aggiornamenti arrivano sullo stdin del figlio, quindi un wrapper vede solo il valore iniziale. Consulta [Verify session identity](/docs/it/self-hosted-environments-identity). |
34| `CCR_SESSION_ACCOUNT_EMAIL` | L'email del creatore della sessione, pre-estratta dal runner dal claim `act.email` del token senza verifica della firma. Adatta per l'etichettatura, come i trailer dei commit. Quando l'email controlla il rilascio delle credenziali, verifica il token e leggi il claim da esso; consulta [Provision credentials scoped to the session creator](#provision-credentials-scoped-to-the-session-creator). Non impostata quando il token non contiene un'email del creatore. Trattala come informazione personale identificabile. |34| `CCR_SESSION_ACCOUNT_EMAIL` | L'email del creatore della sessione, pre-estratta dal runner dal claim `act.email` del token senza verifica della firma. Adatta per l'etichettatura, come i trailer dei commit. Quando l'email controlla il rilascio delle credenziali, verifica il token e leggi il claim da esso. Consulta [Provision credentials scoped to the session creator](#provision-credentials-scoped-to-the-session-creator). Non impostata quando il token non contiene un'email del creatore, ad esempio nelle sessioni create dall'identità di servizio della tua organizzazione. Trattala come informazione personale identificabile. |
35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` o `scheduled_trigger`. Anthropic registra il valore una volta alla creazione della sessione, quindi il wrapper e ogni hook del ciclo di vita vedono lo stesso valore. Usala solo per l'analisi dell'adozione e l'etichettatura, non come segnale di autorizzazione. Non impostata quando la sessione non ha una superficie registrata o riconosciuta, quindi fai riferimento ad essa come `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sotto `set -u`. Richiede Claude Code v2.1.229 o successivo. |35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` o `scheduled_trigger`. Anthropic registra il valore una volta alla creazione della sessione, quindi il wrapper e ogni hook del ciclo di vita vedono lo stesso valore. Usala solo per l'analisi dell'adozione e l'etichettatura, non come segnale di autorizzazione. Non impostata quando la sessione non ha una superficie registrata o riconosciuta. Richiede Claude Code v2.1.229 o successivo. |
36| `CLAUDE_RUNNER_CLAUDE_BIN` | Percorso assoluto al binario Claude Code del runner stesso. Termina il wrapper con `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` per passare il controllo al binario bloccato senza hardcodificare un percorso di installazione. |36| `CLAUDE_RUNNER_CLAUDE_BIN` | Percorso assoluto al binario Claude Code del runner stesso. Termina il wrapper con `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` per passare il controllo al binario bloccato senza hardcodificare un percorso di installazione. |
37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID sessione nel formato taggato `cse_...`. Questa è la stessa sessione che gli [hook del ciclo di vita](#lifecycle-hooks) vedono come `CLAUDE_RUNNER_SESSION_ID` nel formato `session_...`; le variabili UUID corrispondono in entrambi, e sostituire il prefisso `cse_` con `session_` produce l'ID mostrato nell'URL della sessione. |37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID sessione nel formato taggato `cse_...`. Questa è la stessa sessione che gli [hook del ciclo di vita](#lifecycle-hooks) vedono come `CLAUDE_RUNNER_SESSION_ID` nel formato `session_...`; le variabili UUID corrispondono in entrambi, e sostituire il prefisso `cse_` con `session_` produce l'ID mostrato nell'URL della sessione. |
38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | Lo stesso ID sessione nel formato UUID canonico, per i sistemi che si basano su UUID. |38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | Lo stesso ID sessione nel formato UUID canonico, per i sistemi che si basano su UUID. |
39| `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` | Per una sessione [Claude Tag](https://claude.com/docs/claude-tag/overview) che appartiene a un thread Slack, il link a quel thread. Non impostata per le altre sessioni, e può non essere impostata anche per una sessione di thread. |
40| `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` | Per una sessione Claude Tag che appartiene a un thread Slack, il timestamp Slack di quel thread, come `1700000000.000100`. Può non essere impostata, e può essere impostata quando `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` non lo è, quindi controlla ciascuna variabile separatamente. |
39| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Percorso assoluto a un file per sessione che contiene il JWT della sessione corrente, mantenuto aggiornato negli aggiornamenti dei token. I sottoprocessi della shell lo leggono per il loro header `Authorization` quando scaricano gli allegati che l'utente ha aggiunto alla sessione. `exec` preserva la variabile automaticamente; un wrapper che ricostruisce l'ambiente del figlio deve riportare la variabile, altrimenti i download degli allegati smettono di funzionare silenziosamente. |41| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Percorso assoluto a un file per sessione che contiene il JWT della sessione corrente, mantenuto aggiornato negli aggiornamenti dei token. I sottoprocessi della shell lo leggono per il loro header `Authorization` quando scaricano gli allegati che l'utente ha aggiunto alla sessione. `exec` preserva la variabile automaticamente; un wrapper che ricostruisce l'ambiente del figlio deve riportare la variabile, altrimenti i download degli allegati smettono di funzionare silenziosamente. |
40| `CLAUDE_CONFIG_DIR` | Directory di configurazione Claude per sessione, scritta all'inizio della sessione dallo snapshot della configurazione dell'host del runner che il runner acquisisce all'avvio; consulta [Permissions and tool approval](#permissions-and-tool-approval). Le scritture qui sono isolate a questa sessione. La directory rimane sotto `<base-dir>/_sessions/` dopo la fine della sessione a meno che tu non avvii il runner con [`--remove-session-state`](/docs/it/self-hosted-environments-reference#runner-cli-flags); consulta [Reuse a pre-warmed checkout](/docs/it/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout). |42| `CLAUDE_CONFIG_DIR` | Directory di configurazione Claude per sessione, scritta all'inizio della sessione dallo snapshot della configurazione dell'host del runner che il runner acquisisce all'avvio; consulta [Permissions and tool approval](#permissions-and-tool-approval). Le scritture qui sono isolate a questa sessione. La directory rimane sotto `<base-dir>/_sessions/` dopo la fine della sessione a meno che tu non avvii il runner con [`--remove-session-state`](/docs/it/self-hosted-environments-reference#runner-cli-flags); consulta [Reuse a pre-warmed checkout](/docs/it/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout). |
41| `ANTHROPIC_BASE_URL` | L'URL di base dell'API che il figlio utilizzerà, fornito dal piano di controllo per sessione e normalmente `https://api.anthropic.com`. Non sovrascriverlo: la credenziale di inferenza della sessione è un token OAuth emesso da Anthropic che altri provider non accettano. |43| `ANTHROPIC_BASE_URL` | L'URL di base dell'API che il figlio utilizzerà, fornito dal piano di controllo per sessione e normalmente `https://api.anthropic.com`. Non sovrascriverlo: la credenziale di inferenza della sessione è un token OAuth emesso da Anthropic che altri provider non accettano. |
43 45
44Il wrapper eredita anche il resto dell'ambiente gestito del figlio, incluse tutte le variabili d'ambiente fornite dal server. `exec` le propaga tutte automaticamente; se il tuo wrapper avvia il figlio in un altro modo, inoltra l'ambiente completo.46Il wrapper eredita anche il resto dell'ambiente gestito del figlio, incluse tutte le variabili d'ambiente fornite dal server. `exec` le propaga tutte automaticamente; se il tuo wrapper avvia il figlio in un altro modo, inoltra l'ambiente completo.
45 47
48`CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` e `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` raggiungono il tuo wrapper o l'[hook `command`](#command). Raggiungono anche ciò che la sessione esegue, come i comandi della shell, gli hook di git e gli hook di Claude Code. Gli hook `checkout`, `post-session` e `spawn-runner` non le ricevono.
49
50<h3 id="give-a-default-to-variables-that-can-be-unset">
51 Assegnare un valore predefinito alle variabili che possono non essere impostate
52</h3>
53
54`CCR_SESSION_ACCOUNT_EMAIL`, `CLAUDE_RUNNER_CLIENT_PLATFORM`, `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` e `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` possono ciascuna non essere impostate. Se il tuo script usa `set -u`, Bash si arresta con `unbound variable` quando espande una di esse non impostata, quindi espandile con un valore predefinito, come `${CCR_SESSION_ACCOUNT_EMAIL:-}`.
55
56Ovunque una shell espanda il link del thread Slack, adotta queste precauzioni:
57
58* **Mettilo tra virgolette**: il link può contenere caratteri che la shell interpreta, come `?` e `&`, quindi metti la variabile tra virgolette, come in `"${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}"`.
59* **Tieni il suo valore fuori dalle stringhe di `eval` e `sh -c`**: non sostituire il suo valore in una stringa eseguita da `eval` o `sh -c`, nemmeno tra virgolette. Fai invece in modo che quella stringa faccia riferimento alla variabile.
60
46<h3 id="keep-stdin-and-file-descriptor-3-attached">61<h3 id="keep-stdin-and-file-descriptor-3-attached">
47 Mantenere stdin e il descrittore di file 3 collegati62 Mantenere stdin e il descrittore di file 3 collegati
48</h3>63</h3>
49 64
50Lo stdin del figlio è il canale di controllo del runner. Le rotazioni dei token e i segnali di fine sessione arrivano su di esso. Il runner apre anche una pipe sul descrittore di file 3 e legge da essa i segnali di attività del figlio per gestire i timeout di inattività e di avvio. Un semplice `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` preserva entrambi automaticamente.65Lo stdin del figlio è il canale di controllo del runner. Le rotazioni dei token e i segnali di fine sessione arrivano su di esso. Il runner apre anche una pipe sul descrittore di file 3 e legge da essa i segnali di attività del figlio per gestire i timeout di inattività e di avvio. Un semplice `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` preserva entrambi automaticamente.
51 66
52Se il tuo wrapper mette in background il figlio con un semplice `&`, interrompe lo stdin del figlio: la sessione sembra sana fino a quando non scade la durata di circa 30 minuti del token OAuth iniziale, dopodiché ogni chiamata API fallisce con `401 authentication_error`. Se il tuo wrapper deve mettere in background il figlio, ad esempio per mantenere attivo un trap di teardown, salva stdin sul descrittore di file 4 o superiore e ricollegalo esplicitamente:67Se il tuo wrapper mette in background il figlio con un semplice `&`, interrompe lo stdin del figlio. La sessione sembra sana fino a quando non scade la durata di circa 30 minuti del token OAuth iniziale, dopodiché ogni chiamata API che usa il token fallisce con `401 authentication_error`. Se il tuo wrapper deve mettere in background il figlio, ad esempio per mantenere attivo un trap di teardown, salva stdin sul descrittore di file 4 o superiore e ricollegalo esplicitamente:
53 68
54```bash theme={null}69```bash theme={null}
55exec 4<&070exec 4<&0
59wait "$CHILD"74wait "$CHILD"
60```75```
61 76
62Non chiudere né riutilizzare il descrittore di file 3 nel wrapper. Reindirizzare lo stdout e lo stderr del figlio va bene.77Puoi reindirizzare lo stdout del figlio. Mantieni il descrittore di file 3 e lo stderr collegati al runner:
78
79* **Descrittore di file 3**: trasporta i segnali di attività del figlio al runner. Non chiuderlo né riutilizzarlo nel wrapper.
80* **stderr**: quando il wrapper o il figlio esce con codice diverso da zero, il runner pubblica le ultime righe dello stderr nella sessione e le stampa nel proprio log. L'utente della sessione vede quelle righe, quindi non stampare segreti sullo stderr e rimuovi `set -x` prima di distribuire il wrapper. Se reindirizzi lo stderr, le sessioni vengono comunque eseguite, ma il runner segnala un errore con il solo codice di uscita.
63 81
64<h3 id="pass-the-system-prompt-flags-through">82<h3 id="pass-the-system-prompt-flags-through">
65 Passare i flag del prompt di sistema83 Passare i flag del prompt di sistema
108 checkout126 checkout
109</h3>127</h3>
110 128
111Viene eseguito una volta per repository, al posto del clone e del fetch integrati del runner. Usa l'hook per clonare da un mirror read-through, popolare un albero di lavoro da un archivio o applicare l'autenticazione git per sessione. Il runner imposta queste variabili, e può impostare altre variabili `CLAUDE_RUNNER_` che la tabella non elenca:129Viene eseguito una volta per repository, al posto del clone e del fetch integrati del runner. Usa l'hook per clonare da un mirror read-through che raggiungi tramite HTTPS o SSH, popolare un albero di lavoro da un archivio o applicare l'autenticazione git per sessione. Il runner imposta queste variabili, e può impostare altre variabili `CLAUDE_RUNNER_` che la tabella non elenca:
112 130
113| Variabile | Descrizione |131| Variabile | Descrizione |
114| :- | :- |132| :- | :- |
115| `CLAUDE_RUNNER_REPO_URL` | URL del repository da clonare, dopo che `--git-host-rewrite` e `--git-ssh-rewrite` sono stati applicati |133| `CLAUDE_RUNNER_REPO_URL` | URL del repository da clonare, dopo che `--git-host-rewrite` e `--git-ssh-rewrite` sono stati applicati |
116| `CLAUDE_RUNNER_REPO_REF` | Revisione da controllare: ramo, tag o commit SHA come la sessione lo ha richiesto. Vuoto significa il ramo predefinito del repository. |134| `CLAUDE_RUNNER_REPO_REF` | Revisione di cui eseguire il checkout, come richiesta dalla sessione: un branch, un tag, un commit SHA o un nome di riferimento completo come `refs/pull/<number>/head`. Vuoto indica il branch predefinito del repository. |
117| `CLAUDE_RUNNER_CHECKOUT_PATH` | Percorso assoluto dove l'albero di lavoro deve essere lasciato |135| `CLAUDE_RUNNER_CHECKOUT_PATH` | Percorso assoluto dove l'albero di lavoro deve essere lasciato |
118| `CLAUDE_RUNNER_SESSION_ID` | ID sessione nel modulo taggato `session_...`, per la registrazione e la correlazione |136| `CLAUDE_RUNNER_SESSION_ID` | ID sessione nel modulo taggato `session_...`, per la registrazione e la correlazione |
119| `CLAUDE_RUNNER_SESSION_UUID` | Lo stesso ID sessione nel modulo UUID canonico |137| `CLAUDE_RUNNER_SESSION_UUID` | Lo stesso ID sessione nel modulo UUID canonico |
120| `CLAUDE_RUNNER_API_BASE_URL` | URL di base dell'API Anthropic per le chiamate limitate alla sessione |138| `CLAUDE_RUNNER_API_BASE_URL` | URL di base dell'API Anthropic per le chiamate limitate alla sessione |
121| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app` o `ios`. Non impostato quando la sessione non ha una superficie registrata o riconosciuta. |139| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app` o `ios`. Non impostata quando la sessione non ha una superficie registrata o riconosciuta, quindi fai riferimento a essa come `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` con `set -u`. Richiede Claude Code v2.1.229 o successivo. |
122| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il token di accesso della sessione, per le chiamate API limitate alla sessione |140| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il token di accesso della sessione, per le chiamate API limitate alla sessione |
123| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Impostazioni git che il runner fissa per il git eseguito dal tuo hook. [Configurazione git all'interno degli hook del ciclo di vita](#git-configuration-inside-lifecycle-hooks) le descrive. Richiede Claude Code v2.1.280 o successivo. |141| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Impostazioni git che il runner fissa per il git eseguito dal tuo hook. [Configurazione git all'interno degli hook del ciclo di vita](#git-configuration-inside-lifecycle-hooks) le descrive. Richiede Claude Code v2.1.280 o successivo. |
124 142
125Lo script deve lasciare un albero di lavoro in `CLAUDE_RUNNER_CHECKOUT_PATH` controllato alla revisione richiesta. HEAD staccato va bene; il runner crea il ramo di lavoro della sessione in cima. Il runner verifica che il percorso contenga un `.git` in seguito; se l'hook materializza una fonte non-git come Perforce o un tarball scompattato, impostare `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` nell'ambiente del runner per saltare quel controllo. I flussi basati su Git come la creazione del ramo di lavoro e il push dei risultati richiedono un checkout git, quindi esportare i risultati da alberi non-git con un hook [`post-session`](#post-session).143Lo script deve lasciare in `CLAUDE_RUNNER_CHECKOUT_PATH` un albero di lavoro con il checkout della revisione richiesta. Un HEAD staccato va bene, perché il runner crea sopra di esso il branch di lavoro della sessione.
126 144
127Il runner non passa una credenziale git all'hook. Invece, coniare una credenziale di clone per sessione dall'identità della sessione: verificare `CLAUDE_CODE_SESSION_ACCESS_TOKEN` con una libreria JWT standard rispetto all'endpoint JWKS sotto `CLAUDE_RUNNER_API_BASE_URL`, come descritto in [Verify the token from your service](/docs/it/self-hosted-environments-identity#verify-the-token-from-your-service), quindi fare in modo che il servizio di credenziale emetta una credenziale di clone di breve durata per l'identità nel claim `act` del token. `CLAUDE_RUNNER_CLAUDE_BIN` non è impostato nell'ambiente dell'hook di checkout, quindi il subcomando `decode-token` non è disponibile qui. Ricadere in qualsiasi autenticazione git che l'host ha già, come un agente SSH, un helper di credenziale o `.netrc`, è anche un'opzione.145Dopo che il tuo hook termina, il runner verifica che `CLAUDE_RUNNER_CHECKOUT_PATH` contenga un `.git`. Se il tuo hook materializza una sorgente non git come Perforce o un tarball scompattato, imposta `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` nell'ambiente del runner per saltare quel controllo. I flussi basati su git come la creazione del branch di lavoro e il push dei risultati richiedono un checkout git, quindi esporta i risultati da alberi non git con un [hook `post-session`](#post-session).
128 146
129Quando l'hook esce con codice diverso da zero, o esce 0 senza lasciare un checkout utilizzabile dietro, ciò che il runner fa dipende dal repository:147<h4 id="get-git-credentials-in-the-hook">
148 Ottenere le credenziali git nell'hook
149</h4>
130 150
131* **Un repository a cui la sessione spinge i risultati**: il runner fallisce la sessione e su un'uscita diversa da zero mostra la coda dello stderr dello script all'utente.151Il runner non passa una credenziale git all'hook. Nemmeno il sottocomando `decode-token` è disponibile qui, perché `CLAUDE_RUNNER_CLAUDE_BIN` non è impostato nell'ambiente dell'hook di checkout. Genera invece una credenziale di clone per sessione a partire dall'identità della sessione, oppure ricorri all'autenticazione git dell'host stesso:
132* **Un repository che la sessione legge solo**, come un repository aggiunto a una sessione in esecuzione: il runner registra una riga `[runner:warn]` con il dettaglio del fallimento, pubblica un passo `Skipped` alla sessione, rimuove ciò che l'hook ha lasciato al percorso di checkout e continua con i repository rimanenti. Quando il runner non può rimuovere il percorso immediatamente, ritenta la rimozione alla fine della sessione. Se saltare lascia la sessione senza alcun repository, il runner fallisce comunque la sessione.
133 152
134Prima della v2.1.228, il runner falliva la sessione su un fallimento dell'hook per qualsiasi repository, quindi un repository di sola lettura che l'hook non poteva servire falliva di nuovo la sessione su ogni nuovo runner su cui la sessione riprendeva.153* **Credenziale di clone per sessione**: verifica `CLAUDE_CODE_SESSION_ACCESS_TOKEN` con una libreria JWT standard rispetto all'endpoint JWKS sotto `CLAUDE_RUNNER_API_BASE_URL`, come descritto in [Verify the token from your service](/docs/it/self-hosted-environments-identity#verify-the-token-from-your-service). Poi fai in modo che il tuo servizio di credenziali emetta una credenziale di clone di breve durata per l'identità nel claim `act` del token. Associa quella credenziale a `act.sub` e non richiedere `act.email`.
154* **Autenticazione git dell'host**: usa qualsiasi autenticazione git di cui l'host dispone già, come un agente SSH, un credential helper o `.netrc`.
135 155
136Il runner rimuove il percorso di checkout dopo la fine della sessione.156<h4 id="when-the-hook-fails">
157 Quando l'hook fallisce
158</h4>
159
160L'hook fallisce quando esce con un codice diverso da zero, o esce con 0 senza lasciare un checkout utilizzabile:
161
162* **Un repository a cui la sessione spinge i risultati**: il runner fallisce la sessione e su un'uscita diversa da zero mostra la coda dello stderr dello script all'utente.
163* **Un repository che la sessione legge soltanto**, come un repository aggiunto a una sessione in esecuzione: il runner registra una riga `[runner:warn]` con il dettaglio del fallimento, pubblica un passaggio `Skipped` nella sessione, rimuove ciò che l'hook ha lasciato nel percorso di checkout e continua con i repository rimanenti. Se saltarlo lascia la sessione senza alcun repository, il runner fa comunque fallire la sessione.
164
165Quando l'hook ha successo, il runner rimuove il percorso di checkout dopo la fine della sessione.
137 166
138<h3 id="post-session">167<h3 id="post-session">
139 post-session168 post-session
151| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Percorsi assoluti separati da due punti degli alberi di lavoro della sessione. Vuoto per sessioni senza repository. |180| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Percorsi assoluti separati da due punti degli alberi di lavoro della sessione. Vuoto per sessioni senza repository. |
152| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | Percorso al log di debug della sessione, ancora su disco mentre l'hook viene eseguito |181| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | Percorso al log di debug della sessione, ancora su disco mentre l'hook viene eseguito |
153| `CLAUDE_RUNNER_API_BASE_URL` | URL di base dell'API Anthropic per le chiamate limitate alla sessione |182| `CLAUDE_RUNNER_API_BASE_URL` | URL di base dell'API Anthropic per le chiamate limitate alla sessione |
154| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app` o `ios`. Non impostato quando la sessione non ha una superficie registrata o riconosciuta. Richiede Claude Code v2.1.229 o successivo. |183| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app` o `ios`. Non impostata quando la sessione non ha una superficie registrata o riconosciuta, quindi fai riferimento a essa come `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` con `set -u`. Richiede Claude Code v2.1.229 o successivo. |
155| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il token di accesso della sessione, per le chiamate API limitate alla sessione |184| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Il token di accesso della sessione, per le chiamate API limitate alla sessione |
156| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Impostazioni git che il runner fissa per il git eseguito dal tuo hook. [Configurazione git all'interno degli hook del ciclo di vita](#git-configuration-inside-lifecycle-hooks) le descrive. Richiede Claude Code v2.1.280 o successivo. |185| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Impostazioni git che il runner fissa per il git eseguito dal tuo hook. [Configurazione git all'interno degli hook del ciclo di vita](#git-configuration-inside-lifecycle-hooks) le descrive. Richiede Claude Code v2.1.280 o successivo. |
157 186
158`CLAUDE_RUNNER_EXIT_REASON` assume uno di quattro valori:187`CLAUDE_RUNNER_EXIT_REASON` assume uno di quattro valori:
159 188
160* `completed`: la sessione è terminata in modo pulito. Il processo Claude Code è uscito normalmente, oppure la sessione è stata archiviata o eliminata mentre era ancora in esecuzione.189* `completed`: la sessione è terminata in modo pulito. Il processo Claude Code è uscito normalmente, oppure è uscito da solo dopo che la sessione è stata archiviata o eliminata.
161* `failed`: il processo Claude Code è andato in crash, oppure la configurazione è fallita dopo l'avvio.190* `failed`: il processo Claude Code è andato in crash, oppure la configurazione è fallita dopo l'avvio.
162* `interrupted`: il runner ha interrotto la sessione. Ha rilasciato la sessione per liberare lo slot, la sessione è scaduta all'avvio, il server ha spostato la sessione da questo runner, il runner era in drenaggio, oppure la sessione ha superato il limite [`--kill-session-after-min`](/docs/it/self-hosted-environments-reference#runner-cli-flags).191* `interrupted`: il runner ha interrotto la sessione, in uno di questi casi:
192 * Il runner ha rilasciato la sessione per liberare lo slot.
193 * La sessione è andata in timeout all'avvio.
194 * Il server ha spostato la sessione da questo runner.
195 * Il polling del runner ha rilevato un'archiviazione o un'eliminazione prima che il processo uscisse.
196 * Il runner era in fase di drain.
197 * La sessione ha superato il limite [`--kill-session-after-min`](/docs/it/self-hosted-environments-reference#runner-cli-flags).
163* `abandoned`: riservato per una sessione che un altro runner ha rivendicato. L'hook attualmente non si attiva in quel caso.198* `abandoned`: riservato per una sessione che un altro runner ha rivendicato. L'hook attualmente non si attiva in quel caso.
164 199
165I [contatori del ciclo di vita della sessione](/docs/it/self-hosted-environments-reference#session-lifecycle-counter-semantics) contano un rilascio, un timeout di avvio e uno spostamento del server come `completed` piuttosto che `interrupted`, perché il runner ha restituito lo slot in modo pulito. Aspettati quella differenza se confronti le ricevute dell'hook con i contatori.200Se confronti le ricevute dell'hook con i [contatori del ciclo di vita della sessione](/docs/it/self-hosted-environments-reference#session-lifecycle-counter-semantics), aspettati che alcune ricevute `interrupted` vengano contate lì come `completed`. I contatori contano come `completed` un rilascio, un timeout all'avvio, uno spostamento da parte del server e un'archiviazione o eliminazione rilevata per prima dal polling del runner, perché il runner ha restituito lo slot in modo pulito.
166 201
167Lo stato di uscita dell'hook non influisce mai sul risultato della sessione; un fallimento viene registrato e ignorato. Il runner attende fino a `--post-session-hook-timeout-sec`, 60 secondi per impostazione predefinita, ad ogni fine sessione incluso l'arresto del runner. Questo esempio salva il lavoro non committato in un ramo di salvataggio:202Lo stato di uscita dell'hook non influisce mai sul risultato della sessione; un fallimento viene registrato e ignorato. Il runner attende fino a `--post-session-hook-timeout-sec`, 60 secondi per impostazione predefinita, ad ogni fine sessione incluso l'arresto del runner. Questo esempio salva il lavoro non committato in un ramo di salvataggio:
168 203
169```bash theme={null}204```bash theme={null}
170#!/usr/bin/env bash205#!/usr/bin/env bash
171set -u206set -u
207export GIT_ALLOW_PROTOCOL=${GIT_ALLOW_PROTOCOL:-https:http:ssh}
172IFS=':'208IFS=':'
173# -c overrides beat repo-local settings, blocking session-written fsmonitor,209# -c overrides beat repo-local settings, blocking session-written fsmonitor,
174# hook-path, and gpg-program config from executing code with the hook's210# hook-path, and gpg-program config from executing code with the hook's
175# privileges. -c commit.gpgsign=false also leaves these rescue commits211# privileges. -c commit.gpgsign=false also leaves these rescue commits
176# unsigned under --configure-git.212# unsigned under --configure-git.
177# Repo-local credential.helper and pushurl still apply, and on a runner213# Repo-local credential.helper and pushurl still apply, and on a runner
178# before v2.1.280 so does core.sshCommand; if the hook holds credentials214# before v2.1.280 so does core.sshCommand; see the note below the script
179# the session didn't, see the note below the script.215# before you give this push a credential.
180g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \216g() { git -c core.fsmonitor=false -c core.hooksPath=/dev/null \
181 -c commit.gpgsign=false "$@"; }217 -c commit.gpgsign=false "$@"; }
182for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do218for ws in $CLAUDE_RUNNER_WORKSPACE_PATHS; do
188done224done
189```225```
190 226
191L'hook esegue il push con le credenziali git disponibili nel proprio ambiente sull'host del runner. Con l'[approccio senza credenziali nell'immagine](/docs/it/self-hosted-environments-deploy#configure-git), anche quando il clone integrato passa attraverso il proxy git di Anthropic, non ce ne sono, quindi genera una credenziale di push di breve durata all'interno dell'hook prima del push: scambia il token della sessione che l'hook riceve in `CLAUDE_CODE_SESSION_ACCESS_TOKEN` con il tuo servizio di token, verificandolo come descritto in [Verificare l'identità della sessione](/docs/it/self-hosted-environments-identity). Quando l'hook dispone di una credenziale che la sessione non aveva, sostituisci `origin` con un URL fornito dall'operatore e passa `-c credential.helper=` insieme al tuo helper. [Configurazione git all'interno degli hook del ciclo di vita](#git-configuration-inside-lifecycle-hooks) descrive su cosa può ancora influire la configurazione scritta dalla sessione.227La riga `GIT_ALLOW_PROTOCOL` nello script limita git ai remote HTTPS, HTTP e SSH. Se l'ambiente del runner imposta già un proprio elenco `GIT_ALLOW_PROTOCOL` non vuoto, lo script mantiene quell'elenco.
228
229L'hook esegue il push con le credenziali git disponibili nel proprio ambiente sull'host del runner. Con l'[approccio senza credenziali nell'immagine](/docs/it/self-hosted-environments-deploy#configure-git), anche quando il clone integrato passa attraverso il proxy git di Anthropic, non ce ne sono, quindi genera una credenziale di push di breve durata all'interno dell'hook prima del push: scambia il token della sessione che l'hook riceve in `CLAUDE_CODE_SESSION_ACCESS_TOKEN` con il tuo servizio di token, verificandolo come descritto in [Verificare l'identità della sessione](/docs/it/self-hosted-environments-identity).
230
231Tratta qualsiasi credenziale che il tuo hook fornisce a git come una credenziale che una sessione può ottenere, e generala in modo che non possa fare nulla di più di questo push. Il git nel tuo hook legge file di configurazione che una sessione può scrivere, e un credential helper o un filter driver indicato in uno di essi viene eseguito con i privilegi del tuo hook. Le impostazioni in quei file possono anche cambiare la destinazione di un push, qualunque remote tu indichi. Per le impostazioni git che il runner fissa nel tuo hook e quelle che lascia a quei file, consulta [Configurazione git all'interno degli hook del ciclo di vita](#git-configuration-inside-lifecycle-hooks).
192 232
193<h4 id="hook-timing-when-the-runner-releases-a-session">233<h4 id="hook-timing-when-the-runner-releases-a-session">
194 Hook timing quando il runner rilascia una sessione234 Hook timing quando il runner rilascia una sessione
264| `CLAUDE_RUNNER_ORDER_ID` | Chiave di idempotenza opaca, unica per richiesta di spawn e sicura per i nomi delle risorse Kubernetes. Utilizzarla come chiave di dedup del provisioner. |304| `CLAUDE_RUNNER_ORDER_ID` | Chiave di idempotenza opaca, unica per richiesta di spawn e sicura per i nomi delle risorse Kubernetes. Utilizzarla come chiave di dedup del provisioner. |
265| `CLAUDE_RUNNER_SESSION_ID` | La sessione per cui è questa richiesta. Si ripete su ogni richiesta per la sessione, quindi utilizzarla per la registrazione e l'instradamento, non come chiave di dedup. Vuoto per le richieste di pre-warming, che avviano un runner standby prima di qualsiasi sessione specifica quando [`--min-idle`](/docs/it/self-hosted-environments-reference#orchestrator-cli-flags) è impostato, quindi non assumere che la variabile sia impostata. |305| `CLAUDE_RUNNER_SESSION_ID` | La sessione per cui è questa richiesta. Si ripete su ogni richiesta per la sessione, quindi utilizzarla per la registrazione e l'instradamento, non come chiave di dedup. Vuoto per le richieste di pre-warming, che avviano un runner standby prima di qualsiasi sessione specifica quando [`--min-idle`](/docs/it/self-hosted-environments-reference#orchestrator-cli-flags) è impostato, quindi non assumere che la variabile sia impostata. |
266| `CLAUDE_RUNNER_SESSION_UUID` | Lo stesso ID sessione nel modulo UUID canonico. Vuoto per le richieste di pre-warming. |306| `CLAUDE_RUNNER_SESSION_UUID` | Lo stesso ID sessione nel modulo UUID canonico. Vuoto per le richieste di pre-warming. |
267| `CLAUDE_RUNNER_ATTEMPT` | Quante richieste di spawn questa sessione ha avuto. `0` per le richieste di pre-warming. |307| `CLAUDE_RUNNER_ATTEMPT` | Un contatore per sessione da usare per i log. Non è un conteggio dei nuovi tentativi né delle richieste. `0` per le richieste di pre-warming, anche se pure una richiesta per una sessione può riportare `0`. |
268| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Ora del server dalla risposta del poll header HTTP `Date`. Quando l'hook verifica l'`exp` del JWT dell'ordine di lavoro, confrontare rispetto a questo valore invece dell'orologio locale per tollerare lo skew. Vuoto quando il gateway ha omesso l'header. |308| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Ora del server dalla risposta del poll header HTTP `Date`. Quando l'hook verifica l'`exp` del JWT dell'ordine di lavoro, confrontare rispetto a questo valore invece dell'orologio locale per tollerare lo skew. Vuoto quando il gateway ha omesso l'header. |
269| `CLAUDE_RUNNER_POOL_ID` | L'ID dell'ambiente a cui il nuovo runner dovrebbe unirsi, nel modulo `ccpool_...` |309| `CLAUDE_RUNNER_POOL_ID` | L'ID dell'ambiente a cui il nuovo runner dovrebbe unirsi, nel modulo `ccpool_...` |
270| `CLAUDE_RUNNER_ACCOUNT_ID` | ID taggato dell'account che ha accodato la sessione, per l'instradamento per account, la quota o il chargeback. Vuoto quando non disponibile, e sempre vuoto per le sessioni del canale Claude Tag, che nessun account accoda. |310| `CLAUDE_RUNNER_ACCOUNT_ID` | ID taggato dell'account che ha accodato la sessione, per l'instradamento per account, la quota o il chargeback. Vuoto quando non disponibile, e sempre vuoto per le sessioni del canale Claude Tag, che nessun account accoda. |
271| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email dell'account che ha accodato la sessione. Vuoto quando non disponibile. Trattare l'email come informazioni personali identificabili e non registrarla. |311| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email dell'account che ha accodato la sessione. Vuoto quando non disponibile. Trattare l'email come informazioni personali identificabili e non registrarla. |
272| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL della prima fonte git della sessione, per l'instradamento a un runner con quel repository pre-riscaldato. Vuoto quando la sessione non ha fonti git. |312| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL della prima fonte git della sessione, per l'instradamento a un runner con quel repository pre-riscaldato. Vuoto quando la sessione non ha fonti git. |
273| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Revisione della prima fonte git della sessione: ramo, SHA o tag. Vuoto quando non specificato. |313| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Revisione della prima fonte git della sessione: branch, SHA, tag o nome completo del riferimento. Vuoto quando non specificato. |
274| `CLAUDE_RUNNER_REPO_SOURCES` | Array JSON di `{url, revision}` per tutte le fonti git della sessione, per gli hook che instradano su un repository secondario. Vuoto quando non ci sono fonti. |314| `CLAUDE_RUNNER_REPO_SOURCES` | Array JSON di `{url, revision}` per tutte le fonti git della sessione, per gli hook che instradano su un repository secondario. Vuoto quando non ci sono fonti. |
275| `CLAUDE_RUNNER_CORRELATION_ID` | L'ID di correlazione fornito alla creazione della sessione, ripetuto in modo che l'hook possa mappare questo ordine di lavoro alla richiesta che ha creato la sessione. Vuoto quando la sessione non ne ha uno. |315| `CLAUDE_RUNNER_CORRELATION_ID` | L'ID di correlazione fornito alla creazione della sessione, ripetuto in modo che l'hook possa mappare questo ordine di lavoro alla richiesta che ha creato la sessione. Vuoto quando la sessione non ne ha uno. |
276| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app`, `ios` o `scheduled_trigger`, per l'analisi dell'adozione. Non impostato quando la sessione non ha una superficie registrata o riconosciuta, e per le richieste di pre-warming; controllarlo con `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, che rimane sicuro sotto `set -u`. |316| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La superficie client che ha creato la sessione, come `web_claude_ai`, `desktop_app`, `ios` o `scheduled_trigger`, per l'analisi dell'adozione. Non impostato quando la sessione non ha una superficie registrata o riconosciuta, e per le richieste di pre-warming; controllarlo con `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, che rimane sicuro sotto `set -u`. |
282* **Utilizzare `--capacity 1` sui runner generati**: un ordine di lavoro legato alla sessione registra esattamente un runner legato a quella sessione, quindi una capacità più alta aggiunge slot che non ricevono mai lavoro, e il runner registra un avviso all'avvio.322* **Utilizzare `--capacity 1` sui runner generati**: un ordine di lavoro legato alla sessione registra esattamente un runner legato a quella sessione, quindi una capacità più alta aggiunge slot che non ricevono mai lavoro, e il runner registra un avviso all'avvio.
283* **Gli ordini di lavoro di pre-warming si registrano non legati**: il runner standby non è legato a una sessione e rivendica il lavoro in coda come un runner di flotta fissa.323* **Gli ordini di lavoro di pre-warming si registrano non legati**: il runner standby non è legato a una sessione e rivendica il lavoro in coda come un runner di flotta fissa.
284 324
285Il contratto ha quattro regole agnostiche del provisioner:325Il contratto ha quattro regole, qualunque sia la piattaforma su cui il tuo hook esegue il provisioning:
286 326
2871. **Essere idempotenti su `CLAUDE_RUNNER_ORDER_ID`.** La rielaborazione della stessa richiesta deve generare al massimo un runner. Derivare un nome di risorsa deterministico dall'ID e lasciare che la propria piattaforma rifiuti il duplicato. Non chiave su `CLAUDE_RUNNER_SESSION_ID` invece. Ogni richiesta per una sessione porta lo stesso ID sessione con un nuovo ID ordine, quindi un carico di lavoro denominato o deduplicato dall'ID sessione viene creato una volta e mai più per quella sessione.3271. **Essere idempotenti su `CLAUDE_RUNNER_ORDER_ID`.** La rielaborazione della stessa richiesta deve generare al massimo un runner. Derivare un nome di risorsa deterministico dall'ID e lasciare che la propria piattaforma rifiuti il duplicato. Non chiave su `CLAUDE_RUNNER_SESSION_ID` invece. Ogni richiesta per una sessione porta lo stesso ID sessione con un nuovo ID ordine, quindi un carico di lavoro denominato o deduplicato dall'ID sessione viene creato una volta e mai più per quella sessione.
2882. **Non ritentare il carico di lavoro.** Un ID ordine significa al massimo un carico di lavoro creato. Se il runner non si registra mai, Anthropic richiede con un ID ordine fresco dopo `--expected-spawn-seconds`.3282. **Non ritentare il carico di lavoro.** Un ID ordine significa al massimo un carico di lavoro creato. Se il runner non si registra mai, Anthropic richiede con un ID ordine fresco dopo `--expected-spawn-seconds`.
2893. **Utilizzare il contratto del codice di uscita.** Uscita 0 significa inviato. Uscita 1 significa fallimento ritentabile; la sessione si ritira e viene riottenuta. Uscita 2 o superiore significa non ritentabile; la sessione è bloccata dallo spawn di nuovo fino a quando un [Owner](/docs/it/cloud-environments#organization-shared-environments) non seleziona **Retry** su di essa nella scheda **Activity** dell'ambiente. Su uscita diversa da zero, la coda dello stderr dell'hook appare lì come motivo del fallimento, quindi scrivere l'errore azionabile su stderr e mai segreti. Per una richiesta di pre-warming non c'è sessione da fallire: l'orchestratore registra un'uscita diversa da zero localmente solo, e il server richiede di nuovo lo spawn dopo il lease.3293. **Usa il contratto del codice di uscita.** Esci con lo stato corrispondente all'esito:
2904. **Impostare `--expected-spawn-seconds` ad almeno il tempo di avvio p99.** Questo è il lease lato server. Tutte le repliche dell'orchestratore devono utilizzare lo stesso valore.330
331 * **Uscita 0**: inviato.
332 * **Uscita 1**: errore che si può riprovare. La sessione attende e viene riproposta.
333 * **Uscita 2 o superiore**: errore che non si può riprovare. Alla sessione viene impedito un nuovo spawn finché un utente non le invia un nuovo messaggio o un [Owner](/docs/it/cloud-environments#organization-shared-environments) non seleziona **Retry** su di essa nella scheda **Activity** dell'ambiente.
334
335 In caso di uscita diversa da zero, la parte finale dello stderr dell'hook appare nella scheda **Activity** come motivo dell'errore, quindi scrivi su stderr l'errore su cui si può intervenire e non scriverci mai segreti. In un hook shell, [mantieni riprovabili gli errori transitori](#keep-transient-failures-retryable-in-a-shell-hook).
336
337 Una richiesta di pre-warming non ha una sessione da far fallire: l'orchestratore registra un'uscita diversa da zero solo localmente, e il server richiede di nuovo lo spawn dopo la scadenza del lease di `--expected-spawn-seconds`.
3384. **Imposta `--expected-spawn-seconds` ad almeno il tuo tempo p99 dalla richiesta di spawn alla registrazione del runner.** Misura a partire da quando l'orchestratore riceve la richiesta di spawn e includi sia l'eventuale attesa di capacità sulla tua piattaforma sia il tempo di avvio. Questo valore è il lease lato server, e l'ordine di lavoro scade insieme a esso, quindi un runner il cui carico di lavoro impiega più tempo non può registrarsi. Tutte le repliche dell'orchestratore devono utilizzare lo stesso valore.
291 339
292Tutto ciò che l'hook scrive su stdout o stderr appare nel log dell'orchestratore con le credenziali automaticamente redatte. Se le sessioni rimangono in coda, controllare il corpo `/healthz` dell'orchestratore per i conteggi della coda, quindi aprire la scheda **Activity** dell'ambiente sulla [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): espandere una sessione fallita lì per il suo errore di spawn e selezionare **Retry** per richiederlo di nuovo.340Tutto ciò che l'hook scrive su stdout o stderr appare nel log dell'orchestratore con le credenziali automaticamente redatte. Se le sessioni rimangono in coda, controllare il corpo `/healthz` dell'orchestratore per i conteggi della coda, quindi aprire la scheda **Activity** dell'ambiente sulla [pagina di amministrazione **Cloud environments**](https://claude.ai/admin-settings/cloud-environments): espandere una sessione fallita lì per il suo errore di spawn e selezionare **Retry** per richiederlo di nuovo.
293 341
294Una sessione che rimane in coda senza errore di spawn nella scheda **Activity** può significare che l'hook è chiave sull'ID sessione. Per confermare, controllare se la propria piattaforma ha un carico di lavoro per la prima richiesta di spawn di quella sessione e nessuno per le richieste. Se così, chiave il carico di lavoro su `CLAUDE_RUNNER_ORDER_ID` invece.342Una sessione che rimane in coda senza errore di spawn nella scheda **Activity** può significare che l'hook è chiave sull'ID sessione. Per confermare, controllare se la propria piattaforma ha un carico di lavoro per la prima richiesta di spawn di quella sessione e nessuno per le richieste. Se così, chiave il carico di lavoro su `CLAUDE_RUNNER_ORDER_ID` invece.
295 343
344<h4 id="keep-transient-failures-retryable-in-a-shell-hook">
345 Mantieni riprovabili gli errori transitori in un hook shell
346</h4>
347
348In un hook shell che usa `set -e`, un errore che un nuovo tentativo avrebbe potuto risolvere può bloccare la sessione. L'hook si ferma al comando che fallisce ed esce con lo stato di quel comando, e l'orchestratore applica il contratto del codice di uscita a quello stato. Molti errori restituiscono uno stato pari a 2 o superiore, come `127` quando un comando non è installato e `22` da `curl --fail` in caso di errore HTTP, quindi bloccano la sessione al primo errore.
349
350Una sessione che l'hook ha già bloccato rimane bloccata finché un utente non le invia un nuovo messaggio o un [Owner](/docs/it/cloud-environments#organization-shared-environments) non seleziona **Retry** su di essa nella scheda **Activity** dell'ambiente.
351
352Per trasformare invece un errore di questo tipo in uscita 1, inserisci queste righe subito sotto la riga `#!` dell'hook, prima di qualsiasi cosa possa fallire:
353
354```bash theme={null}
355set -e
356PERMANENT=; permanent() { printf '%s\n' "$*" >&2; PERMANENT=1; exit 2; }
357trap 'rc=$?; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
358```
359
360Queste righe cambiano il comportamento del resto dell'hook, quindi dopo averle aggiunte controlla l'hook per ciascuno di questi schemi:
361
362* **`exit 2` o superiore isolato**: con il trap impostato, diventa uscita 1. Per un errore che nessun nuovo tentativo può risolvere, chiama invece `permanent` con il motivo, ad esempio `permanent "namespace claude-runners does not exist"`. Chiamalo nella shell principale, non all'interno di `$( )`, `( )` o di una pipe.
363* **`exec`**: non iniziare l'ultimo comando dell'hook con `exec`, perché `exec` sostituisce la shell e il trap non viene eseguito.
364* **Secondo trap `EXIT`**: un secondo `trap ... EXIT` sostituisce il primo, quindi unisci i due in un unico trap. Metti i tuoi comandi di pulizia subito dopo `rc=$?;` e termina ciascuno con `|| true;`. La pulizia viene quindi eseguita sia in caso di errore sia in caso di successo, e un comando di pulizia che fallisce non imposta lo stato di uscita dell'hook. Questo trap unificato mostra la struttura, con `your-cleanup-command` al posto del tuo comando:
365
366 ```bash theme={null}
367 trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
368 ```
369* **Comandi a cui è consentito fallire**: se prima l'hook non usava `set -e`, ora si ferma al primo comando che restituisce un valore diverso da zero, come una ricerca che non trova nulla o un invio duplicato che la tua piattaforma rifiuta. Se l'hook agisce in base al risultato, rendi quel comando la condizione di un `if`. Se ne ignora il risultato, fai seguire il comando da `|| true`.
370
371Per verificare che il trap funzioni, aggiungi subito sotto la riga `trap` una riga che chiama un comando inesistente, come `no-such-command`. Esegui il file dell'hook dalla tua shell e verifica che `echo $?` stampi `1`, quindi rimuovi la riga.
372
296<h2 id="send-model-requests-to-bedrock-or-agent-platform">373<h2 id="send-model-requests-to-bedrock-or-agent-platform">
297 Inviare le richieste al modello a Bedrock o ad Agent Platform374 Inviare le richieste al modello a Bedrock o ad Agent Platform
298</h2>375</h2>
381Una sessione che invia le richieste al modello ad Amazon Bedrock o ad Agent Platform di Google Cloud differisce da una sessione sull'API di Anthropic nei seguenti modi:458Una sessione che invia le richieste al modello ad Amazon Bedrock o ad Agent Platform di Google Cloud differisce da una sessione sull'API di Anthropic nei seguenti modi:
382 459
383* **Policy da claude.ai**: le [impostazioni gestite dal server](/docs/it/server-managed-settings) non raggiungono queste sessioni. Nemmeno le policy dell'organizzazione che un Owner imposta nelle impostazioni di amministrazione di Claude Code le raggiungono, quindi Claude Code non le applica all'interno della sessione. Inserisci le regole su cui fai affidamento nel [file delle impostazioni gestite](/docs/it/managed-settings#delivery-mechanisms) dell'immagine del runner.460* **Policy da claude.ai**: le [impostazioni gestite dal server](/docs/it/server-managed-settings) non raggiungono queste sessioni. Nemmeno le policy dell'organizzazione che un Owner imposta nelle impostazioni di amministrazione di Claude Code le raggiungono, quindi Claude Code non le applica all'interno della sessione. Inserisci le regole su cui fai affidamento nel [file delle impostazioni gestite](/docs/it/managed-settings#delivery-mechanisms) dell'immagine del runner.
461* **Skill dell'account**: queste sessioni non scaricano le skill abilitate per l'account claude.ai di una persona. Consulta [Come viene assemblata la configurazione di ogni sessione](#how-each-session’s-config-is-assembled).
384* **File**: i file che le persone allegano a una sessione in claude.ai o nell'app mobile o desktop non la raggiungono, e Claude non può inviare file indietro con lo [strumento `SendUserFile`](/docs/it/tools-reference). Inserisci invece i file di input nel repository o sul runner.462* **File**: i file che le persone allegano a una sessione in claude.ai o nell'app mobile o desktop non la raggiungono, e Claude non può inviare file indietro con lo [strumento `SendUserFile`](/docs/it/tools-reference). Inserisci invece i file di input nel repository o sul runner.
385* **Selezione del modello**: il control plane di Anthropic invia il modello di ogni sessione e, quando una sessione viene avviata senza un modello, Claude Code usa quello predefinito per il provider. Il runner rimuove `ANTHROPIC_MODEL` e `ANTHROPIC_DEFAULT_MODEL` dall'ambiente che passa alle sessioni. Gli esempi nelle pagine dei provider impostano `ANTHROPIC_MODEL`, ma nell'ambiente del runner nessuna delle due variabili ha effetto. Le variabili per famiglia descritte in Fissare le versioni dei modelli per [Amazon Bedrock](/docs/it/amazon-bedrock#4-pin-model-versions) e per [Agent Platform](/docs/it/google-vertex-ai#5-pin-model-versions) raggiungono invece le sessioni. Determinano a cosa si risolve un alias come `opus`, non a cosa si risolve un ID completo del modello.463* **Selezione del modello**: il control plane di Anthropic invia il modello di ogni sessione e, quando una sessione viene avviata senza un modello, Claude Code usa quello predefinito per il provider. Non puoi scegliere il modello con `ANTHROPIC_MODEL` o `ANTHROPIC_DEFAULT_MODEL` nell'ambiente del runner, ma puoi fissare a cosa si risolve un alias:
464 * **`ANTHROPIC_MODEL` e `ANTHROPIC_DEFAULT_MODEL`**: il runner le rimuove dall'ambiente che passa alle sessioni, anche se gli esempi nelle pagine dei provider impostano `ANTHROPIC_MODEL`.
465 * **Variabili per famiglia per fissare i modelli**: le variabili descritte in Fissare le versioni dei modelli per [Amazon Bedrock](/docs/it/amazon-bedrock#4-pin-model-versions) e per [Agent Platform](/docs/it/google-vertex-ai#5-pin-model-versions) raggiungono invece le sessioni. Determinano a cosa si risolve un alias come `opus`, non a cosa si risolve un ID completo del modello.
386* **Modelli non serviti dal tuo account**: una sessione può fallire su un messaggio con un errore che indica il modello. Abilita i modelli che i tuoi sviluppatori possono scegliere, il modello in background descritto in Fissare le versioni dei modelli e il modello del classificatore usato dalla [modalità auto](/docs/it/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry). Su Amazon Bedrock, consenti ciascuno di essi nella tua policy.466* **Modelli non serviti dal tuo account**: una sessione può fallire su un messaggio con un errore che indica il modello. Abilita i modelli che i tuoi sviluppatori possono scegliere, il modello in background descritto in Fissare le versioni dei modelli e il modello del classificatore usato dalla [modalità auto](/docs/it/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry). Su Amazon Bedrock, consenti ciascuno di essi nella tua policy.
387* **Ricerca web e modalità veloce**: la [ricerca web](/docs/it/tools-reference#websearch-tool-behavior) non è disponibile su Amazon Bedrock e la [modalità veloce](/docs/it/fast-mode) non è disponibile su nessuno dei due provider. Per altre funzionalità che variano in base al provider, consulta [Funzionalità della CLI che variano in base al provider](/docs/it/feature-availability#cli-capabilities-that-vary-by-provider).467* **Ricerca web e modalità veloce**: la [ricerca web](/docs/it/tools-reference#websearch-tool-behavior) non è disponibile su Amazon Bedrock e la [modalità veloce](/docs/it/fast-mode) non è disponibile su nessuno dei due provider. Per altre funzionalità che variano in base al provider, consulta [Funzionalità della CLI che variano in base al provider](/docs/it/feature-availability#cli-capabilities-that-vary-by-provider).
388 468
411 491
412Le sessioni ereditano l'ambiente del runner, quindi imposta lì [`ENABLE_TOOL_SEARCH`](/docs/it/mcp#scale-with-mcp-tool-search) per controllare la ricerca degli strumenti MCP per ogni sessione avviata da un runner; la pagina MCP descrive i valori.492Le sessioni ereditano l'ambiente del runner, quindi imposta lì [`ENABLE_TOOL_SEARCH`](/docs/it/mcp#scale-with-mcp-tool-search) per controllare la ricerca degli strumenti MCP per ogni sessione avviata da un runner; la pagina MCP descrive i valori.
413 493
494<a id="connection-timing" />
495
496<h3 id="wait-for-mcp-servers-before-the-first-turn">
497 Attendere i server MCP prima del primo turno
498</h3>
499
500Una sessione self-hosted attende brevemente i server MCP che si stanno ancora connettendo, in due punti distinti. Un server che manca un'attesa ha i suoi strumenti assenti all'inizio del primo turno, e questi diventano disponibili in seguito senza alcun intervento da parte tua. Le due attese sono:
501
502* **Avvio della sessione**: prima che l'elenco degli strumenti venga acquisito per la prima volta, la sessione attende per impostazione predefinita fino a 5 secondi un server HTTP o SSE la cui voce imposta [`alwaysLoad: true`](/docs/it/mcp#exempt-a-server-from-deferral), oppure tutti i server quando imposti [`MCP_CONNECTION_NONBLOCKING=0`](/docs/it/env-vars) nell'ambiente del runner. Altrimenti i server HTTP e SSE si connettono in background. Mentre la sessione attende qui, l'inizializzazione è più lenta. [`MCP_CONNECT_TIMEOUT_MS`](/docs/it/env-vars) modifica il valore predefinito di 5 secondi.
503* **Primo turno**: dopo l'arrivo del messaggio, il primo turno attende fino a 2 secondi i server stdio che si stanno ancora connettendo. Mentre la sessione attende qui, la prima risposta è più lenta. Per modificare la durata di questa attesa, imposta [`CLAUDE_CODE_MCP_STARTUP_WAIT_MS`](/docs/it/env-vars) nell'ambiente del runner. Non modifica quali server sono coperti dall'attesa. Richiede Claude Code v2.1.274 o successiva.
504
505`claude mcp add` non ha un flag `alwaysLoad`. Per impostare la chiave, aggiungi invece il server con `claude mcp add-json`, che la accetta nel JSON del server e la scrive in `.claude.json`. Nel tuo Dockerfile:
506
507```dockerfile theme={null}
508RUN claude mcp add-json core '{"type":"http","url":"https://mcp.example.com/mcp","alwaysLoad":true}' --scope user
509```
510
511Se gli strumenti di un server non compaiono nemmeno nei turni successivi, verifica se il server ha effettivamente raggiunto la sessione, come descritto in [Server MCP](#mcp-servers).
512
414<h3 id="turn-off-built-in-session-tools">513<h3 id="turn-off-built-in-session-tools">
415 Disattivare gli strumenti di sessione integrati514 Disattivare gli strumenti di sessione integrati
416</h3>515</h3>
572 671
573Impostare `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` per seminare da un percorso diverso, o puntarlo a una directory vuota per disabilitare la semina.672Impostare `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` per seminare da un percorso diverso, o puntarlo a una directory vuota per disabilitare la semina.
574 673
575Il `.claude/settings.json` committato nel repository si sovrappone come impostazioni di progetto. In una sessione con più repository, [ha effetto al massimo il file di un solo repository](#repository-settings-in-sessions-with-several-repositories). Le sessioni leggono anche [`managed-settings.json`](/docs/it/settings#where-settings-live) dal percorso di sistema standard nell'immagine del runner. Se le sue chiavi si applicano insieme alle [impostazioni gestite dal server](/docs/it/server-managed-settings) dipende da [come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources): per impostazione predefinita, quando la tua organizzazione fornisce chiavi gestite dal server, le sessioni ignorano il file dell'immagine del runner, ad eccezione delle [chiavi che Claude Code legge da ogni fonte di amministrazione](/docs/it/managed-settings#keys-read-from-every-admin-source), come il blocco `env`, i blocchi della sandbox, i percorsi dei binari della sandbox e `forceRemoteSettingsRefresh`. Consulta [precedenza delle impostazioni](/docs/it/settings#settings-precedence).674Le sessioni leggono anche questi file di impostazioni:
675
676* **Impostazioni di progetto**: un `.claude/settings.json` committato nel repository si sovrappone alla baseline a livello utente. In una sessione con più repository, [ha effetto al massimo il file di un solo repository](#repository-settings-in-sessions-with-several-repositories).
677* **Impostazioni gestite**: le sessioni leggono [`managed-settings.json`](/docs/it/settings#where-settings-live) dal percorso di sistema standard nella tua immagine del runner. Per sapere se le sue chiavi si applicano insieme alle [impostazioni gestite dal server](/docs/it/server-managed-settings), consulta [come Claude Code combina le fonti gestite](/docs/it/managed-settings#how-claude-code-combines-managed-sources).
678
679Per l'ordine in cui si applicano queste fonti, consulta [precedenza delle impostazioni](/docs/it/settings#settings-precedence).
576 680
577Quando il piano di controllo di Anthropic fornisce una sessione con [hook Claude Code](/docs/it/hooks), il runner li installa insieme, non sopra, la propria configurazione. Richiede Claude Code v2.1.229 o successivo.681Quando il piano di controllo di Anthropic fornisce una sessione con [hook Claude Code](/docs/it/hooks), il runner li installa insieme, non sopra, la propria configurazione. Richiede Claude Code v2.1.229 o successivo.
578 682
580* **Chi li crea**: il piano di controllo popola gli script da costanti fisse nella propria distribuzione, mai da input per sessione o di terze parti.684* **Chi li crea**: il piano di controllo popola gli script da costanti fisse nella propria distribuzione, mai da input per sessione o di terze parti.
581* **Cosa ancora li governa**: gli hook forniti attraverso `--settings` entrano nella configurazione ordinaria dell'hook unito, non nel livello gestito, quindi le impostazioni gestite si applicano ancora. `disableAllHooks` li disabilita, e non sono tra le categorie che [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly) mantiene caricate.685* **Cosa ancora li governa**: gli hook forniti attraverso `--settings` entrano nella configurazione ordinaria dell'hook unito, non nel livello gestito, quindi le impostazioni gestite si applicano ancora. `disableAllHooks` li disabilita, e non sono tra le categorie che [`allowManagedHooksOnly`](/docs/it/settings-reference#allowmanagedhooksonly) mantiene caricate.
582 686
687Quando una persona avvia una propria sessione, Claude Code scarica anche le [skill abilitate per il suo account claude.ai](/docs/it/skills#skills-in-cowork-and-cloud-sessions) nella directory di configurazione di quella sessione. L'esecuzione di una [routine](/docs/it/routines) non riceve le skill del suo proprietario, e una sessione che [invia le richieste al modello a Bedrock o Agent Platform](#send-model-requests-to-bedrock-or-agent-platform) non ne scarica alcuna. Per una skill di cui quelle sessioni hanno bisogno, fai il commit nella directory `.claude/skills/` del repository oppure aggiungila alla tua immagine del runner.
688
583Al di fuori delle sessioni [Claude Tag](https://claude.com/docs/claude-tag/overview), una sessione in un ambiente self-hosted viene eseguita con la [memoria automatica](/docs/it/memory#auto-memory) disattivata per impostazione predefinita. Per le istruzioni che devono valere tra una sessione e l'altra, usa il `CLAUDE.md` nell'immagine del runner o nel repository.689Al di fuori delle sessioni [Claude Tag](https://claude.com/docs/claude-tag/overview), una sessione in un ambiente self-hosted viene eseguita con la [memoria automatica](/docs/it/memory#auto-memory) disattivata per impostazione predefinita. Per le istruzioni che devono valere tra una sessione e l'altra, usa il `CLAUDE.md` nell'immagine del runner o nel repository.
584 690
585Lo snapshot di `~/.claude/` dell'host acquisito dal runner esclude la directory `projects/`. La posizione di archiviazione predefinita della memoria automatica si trova in quella directory. Se vi inserisci file di memoria, il runner non li copia nelle sessioni e questi non attivano la memoria automatica.691Lo snapshot di `~/.claude/` dell'host acquisito dal runner esclude la directory `projects/`. La posizione di archiviazione predefinita della memoria automatica si trova in quella directory. Se vi inserisci file di memoria, il runner non li copia nelle sessioni e questi non attivano la memoria automatica.
