31| Variable | Description |31| Variable | Description |
32| :- | :- |32| :- | :- |
33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Le JWT de session, préfixé `sk-ant-cc-`. Sa revendication `act` identifie le créateur de la session, avec l'email du créateur quand la surface de création l'a enregistré. La valeur est le token au moment du spawn ; les actualisations arrivent sur stdin de l'enfant, donc un wrapper ne voit que la valeur initiale. Voir [Vérifier l'identité de la session](/docs/fr/self-hosted-environments-identity). |33| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Le JWT de session, préfixé `sk-ant-cc-`. Sa revendication `act` identifie le créateur de la session, avec l'email du créateur quand la surface de création l'a enregistré. La valeur est le token au moment du spawn ; les actualisations arrivent sur stdin de l'enfant, donc un wrapper ne voit que la valeur initiale. Voir [Vérifier l'identité de la session](/docs/fr/self-hosted-environments-identity). |
34| `CCR_SESSION_ACCOUNT_EMAIL` | L'email du créateur de la session, pré-extrait par le runner de la revendication `act.email` du token sans vérification de signature. Approprié pour l'étiquetage, comme les trailers de commit. Quand l'email contrôle l'émission d'identifiants, vérifiez le token et lisez la revendication à partir de celui-ci à la place ; voir [Provisionner les identifiants limités au créateur de la session](#provision-credentials-scoped-to-the-session-creator). Non défini quand le token ne porte pas d'email de créateur. Traiter comme des informations d'identification personnelle. |34| `CCR_SESSION_ACCOUNT_EMAIL` | L'email du créateur de la session, pré-extrait par le runner de la revendication `act.email` du token sans vérification de signature. Approprié pour l'étiquetage, comme les trailers de commit. Quand l'email contrôle l'émission d'identifiants, vérifiez le token et lisez la revendication à partir de celui-ci à la place. Voir [Provisionner les identifiants limités au créateur de la session](#provision-credentials-scoped-to-the-session-creator). Non défini quand le token ne porte pas d'email de créateur, par exemple dans les sessions créées par l'identité de service de votre organisation. Traiter comme des données personnelles identifiables. |
35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La surface client qui a créé la session, comme `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` ou `scheduled_trigger`. Anthropic enregistre la valeur une fois à la création de la session, donc le wrapper et chaque hook de cycle de vie voient la même valeur. Utilisez-la pour l'analyse d'adoption et l'étiquetage uniquement, pas comme signal d'autorisation. Non défini quand la session n'a pas de surface enregistrée ou reconnue, donc référencez-la comme `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sous `set -u`. Nécessite Claude Code v2.1.229 ou ultérieur. |35| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La surface client qui a créé la session, comme `web_claude_ai`, `desktop_app`, `ios`, `claude_code_cli` ou `scheduled_trigger`. Anthropic enregistre la valeur une fois à la création de la session, donc le wrapper et chaque hook de cycle de vie voient la même valeur. Utilisez-la pour l'analyse d'adoption et l'étiquetage uniquement, pas comme signal d'autorisation. Non défini quand la session n'a pas de surface enregistrée ou reconnue. Nécessite Claude Code v2.1.229 ou ultérieur. |
36| `CLAUDE_RUNNER_CLAUDE_BIN` | Chemin absolu vers le binaire Claude Code du runner lui-même. Terminez votre wrapper avec `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` pour passer au binaire épinglé sans coder en dur un chemin d'installation. |36| `CLAUDE_RUNNER_CLAUDE_BIN` | Chemin absolu vers le binaire Claude Code du runner lui-même. Terminez votre wrapper avec `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` pour passer au binaire épinglé sans coder en dur un chemin d'installation. |
37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID de session sous la forme balisée `cse_...`. C'est la même session que les [hooks de cycle de vie](#lifecycle-hooks) voient comme `CLAUDE_RUNNER_SESSION_ID` sous la forme `session_...` ; les variables UUID correspondent entre les deux, et remplacer le préfixe `cse_` par `session_` donne l'ID affiché dans l'URL de la session. |37| `CLAUDE_CODE_REMOTE_SESSION_ID` | ID de session sous la forme balisée `cse_...`. C'est la même session que les [hooks de cycle de vie](#lifecycle-hooks) voient comme `CLAUDE_RUNNER_SESSION_ID` sous la forme `session_...` ; les variables UUID correspondent entre les deux, et remplacer le préfixe `cse_` par `session_` donne l'ID affiché dans l'URL de la session. |
38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | Le même ID de session sous la forme UUID canonique, pour les systèmes qui utilisent des UUIDs comme clé. |38| `CLAUDE_CODE_REMOTE_SESSION_UUID` | Le même ID de session sous la forme UUID canonique, pour les systèmes qui utilisent des UUIDs comme clé. |
39| `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` | Pour une session [Claude Tag](https://claude.com/docs/claude-tag/overview) qui appartient à un fil Slack, le lien vers ce fil. Non défini pour les autres sessions, et peut aussi être non défini pour une session de fil. |
40| `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` | Pour une session Claude Tag qui appartient à un fil Slack, l'horodatage Slack de ce fil, comme `1700000000.000100`. Peut être non défini, et peut être défini lorsque `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` ne l'est pas, donc vérifiez chaque variable séparément. |
39| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Chemin absolu vers un fichier par session contenant le JWT de session actuel, maintenu à jour lors des actualisations de token. Les sous-processus shell le lisent pour leur en-tête `Authorization` lors du téléchargement des pièces jointes que l'utilisateur a ajoutées à la session. `exec` préserve la variable automatiquement ; un wrapper qui reconstruit l'environnement de l'enfant doit transporter la variable, ou les téléchargements de pièces jointes s'arrêtent silencieusement. |41| `CLAUDE_SESSION_INGRESS_TOKEN_FILE` | Chemin absolu vers un fichier par session contenant le JWT de session actuel, maintenu à jour lors des actualisations de token. Les sous-processus shell le lisent pour leur en-tête `Authorization` lors du téléchargement des pièces jointes que l'utilisateur a ajoutées à la session. `exec` préserve la variable automatiquement ; un wrapper qui reconstruit l'environnement de l'enfant doit transporter la variable, ou les téléchargements de pièces jointes s'arrêtent silencieusement. |
40| `CLAUDE_CONFIG_DIR` | Répertoire de configuration Claude par session, écrit au démarrage de la session à partir de l'instantané de la configuration de l'hôte runner que le runner capture au démarrage ; voir [Permissions et approbation d'outils](#permissions-and-tool-approval). Les écritures ici sont isolées à cette session. Le répertoire reste sous `<base-dir>/_sessions/` après la fin de la session sauf si vous démarrez le runner avec [`--remove-session-state`](/docs/fr/self-hosted-environments-reference#runner-cli-flags) ; voir [Réutiliser un checkout pré-chauffé](/docs/fr/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout). |42| `CLAUDE_CONFIG_DIR` | Répertoire de configuration Claude par session, écrit au démarrage de la session à partir de l'instantané de la configuration de l'hôte runner que le runner capture au démarrage ; voir [Permissions et approbation d'outils](#permissions-and-tool-approval). Les écritures ici sont isolées à cette session. Le répertoire reste sous `<base-dir>/_sessions/` après la fin de la session sauf si vous démarrez le runner avec [`--remove-session-state`](/docs/fr/self-hosted-environments-reference#runner-cli-flags) ; voir [Réutiliser un checkout pré-chauffé](/docs/fr/self-hosted-environments-deploy#reuse-a-pre-warmed-checkout). |
41| `ANTHROPIC_BASE_URL` | L'URL de base de l'API que l'enfant utilisera, livrée par le plan de contrôle par session et normalement `https://api.anthropic.com`. Ne la remplacez pas : l'identifiant d'inférence de la session est un token OAuth émis par Anthropic que les autres fournisseurs n'acceptent pas. |43| `ANTHROPIC_BASE_URL` | L'URL de base de l'API que l'enfant utilisera, livrée par le plan de contrôle par session et normalement `https://api.anthropic.com`. Ne la remplacez pas : l'identifiant d'inférence de la session est un token OAuth émis par Anthropic que les autres fournisseurs n'acceptent pas. |
43 45
44Le wrapper hérite également du reste de l'environnement géré de l'enfant, y compris toutes les variables d'environnement fournies par le serveur. `exec` propage tout automatiquement ; si votre wrapper lance l'enfant d'une autre manière, transmettez l'environnement complet.46Le wrapper hérite également du reste de l'environnement géré de l'enfant, y compris toutes les variables d'environnement fournies par le serveur. `exec` propage tout automatiquement ; si votre wrapper lance l'enfant d'une autre manière, transmettez l'environnement complet.
45 47
48`CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` et `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` parviennent à votre wrapper ou à votre [hook `command`](#command). Elles parviennent aussi à ce que la session exécute, comme les commandes shell, les hooks git et les hooks Claude Code. Les hooks `checkout`, `post-session` et `spawn-runner` ne les reçoivent pas.
49
50<h3 id="give-a-default-to-variables-that-can-be-unset">
51 Donner une valeur par défaut aux variables qui peuvent être non définies
52</h3>
53
54`CCR_SESSION_ACCOUNT_EMAIL`, `CLAUDE_RUNNER_CLIENT_PLATFORM`, `CLAUDE_CODE_REMOTE_SLACK_THREAD_URL` et `CLAUDE_CODE_REMOTE_SLACK_THREAD_TS` peuvent chacune être non définies. Si votre script utilise `set -u`, Bash s'arrête avec `unbound variable` lorsqu'il développe l'une d'elles qui n'est pas définie ; développez-les donc avec une valeur par défaut, comme `${CCR_SESSION_ACCOUNT_EMAIL:-}`.
55
56Partout où un shell développe le lien du fil Slack, prenez ces précautions :
57
58* **Mettez-le entre guillemets** : le lien peut contenir des caractères qu'un shell interprète, comme `?` et `&`, donc mettez la variable entre guillemets, comme dans `"${CLAUDE_CODE_REMOTE_SLACK_THREAD_URL:-}"`.
59* **Gardez sa valeur hors des chaînes `eval` et `sh -c`** : ne substituez pas sa valeur dans une chaîne que `eval` ou `sh -c` exécute, même entre guillemets. Faites plutôt référencer la variable par cette chaîne.
60
46<h3 id="keep-stdin-and-file-descriptor-3-attached">61<h3 id="keep-stdin-and-file-descriptor-3-attached">
47 Garder stdin et le descripteur de fichier 3 attachés62 Garder stdin et le descripteur de fichier 3 attachés
48</h3>63</h3>
49 64
50stdin de l'enfant est le canal de contrôle du runner. Les rotations de token et les signaux de fin de session arrivent dessus. Le runner ouvre également un tuyau sur le descripteur de fichier 3 et lit les signaux d'activité de l'enfant à partir de celui-ci pour piloter les délais d'inactivité et de démarrage. Un simple `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` préserve les deux automatiquement.65stdin de l'enfant est le canal de contrôle du runner. Les rotations de token et les signaux de fin de session arrivent dessus. Le runner ouvre également un tuyau sur le descripteur de fichier 3 et lit les signaux d'activité de l'enfant à partir de celui-ci pour piloter les délais d'inactivité et de démarrage. Un simple `exec "$CLAUDE_RUNNER_CLAUDE_BIN" "$@"` préserve les deux automatiquement.
51 66
52Si votre wrapper met l'enfant en arrière-plan avec un simple `&`, il coupe stdin de l'enfant : la session semble saine jusqu'à ce que la durée de vie du token OAuth initial d'environ 30 minutes expire, puis chaque appel API échoue avec `401 authentication_error`. Si votre wrapper doit mettre l'enfant en arrière-plan, par exemple pour garder un trap de démontage actif, enregistrez stdin sur le descripteur de fichier 4 ou supérieur et réattachez-le explicitement :67Si votre wrapper met l'enfant en arrière-plan avec un simple `&`, il coupe stdin de l'enfant. La session semble saine jusqu'à ce que la durée de vie du token OAuth initial d'environ 30 minutes expire, puis chaque appel API qui utilise le token échoue avec `401 authentication_error`. Si votre wrapper doit mettre l'enfant en arrière-plan, par exemple pour garder un trap de démontage actif, enregistrez stdin sur le descripteur de fichier 4 ou supérieur et réattachez-le explicitement :
53 68
54```bash theme={null}69```bash theme={null}
55exec 4<&070exec 4<&0
59wait "$CHILD"74wait "$CHILD"
60```75```
61 76
62Ne fermez pas ou ne réutilisez pas le descripteur de fichier 3 dans le wrapper. Rediriger stdout et stderr de l'enfant est correct.77Vous pouvez rediriger stdout de l'enfant. Gardez le descripteur de fichier 3 et stderr attachés au runner :
78
79* **Descripteur de fichier 3** : transporte les signaux d'activité de l'enfant vers le runner. Ne le fermez pas et ne le réutilisez pas dans le wrapper.
80* **stderr** : lorsque le wrapper ou l'enfant se termine avec un code non nul, le runner publie les dernières lignes de stderr dans la session et les affiche dans son propre log. L'utilisateur de la session voit ces lignes, donc n'affichez pas de secrets sur stderr, et retirez `set -x` avant de déployer le wrapper. Si vous redirigez stderr, les sessions s'exécutent toujours, mais le runner signale un échec avec le seul code de sortie.
63 81
64<h3 id="pass-the-system-prompt-flags-through">82<h3 id="pass-the-system-prompt-flags-through">
65 Transmettre les flags de prompt système83 Transmettre les flags de prompt système
108 checkout126 checkout
109</h3>127</h3>
110 128
111S'exécute une fois par dépôt, à la place du clone et de la récupération intégrés du runner. Utilisez le hook pour cloner à partir d'un miroir de lecture directe, amorcer un arbre de travail à partir d'une archive ou appliquer une authentification git par session. Le runner définit ces variables, et peut définir d'autres variables `CLAUDE_RUNNER_` que le tableau ne répertorie pas :129S'exécute une fois par dépôt, à la place du clone et de la récupération intégrés du runner. Utilisez le hook pour cloner à partir d'un miroir de lecture directe accessible via HTTPS ou SSH, amorcer un arbre de travail à partir d'une archive ou appliquer une authentification git par session. Le runner définit ces variables, et peut définir d'autres variables `CLAUDE_RUNNER_` que le tableau ne répertorie pas :
112 130
113| Variable | Description |131| Variable | Description |
114| :- | :- |132| :- | :- |
115| `CLAUDE_RUNNER_REPO_URL` | URL du référentiel à cloner, après que tout `--git-host-rewrite` et `--git-ssh-rewrite` aient été appliqués |133| `CLAUDE_RUNNER_REPO_URL` | URL du référentiel à cloner, après que tout `--git-host-rewrite` et `--git-ssh-rewrite` aient été appliqués |
116| `CLAUDE_RUNNER_REPO_REF` | Révision à vérifier : branche, tag ou SHA de commit comme la session l'a demandé. Vide signifie la branche par défaut du référentiel. |134| `CLAUDE_RUNNER_REPO_REF` | Révision à extraire, telle que la session l'a demandée : une branche, un tag, un SHA de commit ou un nom de référence complet comme `refs/pull/<number>/head`. Vide signifie la branche par défaut du dépôt. |
117| `CLAUDE_RUNNER_CHECKOUT_PATH` | Chemin absolu où l'arbre de travail doit être laissé |135| `CLAUDE_RUNNER_CHECKOUT_PATH` | Chemin absolu où l'arbre de travail doit être laissé |
118| `CLAUDE_RUNNER_SESSION_ID` | ID de session sous la forme balisée `session_...`, pour la journalisation et la corrélation |136| `CLAUDE_RUNNER_SESSION_ID` | ID de session sous la forme balisée `session_...`, pour la journalisation et la corrélation |
119| `CLAUDE_RUNNER_SESSION_UUID` | Le même ID de session sous la forme UUID canonique |137| `CLAUDE_RUNNER_SESSION_UUID` | Le même ID de session sous la forme UUID canonique |
120| `CLAUDE_RUNNER_API_BASE_URL` | URL de base de l'API Anthropic pour les appels limités à la session |138| `CLAUDE_RUNNER_API_BASE_URL` | URL de base de l'API Anthropic pour les appels limités à la session |
121| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La surface client qui a créé la session, comme `web_claude_ai`, `desktop_app` ou `ios`. Non défini quand la session n'a pas de surface enregistrée ou reconnue. |139| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La surface client qui a créé la session, comme `web_claude_ai`, `desktop_app` ou `ios`. Non défini quand la session n'a pas de surface enregistrée ou reconnue, donc référencez-la sous la forme `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sous `set -u`. Nécessite Claude Code v2.1.229 ou ultérieur. |
122| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Le token d'accès de session, pour les appels API limités à la session |140| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Le token d'accès de session, pour les appels API limités à la session |
123| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Paramètres git que le runner fixe pour le git que votre hook exécute. [Configuration git dans les hooks de cycle de vie](#git-configuration-inside-lifecycle-hooks) les décrit. Nécessite Claude Code v2.1.280 ou ultérieur. |141| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Paramètres git que le runner fixe pour le git que votre hook exécute. [Configuration git dans les hooks de cycle de vie](#git-configuration-inside-lifecycle-hooks) les décrit. Nécessite Claude Code v2.1.280 ou ultérieur. |
124 142
125Le script doit laisser un arbre de travail à `CLAUDE_RUNNER_CHECKOUT_PATH` vérifié à la révision demandée. HEAD détaché est correct ; le runner crée la branche de travail de la session par-dessus. Le runner vérifie que le chemin contient un `.git` après ; si votre hook matérialise une source non-git comme Perforce ou une archive dépaquetée, définissez `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` dans l'environnement du runner pour ignorer cette vérification. Les flux basés sur git comme la création de branche de travail et l'envoi de résultats nécessitent un checkout git, donc exportez les résultats à partir d'arbres non-git avec un hook [`post-session`](#post-session).143Le script doit laisser un arbre de travail à `CLAUDE_RUNNER_CHECKOUT_PATH` extrait à la révision demandée. Un HEAD détaché convient, car le runner crée la branche de travail de la session par-dessus.
126 144
127Le runner ne transmet pas un identifiant git au hook. À la place, frappez un identifiant de clone par session à partir de l'identité de la session : vérifiez `CLAUDE_CODE_SESSION_ACCESS_TOKEN` avec une bibliothèque JWT standard par rapport au point de terminaison JWKS sous `CLAUDE_RUNNER_API_BASE_URL`, comme décrit dans [Vérifier le token à partir de votre service](/docs/fr/self-hosted-environments-identity#verify-the-token-from-your-service), puis faites en sorte que votre service d'identifiants émette un identifiant de clone de courte durée pour l'identité dans la revendication `act` du token. `CLAUDE_RUNNER_CLAUDE_BIN` n'est pas défini dans l'environnement du hook de checkout, donc la sous-commande `decode-token` n'est pas disponible ici. Revenir à tout ce que l'authentification git de l'hôte a déjà, comme un agent SSH, un helper d'identifiants ou `.netrc`, est aussi une option.145Après le retour de votre hook, le runner vérifie que `CLAUDE_RUNNER_CHECKOUT_PATH` contient un `.git`. Si votre hook matérialise une source non-git comme Perforce ou une archive tarball dépaquetée, définissez `CLAUDE_RUNNER_SKIP_GIT_VERIFY=1` dans l'environnement du runner pour ignorer cette vérification. Les flux basés sur git comme la création de branche de travail et l'envoi des résultats nécessitent un checkout git, donc exportez les résultats des arbres non-git avec un [hook `post-session`](#post-session).
128 146
129Quand le hook se termine avec un code non-zéro, ou se termine avec 0 sans laisser un checkout utilisable derrière, ce que le runner fait dépend du référentiel :147<h4 id="get-git-credentials-in-the-hook">
148 Obtenir des identifiants git dans le hook
149</h4>
130 150
131* **Un référentiel vers lequel la session envoie les résultats** : le runner échoue la session, et sur une sortie non-zéro affiche la queue du stderr du script à l'utilisateur.151Le runner ne transmet pas d'identifiants git au hook. La sous-commande `decode-token` n'est pas non plus disponible ici, car `CLAUDE_RUNNER_CLAUDE_BIN` n'est pas défini dans l'environnement du hook de checkout. Générez plutôt des identifiants de clone par session à partir de l'identité de la session, ou revenez à l'authentification git propre à l'hôte :
132* **Un référentiel que la session lit uniquement**, comme un référentiel ajouté à une session en cours d'exécution : le runner enregistre une ligne `[runner:warn]` avec le détail de l'échec, affiche une étape `Skipped` à la session, supprime ce que le hook a laissé au chemin de checkout et continue avec les référentiels restants. Quand le runner ne peut pas supprimer le chemin immédiatement, il réessaie la suppression à la fin de la session. Si ignorer laisse la session sans aucun référentiel du tout, le runner échoue la session de toute façon.
133 152
134Avant v2.1.228, le runner échouait la session sur un échec de hook pour tout référentiel, donc un référentiel en lecture seule que le hook ne pouvait pas servir échouait la session à nouveau sur chaque nouveau runner sur lequel la session reprenait.153* **Identifiants de clone par session** : vérifiez `CLAUDE_CODE_SESSION_ACCESS_TOKEN` avec une bibliothèque JWT standard par rapport à l'endpoint JWKS sous `CLAUDE_RUNNER_API_BASE_URL`, comme décrit dans [Vérifier le token à partir de votre service](/docs/fr/self-hosted-environments-identity#verify-the-token-from-your-service). Faites ensuite émettre par votre service d'identifiants des identifiants de clone de courte durée pour l'identité figurant dans la revendication `act` du jeton. Associez ces identifiants à `act.sub`, et n'exigez pas `act.email`.
154* **Authentification git de l'hôte** : utilisez l'authentification git dont l'hôte dispose déjà, comme un agent SSH, un helper d'identifiants ou `.netrc`.
135 155
136Le runner supprime le chemin de checkout après la fin de la session.156<h4 id="when-the-hook-fails">
157 Quand le hook échoue
158</h4>
159
160Le hook échoue lorsqu'il se termine avec un code non nul, ou se termine avec 0 sans laisser de checkout utilisable :
161
162* **Un référentiel vers lequel la session envoie les résultats** : le runner échoue la session, et sur une sortie non-zéro affiche la queue du stderr du script à l'utilisateur.
163* **Un dépôt que la session lit uniquement**, comme un dépôt ajouté à une session en cours d'exécution : le runner consigne une ligne `[runner:warn]` avec le détail de l'échec, publie une étape `Skipped` dans la session, supprime ce que le hook a laissé au chemin de checkout et continue avec les dépôts restants. Si l'omission laisse la session sans aucun dépôt, le runner fait quand même échouer la session.
164
165Lorsque le hook réussit, le runner supprime le chemin de checkout après la fin de la session.
137 166
138<h3 id="post-session">167<h3 id="post-session">
139 post-session168 post-session
151| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Chemins absolus séparés par des deux-points des arbres de travail de la session. Vide pour les sessions sans référentiel. |180| `CLAUDE_RUNNER_WORKSPACE_PATHS` | Chemins absolus séparés par des deux-points des arbres de travail de la session. Vide pour les sessions sans référentiel. |
152| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | Chemin vers le journal de débogage de la session, toujours sur le disque pendant que le hook s'exécute |181| `CLAUDE_RUNNER_DEBUG_LOG_PATH` | Chemin vers le journal de débogage de la session, toujours sur le disque pendant que le hook s'exécute |
153| `CLAUDE_RUNNER_API_BASE_URL` | URL de base de l'API Anthropic pour les appels limités à la session |182| `CLAUDE_RUNNER_API_BASE_URL` | URL de base de l'API Anthropic pour les appels limités à la session |
154| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La surface client qui a créé la session, comme `web_claude_ai`, `desktop_app` ou `ios`. Non défini quand la session n'a pas de surface enregistrée ou reconnue. Nécessite Claude Code v2.1.229 ou ultérieur. |183| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La surface client qui a créé la session, comme `web_claude_ai`, `desktop_app` ou `ios`. Non défini quand la session n'a pas de surface enregistrée ou reconnue, donc référencez-la sous la forme `${CLAUDE_RUNNER_CLIENT_PLATFORM:-}` sous `set -u`. Nécessite Claude Code v2.1.229 ou ultérieur. |
155| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Le token d'accès de session, pour les appels API limités à la session |184| `CLAUDE_CODE_SESSION_ACCESS_TOKEN` | Le token d'accès de session, pour les appels API limités à la session |
156| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Paramètres git que le runner fixe pour le git que votre hook exécute. [Configuration git dans les hooks de cycle de vie](#git-configuration-inside-lifecycle-hooks) les décrit. Nécessite Claude Code v2.1.280 ou ultérieur. |185| `GIT_CONFIG_COUNT`, `GIT_CONFIG_KEY_n`, `GIT_CONFIG_VALUE_n` | Paramètres git que le runner fixe pour le git que votre hook exécute. [Configuration git dans les hooks de cycle de vie](#git-configuration-inside-lifecycle-hooks) les décrit. Nécessite Claude Code v2.1.280 ou ultérieur. |
157 186
158`CLAUDE_RUNNER_EXIT_REASON` prend l'une des quatre valeurs :187`CLAUDE_RUNNER_EXIT_REASON` prend l'une des quatre valeurs :
159 188
160* `completed` : la session s'est terminée proprement. Le processus Claude Code s'est terminé normalement, ou la session a été archivée ou supprimée pendant qu'elle était toujours en cours d'exécution.189* `completed` : la session s'est terminée proprement. Le processus Claude Code s'est terminé normalement, ou s'est terminé de lui-même après l'archivage ou la suppression de la session.
161* `failed` : le processus Claude Code s'est écrasé, ou la configuration a échoué après son démarrage.190* `failed` : le processus Claude Code s'est écrasé, ou la configuration a échoué après son démarrage.
162* `interrupted` : le runner a arrêté la session. Il a libéré la session pour libérer l'emplacement, la session a expiré au démarrage, le serveur a déplacé la session hors de ce runner, le runner était en drainage, ou la session a dépassé sa limite [`--kill-session-after-min`](/docs/fr/self-hosted-environments-reference#runner-cli-flags).191* `interrupted` : le runner a arrêté la session, dans l'un des cas suivants :
192 * Le runner a libéré la session pour libérer l'emplacement.
193 * La session a expiré au démarrage.
194 * Le serveur a déplacé la session hors de ce runner.
195 * L'interrogation du runner a détecté un archivage ou une suppression avant la sortie du processus.
196 * Le runner était en drainage.
197 * La session a dépassé sa limite [`--kill-session-after-min`](/docs/fr/self-hosted-environments-reference#runner-cli-flags).
163* `abandoned` : réservé à une session qu'un autre runner a revendiquée. Le hook ne se déclenche actuellement pas dans ce cas.198* `abandoned` : réservé à une session qu'un autre runner a revendiquée. Le hook ne se déclenche actuellement pas dans ce cas.
164 199
165Les [compteurs de cycle de vie de la session](/docs/fr/self-hosted-environments-reference#session-lifecycle-counter-semantics) comptent une libération, un délai d'expiration au démarrage et un déplacement du serveur comme `completed` plutôt que `interrupted`, car le runner a remis l'emplacement proprement. Attendez-vous à cette différence si vous comparez les reçus de hook avec les compteurs.200Si vous comparez les reçus de hook avec les [compteurs de cycle de vie de la session](/docs/fr/self-hosted-environments-reference#session-lifecycle-counter-semantics), attendez-vous à ce que certains reçus `interrupted` y soient comptés comme `completed`. Les compteurs comptent comme `completed` une libération, un délai d'expiration au démarrage, un déplacement du serveur, ainsi qu'un archivage ou une suppression détectés en premier par l'interrogation du runner, car le runner a remis l'emplacement proprement.
166 201
167Le statut de sortie du hook n'affecte jamais le résultat de la session ; un échec est enregistré et ignoré. Le runner attend jusqu'à `--post-session-hook-timeout-sec`, 60 secondes par défaut, à chaque fin de session y compris l'arrêt du runner. Cet exemple sauvegarde le travail non commis dans une branche de secours :202Le statut de sortie du hook n'affecte jamais le résultat de la session ; un échec est enregistré et ignoré. Le runner attend jusqu'à `--post-session-hook-timeout-sec`, 60 secondes par défaut, à chaque fin de session y compris l'arrêt du runner. Cet exemple sauvegarde le travail non commis dans une branche de secours :
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# Les remplacements -c l'emportent sur les paramètres locaux au dépôt, empêchant la configuration209# Les remplacements -c l'emportent sur les paramètres locaux au dépôt, empêchant la configuration
174# fsmonitor, hook-path et gpg-program écrite par la session d'exécuter du code avec les210# fsmonitor, hook-path et gpg-program écrite par la session d'exécuter du code avec les
175# privilèges du hook. -c commit.gpgsign=false laisse aussi ces commits de secours211# privilèges du hook. -c commit.gpgsign=false laisse aussi ces commits de secours
176# non signés sous --configure-git.212# non signés sous --configure-git.
177# credential.helper et pushurl locaux au dépôt s'appliquent toujours, ainsi que213# credential.helper et pushurl locaux au dépôt s'appliquent toujours, ainsi que
178# core.sshCommand sur un runner antérieur à v2.1.280 ; si le hook détient des identifiants214# core.sshCommand sur un runner antérieur à v2.1.280 ; lisez la note sous le script
179# que la session n'avait pas, voir la note sous le script.215# avant de fournir des identifiants à ce push.
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
191Le hook envoie avec les identifiants git disponibles dans son propre environnement sur l'hôte du runner. Sous la [posture sans identifiants dans l'image](/docs/fr/self-hosted-environments-deploy#configure-git), y compris quand le clone intégré passe par le proxy git Anthropic, il n'y en a pas, donc générez des identifiants de push de courte durée à l'intérieur du hook avant d'envoyer : échangez le jeton de session que le hook reçoit dans `CLAUDE_CODE_SESSION_ACCESS_TOKEN` avec votre propre service de jetons, en le vérifiant comme [Vérifier l'identité de la session](/docs/fr/self-hosted-environments-identity) le décrit. Quand le hook détient des identifiants que la session n'avait pas, remplacez `origin` par une URL fournie par l'opérateur et passez `-c credential.helper=` plus votre propre helper. [Configuration git dans les hooks de cycle de vie](#git-configuration-inside-lifecycle-hooks) décrit ce que la configuration écrite par la session peut encore affecter.227La ligne `GIT_ALLOW_PROTOCOL` du script limite git aux remotes HTTPS, HTTP et SSH. Si l'environnement du runner définit déjà sa propre liste `GIT_ALLOW_PROTOCOL` non vide, le script conserve cette liste.
228
229Le hook envoie avec les identifiants git disponibles dans son propre environnement sur l'hôte du runner. Sous la [posture sans identifiants dans l'image](/docs/fr/self-hosted-environments-deploy#configure-git), y compris quand le clone intégré passe par le proxy git Anthropic, il n'y en a pas, donc générez des identifiants de push de courte durée à l'intérieur du hook avant d'envoyer : échangez le jeton de session que le hook reçoit dans `CLAUDE_CODE_SESSION_ACCESS_TOKEN` avec votre propre service de jetons, en le vérifiant comme [Vérifier l'identité de la session](/docs/fr/self-hosted-environments-identity) le décrit.
230
231Traitez tous les identifiants que votre hook fournit à git comme des identifiants qu'une session peut obtenir, et générez-les de sorte qu'ils ne puissent rien faire de plus que ce push. Git dans votre hook lit des fichiers de configuration qu'une session peut écrire, et un helper d'identifiants ou un filter driver désigné dans l'un d'eux s'exécute avec les privilèges de votre hook. Les paramètres de ces fichiers peuvent aussi modifier la destination d'un push, quel que soit le remote que vous indiquez. Pour les paramètres git que le runner fixe dans votre hook et ceux qu'il laisse à ces fichiers, voir [Configuration git dans les hooks de cycle de vie](#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 Timing du hook quand le runner libère une session234 Timing du hook quand le runner libère une session
264| `CLAUDE_RUNNER_ORDER_ID` | Clé d'idempotence opaque, unique par demande de spawn et sûre pour les noms de ressources Kubernetes. Utilisez-la comme clé de déduplication de votre approvisionneur. |304| `CLAUDE_RUNNER_ORDER_ID` | Clé d'idempotence opaque, unique par demande de spawn et sûre pour les noms de ressources Kubernetes. Utilisez-la comme clé de déduplication de votre approvisionneur. |
265| `CLAUDE_RUNNER_SESSION_ID` | La session pour laquelle cette demande est. Elle se répète à chaque re-demande pour la session, donc utilisez-la pour la journalisation et l'acheminement, pas comme clé de déduplication. Vide pour les demandes de pré-réchauffage, qui démarrent un runner de secours avant toute session spécifique quand [`--min-idle`](/docs/fr/self-hosted-environments-reference#orchestrator-cli-flags) est défini, donc ne supposez pas que la variable est définie. |305| `CLAUDE_RUNNER_SESSION_ID` | La session pour laquelle cette demande est. Elle se répète à chaque re-demande pour la session, donc utilisez-la pour la journalisation et l'acheminement, pas comme clé de déduplication. Vide pour les demandes de pré-réchauffage, qui démarrent un runner de secours avant toute session spécifique quand [`--min-idle`](/docs/fr/self-hosted-environments-reference#orchestrator-cli-flags) est défini, donc ne supposez pas que la variable est définie. |
266| `CLAUDE_RUNNER_SESSION_UUID` | Le même ID de session sous la forme UUID canonique. Vide pour les demandes de pré-réchauffage. |306| `CLAUDE_RUNNER_SESSION_UUID` | Le même ID de session sous la forme UUID canonique. Vide pour les demandes de pré-réchauffage. |
267| `CLAUDE_RUNNER_ATTEMPT` | Combien de demandes de spawn cette session a eues. `0` pour les demandes de pré-réchauffage. |307| `CLAUDE_RUNNER_ATTEMPT` | Un compteur par session à utiliser pour la journalisation. Ce n'est ni un nombre de nouvelles tentatives ni un nombre de demandes. `0` pour les demandes de pré-réchauffage, bien qu'une demande pour une session puisse aussi porter `0`. |
268| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Heure du serveur à partir de l'en-tête HTTP `Date` de la réponse du sondage. Quand le hook vérifie le `exp` du JWT du bon de travail, comparez par rapport à cette valeur au lieu de l'horloge locale pour tolérer l'asymétrie. Vide quand la passerelle a omis l'en-tête. |308| `CLAUDE_RUNNER_ORDER_SERVER_TIME` | Heure du serveur à partir de l'en-tête HTTP `Date` de la réponse du sondage. Quand le hook vérifie le `exp` du JWT du bon de travail, comparez par rapport à cette valeur au lieu de l'horloge locale pour tolérer l'asymétrie. Vide quand la passerelle a omis l'en-tête. |
269| `CLAUDE_RUNNER_POOL_ID` | L'ID de l'environnement auquel le nouveau runner doit se joindre, sous la forme `ccpool_...` |309| `CLAUDE_RUNNER_POOL_ID` | L'ID de l'environnement auquel le nouveau runner doit se joindre, sous la forme `ccpool_...` |
270| `CLAUDE_RUNNER_ACCOUNT_ID` | ID balisé du compte qui a mis en attente la session, pour l'acheminement par compte, le quota ou la rétrofacturation. Vide quand indisponible, et toujours vide pour les sessions du canal Claude Tag, qu'aucun compte ne met en attente. |310| `CLAUDE_RUNNER_ACCOUNT_ID` | ID balisé du compte qui a mis en attente la session, pour l'acheminement par compte, le quota ou la rétrofacturation. Vide quand indisponible, et toujours vide pour les sessions du canal Claude Tag, qu'aucun compte ne met en attente. |
271| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email du compte qui a mis en attente la session. Vide quand indisponible. Traitez l'email comme des informations d'identification personnelle et ne le consignez pas. |311| `CLAUDE_RUNNER_ACCOUNT_EMAIL` | Email du compte qui a mis en attente la session. Vide quand indisponible. Traitez l'email comme des informations d'identification personnelle et ne le consignez pas. |
272| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL de la première source git de la session, pour l'acheminement vers un runner avec ce référentiel pré-réchauffé. Vide quand la session n'a pas de sources git. |312| `CLAUDE_RUNNER_PRIMARY_REPO_URL` | URL de la première source git de la session, pour l'acheminement vers un runner avec ce référentiel pré-réchauffé. Vide quand la session n'a pas de sources git. |
273| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Révision de la première source git de la session : branche, SHA ou tag. Vide quand non spécifié. |313| `CLAUDE_RUNNER_PRIMARY_REPO_REVISION` | Révision de la première source git de la session : branche, SHA, tag ou nom de référence complet. Vide quand non spécifié. |
274| `CLAUDE_RUNNER_REPO_SOURCES` | Tableau JSON de `{url, revision}` pour toutes les sources git de la session, pour les hooks qui acheminent sur un référentiel secondaire. Vide quand il n'y a pas de sources. |314| `CLAUDE_RUNNER_REPO_SOURCES` | Tableau JSON de `{url, revision}` pour toutes les sources git de la session, pour les hooks qui acheminent sur un référentiel secondaire. Vide quand il n'y a pas de sources. |
275| `CLAUDE_RUNNER_CORRELATION_ID` | L'ID de corrélation fourni à la création de la session, renvoyé afin que le hook puisse mapper ce bon de travail à la demande qui a créé la session. Vide quand la session n'en a pas. |315| `CLAUDE_RUNNER_CORRELATION_ID` | L'ID de corrélation fourni à la création de la session, renvoyé afin que le hook puisse mapper ce bon de travail à la demande qui a créé la session. Vide quand la session n'en a pas. |
276| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La surface client qui a créé la session, comme `web_claude_ai`, `desktop_app`, `ios` ou `scheduled_trigger`, pour l'analyse d'adoption. Non défini quand la session n'a pas de surface enregistrée ou reconnue, et pour les demandes de pré-réchauffage ; vérifiez-le avec `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, qui reste sûr sous `set -u`. |316| `CLAUDE_RUNNER_CLIENT_PLATFORM` | La surface client qui a créé la session, comme `web_claude_ai`, `desktop_app`, `ios` ou `scheduled_trigger`, pour l'analyse d'adoption. Non défini quand la session n'a pas de surface enregistrée ou reconnue, et pour les demandes de pré-réchauffage ; vérifiez-le avec `[ -n "${CLAUDE_RUNNER_CLIENT_PLATFORM:-}" ]`, qui reste sûr sous `set -u`. |
282* **Utilisez `--capacity 1` sur les runners générés** : un bon de travail lié à une session enregistre exactement un runner lié à cette session, donc une capacité plus élevée ajoute des emplacements qui ne reçoivent jamais de travail, et le runner enregistre un avertissement au démarrage.322* **Utilisez `--capacity 1` sur les runners générés** : un bon de travail lié à une session enregistre exactement un runner lié à cette session, donc une capacité plus élevée ajoute des emplacements qui ne reçoivent jamais de travail, et le runner enregistre un avertissement au démarrage.
283* **Les bons de travail de pré-réchauffage s'enregistrent sans liaison** : le runner de secours n'est pas lié à une session et revendique le travail en attente comme un runner de flotte fixe.323* **Les bons de travail de pré-réchauffage s'enregistrent sans liaison** : le runner de secours n'est pas lié à une session et revendique le travail en attente comme un runner de flotte fixe.
284 324
285Le contrat a quatre règles agnostiques de l'approvisionneur :325Le contrat a quatre règles, quelle que soit la plateforme sur laquelle votre hook effectue l'approvisionnement :
286 326
2871. **Soyez idempotent sur `CLAUDE_RUNNER_ORDER_ID`.** La redélivraison de la même demande doit générer au maximum un runner. Dérivez un nom de ressource déterministe à partir de l'ID et laissez votre plateforme rejeter le doublon. Ne clé pas sur `CLAUDE_RUNNER_SESSION_ID` à la place. Chaque re-demande pour une session porte le même ID de session avec un nouvel ID de commande, donc une charge de travail nommée ou dédupliquée par l'ID de session est créée une fois et jamais à nouveau pour cette session.3271. **Soyez idempotent sur `CLAUDE_RUNNER_ORDER_ID`.** La redélivraison de la même demande doit générer au maximum un runner. Dérivez un nom de ressource déterministe à partir de l'ID et laissez votre plateforme rejeter le doublon. Ne clé pas sur `CLAUDE_RUNNER_SESSION_ID` à la place. Chaque re-demande pour une session porte le même ID de session avec un nouvel ID de commande, donc une charge de travail nommée ou dédupliquée par l'ID de session est créée une fois et jamais à nouveau pour cette session.
2882. **Ne réessayez pas la charge de travail.** Un ID de commande signifie au maximum une charge de travail créée. Si le runner ne s'enregistre jamais, Anthropic re-demande avec un ID de commande frais après `--expected-spawn-seconds`.3282. **Ne réessayez pas la charge de travail.** Un ID de commande signifie au maximum une charge de travail créée. Si le runner ne s'enregistre jamais, Anthropic re-demande avec un ID de commande frais après `--expected-spawn-seconds`.
2893. **Utilisez le contrat du code de sortie.** Sortie 0 signifie soumis. Sortie 1 signifie échec réessayable ; la session recule et est re-proposée. Sortie 2 ou supérieure signifie non-réessayable ; la session est bloquée du spawning à nouveau jusqu'à ce qu'un [Owner](/docs/fr/cloud-environments#organization-shared-environments) sélectionne **Retry** sur elle dans l'onglet **Activity** de l'environnement. Sur une sortie non-zéro, la queue du stderr du hook apparaît là comme la raison de l'échec, donc écrivez l'erreur exploitable sur stderr et jamais les secrets. Pour une demande de pré-réchauffage il n'y a pas de session à échouer : l'orchestrateur enregistre une sortie non-zéro localement uniquement, et le serveur re-demande le spawn après le bail.3293. **Utilisez le contrat du code de sortie.** Sortez avec le statut qui correspond au résultat :
2904. **Définissez `--expected-spawn-seconds` à au moins votre temps de démarrage p99.** C'est le bail côté serveur. Toutes les répliques d'orchestrateur doivent utiliser la même valeur.330
331 * **Sortie 0** : soumis.
332 * **Sortie 1** : échec pouvant être réessayé. La session recule et est re-proposée.
333 * **Sortie 2 ou supérieure** : échec ne pouvant pas être réessayé. La session est empêchée de générer un nouveau spawn jusqu'à ce qu'un utilisateur lui envoie un nouveau message ou qu'un [Owner](/docs/fr/cloud-environments#organization-shared-environments) sélectionne **Retry** sur elle dans l'onglet **Activity** de l'environnement.
334
335 Sur une sortie non nulle, la fin du stderr du hook apparaît dans l'onglet **Activity** comme raison de l'échec, donc écrivez l'erreur exploitable sur stderr et n'y écrivez jamais de secrets. Dans un hook shell, [gardez les échecs transitoires réessayables](#keep-transient-failures-retryable-in-a-shell-hook).
336
337 Une demande de pré-réchauffage n'a pas de session à faire échouer : l'orchestrateur consigne une sortie non nulle localement uniquement, et le serveur re-demande le spawn après l'expiration du bail `--expected-spawn-seconds`.
3384. **Définissez `--expected-spawn-seconds` à au moins votre temps p99 entre la demande de spawn et l'enregistrement du runner.** Mesurez à partir du moment où l'orchestrateur reçoit la demande de spawn, et incluez toute attente de capacité sur votre plateforme ainsi que le temps de démarrage. Cette valeur est le bail côté serveur, et le bon de travail expire avec lui, donc un runner dont la charge de travail prend plus de temps ne peut pas s'enregistrer. Toutes les répliques d'orchestrateur doivent utiliser la même valeur.
291 339
292Tout ce que le hook écrit sur stdout ou stderr apparaît dans le journal de l'orchestrateur avec les identifiants automatiquement supprimés. Si les sessions restent en attente, vérifiez le corps `/healthz` de l'orchestrateur pour les compteurs de file d'attente, puis ouvrez l'onglet **Activity** de votre environnement sur la [page d'administration **Cloud environments**](https://claude.ai/admin-settings/cloud-environments) : développez une session échouée là pour son erreur de spawn, et sélectionnez **Retry** pour la re-demander.340Tout ce que le hook écrit sur stdout ou stderr apparaît dans le journal de l'orchestrateur avec les identifiants automatiquement supprimés. Si les sessions restent en attente, vérifiez le corps `/healthz` de l'orchestrateur pour les compteurs de file d'attente, puis ouvrez l'onglet **Activity** de votre environnement sur la [page d'administration **Cloud environments**](https://claude.ai/admin-settings/cloud-environments) : développez une session échouée là pour son erreur de spawn, et sélectionnez **Retry** pour la re-demander.
293 341
294Une session qui reste en attente sans erreur de spawn dans l'onglet **Activity** peut signifier que le hook est clé sur l'ID de session. Pour confirmer, vérifiez si votre plateforme a une charge de travail pour la première demande de spawn de cette session et aucune pour les re-demandes. Si c'est le cas, clé la charge de travail sur `CLAUDE_RUNNER_ORDER_ID` à la place.342Une session qui reste en attente sans erreur de spawn dans l'onglet **Activity** peut signifier que le hook est clé sur l'ID de session. Pour confirmer, vérifiez si votre plateforme a une charge de travail pour la première demande de spawn de cette session et aucune pour les re-demandes. Si c'est le cas, clé la charge de travail sur `CLAUDE_RUNNER_ORDER_ID` à la place.
295 343
344<h4 id="keep-transient-failures-retryable-in-a-shell-hook">
345 Garder les échecs transitoires réessayables dans un hook shell
346</h4>
347
348Dans un hook shell qui utilise `set -e`, un échec qu'une nouvelle tentative aurait pu résoudre peut bloquer la session. Le hook s'arrête à la commande en échec et sort avec le statut propre à cette commande, et l'orchestrateur applique le contrat du code de sortie à ce statut. De nombreux échecs renvoient un statut de 2 ou plus, comme `127` quand une commande n'est pas installée et `22` de `curl --fail` sur une erreur HTTP, de sorte qu'ils bloquent la session dès son premier échec.
349
350Une session que le hook a déjà bloquée reste bloquée jusqu'à ce qu'un utilisateur lui envoie un nouveau message ou qu'un [Owner](/docs/fr/cloud-environments#organization-shared-environments) sélectionne **Retry** sur elle dans l'onglet **Activity** de l'environnement.
351
352Pour transformer un tel échec en sortie 1, placez ces lignes directement sous la ligne `#!` du hook, au-dessus de tout ce qui peut échouer :
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
360Ces lignes modifient le comportement du reste du hook, donc vérifiez-le pour chacun de ces motifs après les avoir ajoutées :
361
362* **`exit 2` ou supérieur isolé** : avec le trap défini, il devient une sortie 1. Pour une erreur qu'aucune nouvelle tentative ne peut corriger, appelez plutôt `permanent` avec la raison, comme `permanent "namespace claude-runners does not exist"`. Appelez-le dans le shell principal, pas à l'intérieur de `$( )`, `( )` ou d'un pipe.
363* **`exec`** : ne commencez pas la dernière commande du hook par `exec`, car `exec` remplace le shell et le trap ne s'exécute pas.
364* **Second trap `EXIT`** : un second `trap ... EXIT` remplace le premier, donc fusionnez les deux en un seul trap. Placez vos commandes de nettoyage directement après `rc=$?;` et terminez chacune par `|| true;`. Le nettoyage s'exécute alors en cas d'échec comme en cas de succès, et une commande de nettoyage en échec ne définit pas le statut de sortie du hook. Ce trap fusionné illustre la forme, `your-cleanup-command` représentant votre propre commande :
365
366 ```bash theme={null}
367 trap 'rc=$?; your-cleanup-command || true; [ "$rc" -eq 0 ] || [ -n "${PERMANENT:-}" ] || exit 1' EXIT
368 ```
369* **Commandes autorisées à échouer** : si le hook n'utilisait pas `set -e` auparavant, il s'arrête désormais à la première commande qui renvoie une valeur non nulle, comme une recherche qui ne trouve rien ou une soumission en double que votre plateforme rejette. Si le hook agit sur le résultat, faites de cette commande la condition d'un `if`. S'il ignore le résultat, faites suivre la commande de `|| true`.
370
371Pour confirmer que le trap fonctionne, ajoutez directement sous la ligne `trap` une ligne qui appelle une commande inexistante, comme `no-such-command`. Exécutez le fichier du hook depuis votre shell et vérifiez que `echo $?` affiche `1`, puis supprimez la ligne.
372
296<h2 id="send-model-requests-to-bedrock-or-agent-platform">373<h2 id="send-model-requests-to-bedrock-or-agent-platform">
297 Envoyer les requêtes de modèle vers Bedrock ou Agent Platform374 Envoyer les requêtes de modèle vers Bedrock ou Agent Platform
298</h2>375</h2>
381Une session qui envoie des requêtes de modèle à Amazon Bedrock ou à Agent Platform de Google Cloud diffère d'une session sur l'API Anthropic sur les points suivants :458Une session qui envoie des requêtes de modèle à Amazon Bedrock ou à Agent Platform de Google Cloud diffère d'une session sur l'API Anthropic sur les points suivants :
382 459
383* **Stratégie depuis claude.ai** : les [paramètres gérés par le serveur](/docs/fr/server-managed-settings) n'atteignent pas ces sessions. Les stratégies d'organisation qu'un Owner définit dans les paramètres d'administration de Claude Code ne les atteignent pas non plus ; Claude Code ne les applique donc pas à l'intérieur de la session. Placez les règles sur lesquelles vous comptez dans le [fichier de paramètres gérés](/docs/fr/managed-settings#delivery-mechanisms) de l'image du runner.460* **Stratégie depuis claude.ai** : les [paramètres gérés par le serveur](/docs/fr/server-managed-settings) n'atteignent pas ces sessions. Les stratégies d'organisation qu'un Owner définit dans les paramètres d'administration de Claude Code ne les atteignent pas non plus ; Claude Code ne les applique donc pas à l'intérieur de la session. Placez les règles sur lesquelles vous comptez dans le [fichier de paramètres gérés](/docs/fr/managed-settings#delivery-mechanisms) de l'image du runner.
461* **Skills du compte** : ces sessions ne téléchargent pas les skills activés pour le compte claude.ai d'une personne. Consultez [Comment la configuration de chaque session est assemblée](#how-each-session’s-config-is-assembled).
384* **Fichiers** : les fichiers que les utilisateurs joignent à une session dans claude.ai ou dans l'application mobile ou de bureau ne l'atteignent pas, et Claude ne peut pas renvoyer de fichiers avec l'[outil `SendUserFile`](/docs/fr/tools-reference). Placez plutôt les fichiers d'entrée dans le dépôt ou sur le runner.462* **Fichiers** : les fichiers que les utilisateurs joignent à une session dans claude.ai ou dans l'application mobile ou de bureau ne l'atteignent pas, et Claude ne peut pas renvoyer de fichiers avec l'[outil `SendUserFile`](/docs/fr/tools-reference). Placez plutôt les fichiers d'entrée dans le dépôt ou sur le runner.
385* **Sélection du modèle** : le plan de contrôle d'Anthropic envoie le modèle de chaque session, et lorsqu'une session démarre sans modèle, Claude Code utilise son modèle par défaut pour le fournisseur. Le runner supprime `ANTHROPIC_MODEL` et `ANTHROPIC_DEFAULT_MODEL` de l'environnement qu'il transmet aux sessions. Les exemples des pages des fournisseurs définissent `ANTHROPIC_MODEL`, mais dans l'environnement du runner, aucune de ces variables n'a d'effet. Les variables par famille décrites dans Épingler les versions de modèle pour [Amazon Bedrock](/docs/fr/amazon-bedrock#4-pin-model-versions) et [Agent Platform](/docs/fr/google-vertex-ai#5-pin-model-versions) atteignent bien les sessions. Elles déterminent ce vers quoi un alias comme `opus` est résolu, et non ce vers quoi un ID de modèle complet est résolu.463* **Sélection du modèle** : le plan de contrôle d'Anthropic envoie le modèle de chaque session, et lorsqu'une session démarre sans modèle, Claude Code utilise son modèle par défaut pour le fournisseur. Vous ne pouvez pas choisir le modèle avec `ANTHROPIC_MODEL` ou `ANTHROPIC_DEFAULT_MODEL` dans l'environnement du runner, mais vous pouvez épingler ce vers quoi un alias est résolu :
464 * **`ANTHROPIC_MODEL` et `ANTHROPIC_DEFAULT_MODEL`** : le runner les supprime de l'environnement qu'il transmet aux sessions, même si les exemples des pages des fournisseurs définissent `ANTHROPIC_MODEL`.
465 * **Variables d'épinglage par famille** : les variables décrites dans Épingler les versions de modèle pour [Amazon Bedrock](/docs/fr/amazon-bedrock#4-pin-model-versions) et [Agent Platform](/docs/fr/google-vertex-ai#5-pin-model-versions) atteignent bien les sessions. Elles déterminent ce vers quoi un alias comme `opus` est résolu, et non ce vers quoi un ID de modèle complet est résolu.
386* **Modèles que votre compte ne fournit pas** : une session peut échouer sur un message avec une erreur qui nomme le modèle. Activez les modèles que vos développeurs peuvent choisir, le modèle d'arrière-plan décrit dans Épingler les versions de modèle, ainsi que le modèle de classifieur utilisé par le [mode auto](/docs/fr/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry). Sur Amazon Bedrock, autorisez chacun d'eux dans votre stratégie.466* **Modèles que votre compte ne fournit pas** : une session peut échouer sur un message avec une erreur qui nomme le modèle. Activez les modèles que vos développeurs peuvent choisir, le modèle d'arrière-plan décrit dans Épingler les versions de modèle, ainsi que le modèle de classifieur utilisé par le [mode auto](/docs/fr/permission-modes#enable-auto-mode-on-bedrock-agent-platform-or-foundry). Sur Amazon Bedrock, autorisez chacun d'eux dans votre stratégie.
387* **Recherche web et mode rapide** : la [recherche web](/docs/fr/tools-reference#websearch-tool-behavior) n'est pas disponible sur Amazon Bedrock, et le [mode rapide](/docs/fr/fast-mode) n'est disponible sur aucun des deux fournisseurs. Pour les autres fonctionnalités qui varient selon le fournisseur, consultez [Fonctionnalités de la CLI qui varient selon le fournisseur](/docs/fr/feature-availability#cli-capabilities-that-vary-by-provider).467* **Recherche web et mode rapide** : la [recherche web](/docs/fr/tools-reference#websearch-tool-behavior) n'est pas disponible sur Amazon Bedrock, et le [mode rapide](/docs/fr/fast-mode) n'est disponible sur aucun des deux fournisseurs. Pour les autres fonctionnalités qui varient selon le fournisseur, consultez [Fonctionnalités de la CLI qui varient selon le fournisseur](/docs/fr/feature-availability#cli-capabilities-that-vary-by-provider).
388 468
411 491
412Les sessions héritent de l'environnement du runner ; définissez donc [`ENABLE_TOOL_SEARCH`](/docs/fr/mcp#scale-with-mcp-tool-search) à ce niveau pour contrôler la recherche d'outils MCP pour chaque session lancée par un runner ; la page MCP décrit les valeurs possibles.492Les sessions héritent de l'environnement du runner ; définissez donc [`ENABLE_TOOL_SEARCH`](/docs/fr/mcp#scale-with-mcp-tool-search) à ce niveau pour contrôler la recherche d'outils MCP pour chaque session lancée par un runner ; la page MCP décrit les valeurs possibles.
413 493
494<a id="connection-timing" />
495
496<h3 id="wait-for-mcp-servers-before-the-first-turn">
497 Attendre les serveurs MCP avant le premier tour
498</h3>
499
500Une session auto-hébergée attend brièvement les serveurs MCP qui sont encore en cours de connexion, à deux moments distincts. Un serveur qui manque une attente voit ses outils absents au début du premier tour ; ils deviennent disponibles plus tard sans aucune action de votre part. Les deux attentes sont les suivantes :
501
502* **Démarrage de la session** : avant que la liste des outils ne soit établie pour la première fois, la session attend par défaut jusqu'à 5 secondes un serveur HTTP ou SSE dont l'entrée définit [`alwaysLoad: true`](/docs/fr/mcp#exempt-a-server-from-deferral), ou tous les serveurs lorsque vous définissez [`MCP_CONNECTION_NONBLOCKING=0`](/docs/fr/env-vars) dans l'environnement du runner. Sinon, les serveurs HTTP et SSE se connectent en arrière-plan. Pendant cette attente, la session s'initialise plus lentement. [`MCP_CONNECT_TIMEOUT_MS`](/docs/fr/env-vars) modifie la valeur par défaut de 5 secondes.
503* **Premier tour** : après l'arrivée du message, le premier tour attend jusqu'à 2 secondes les serveurs stdio qui sont encore en cours de connexion. Pendant cette attente, la première réponse est plus lente. Pour modifier la durée de cette attente, définissez [`CLAUDE_CODE_MCP_STARTUP_WAIT_MS`](/docs/fr/env-vars) dans l'environnement du runner. Cela ne modifie pas les serveurs couverts par l'attente. Nécessite Claude Code v2.1.274 ou une version ultérieure.
504
505`claude mcp add` n'a pas de flag `alwaysLoad`. Pour définir cette clé, ajoutez plutôt le serveur avec `claude mcp add-json`, qui la reçoit dans le JSON du serveur et l'écrit dans `.claude.json`. Dans votre 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
511Si les outils d'un serveur n'apparaissent pas non plus lors des tours suivants, vérifiez si le serveur a bien atteint la session, comme décrit dans [Serveurs MCP](#mcp-servers).
512
414<h3 id="turn-off-built-in-session-tools">513<h3 id="turn-off-built-in-session-tools">
415 Désactiver les outils de session intégrés514 Désactiver les outils de session intégrés
416</h3>515</h3>
578 677
579Définissez `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` pour semer à partir d'un chemin différent, ou pointez-le vers un répertoire vide pour désactiver le semis.678Définissez `SELF_HOSTED_RUNNER_HOST_CONFIG_DIR` pour semer à partir d'un chemin différent, ou pointez-le vers un répertoire vide pour désactiver le semis.
580 679
581Le `.claude/settings.json` commité dans le dépôt se superpose comme paramètres du projet. Dans une session avec plusieurs dépôts, [le fichier d'au plus un dépôt prend effet](#repository-settings-in-sessions-with-several-repositories). Les sessions lisent également [`managed-settings.json`](/docs/fr/settings#where-settings-live) à partir du chemin système standard dans votre image runner. Que ses clés s'appliquent aux côtés des [paramètres gérés par le serveur](/docs/fr/server-managed-settings) suit [comment Claude Code combine les sources gérées](/docs/fr/managed-settings#how-claude-code-combines-managed-sources) : par défaut, quand votre organisation livre des clés gérées par le serveur, les sessions ignorent le fichier de l'image runner à part les [clés que Claude Code lit à partir de chaque source d'administration](/docs/fr/managed-settings#keys-read-from-every-admin-source), comme le bloc `env`, les verrous de sandbox, les chemins binaires de sandbox et `forceRemoteSettingsRefresh`. Voir [priorité des paramètres](/docs/fr/settings#settings-precedence).680Les sessions lisent également ces fichiers de paramètres :
681
682* **Paramètres du projet** : un `.claude/settings.json` commité dans le dépôt se superpose à la ligne de base au niveau utilisateur. Dans une session avec plusieurs dépôts, [le fichier d'au plus un dépôt prend effet](#repository-settings-in-sessions-with-several-repositories).
683* **Paramètres gérés** : les sessions lisent [`managed-settings.json`](/docs/fr/settings#where-settings-live) à partir du chemin système standard dans votre image runner. Pour savoir si ses clés s'appliquent aux côtés des [paramètres gérés par le serveur](/docs/fr/server-managed-settings), voir [comment Claude Code combine les sources gérées](/docs/fr/managed-settings#how-claude-code-combines-managed-sources).
684
685Pour l'ordre dans lequel ces sources s'appliquent, voir [priorité des paramètres](/docs/fr/settings#settings-precedence).
582 686
583Quand le plan de contrôle d'Anthropic fournit une session avec des [hooks Claude Code](/docs/fr/hooks), le runner les installe aux côtés, pas par-dessus, votre propre configuration. Nécessite Claude Code v2.1.229 ou ultérieur.687Quand le plan de contrôle d'Anthropic fournit une session avec des [hooks Claude Code](/docs/fr/hooks), le runner les installe aux côtés, pas par-dessus, votre propre configuration. Nécessite Claude Code v2.1.229 ou ultérieur.
584 688
586* **Qui les crée** : le plan de contrôle remplit les scripts à partir de constantes fixes dans son propre déploiement, jamais à partir d'entrées par session ou tierces.690* **Qui les crée** : le plan de contrôle remplit les scripts à partir de constantes fixes dans son propre déploiement, jamais à partir d'entrées par session ou tierces.
587* **Ce qui les gouverne toujours** : les hooks livrés via `--settings` entrent dans la configuration de hook fusionnée ordinaire, pas le niveau géré, donc vos paramètres gérés s'appliquent toujours. `disableAllHooks` les désactive, et ils ne font pas partie des catégories que [`allowManagedHooksOnly`](/docs/fr/settings-reference#allowmanagedhooksonly) garde chargées.691* **Ce qui les gouverne toujours** : les hooks livrés via `--settings` entrent dans la configuration de hook fusionnée ordinaire, pas le niveau géré, donc vos paramètres gérés s'appliquent toujours. `disableAllHooks` les désactive, et ils ne font pas partie des catégories que [`allowManagedHooksOnly`](/docs/fr/settings-reference#allowmanagedhooksonly) garde chargées.
588 692
693Quand une personne démarre sa propre session, Claude Code télécharge aussi les [skills activés pour son compte claude.ai](/docs/fr/skills#skills-in-cowork-and-cloud-sessions) dans le répertoire de configuration de cette session. Une exécution de [routine](/docs/fr/routines) ne reçoit pas les skills de son propriétaire, et une session qui [envoie des requêtes de modèle à Bedrock ou Agent Platform](#send-model-requests-to-bedrock-or-agent-platform) n'en télécharge aucun. Pour un skill dont ces sessions ont besoin, commitez-le dans le `.claude/skills/` du dépôt ou ajoutez-le à votre image runner.
694
589En dehors des sessions [Claude Tag](https://claude.com/docs/claude-tag/overview), une session dans un environnement auto-hébergé s'exécute avec la [mémoire automatique](/docs/fr/memory#auto-memory) désactivée par défaut. Pour les instructions qui doivent persister d'une session à l'autre, utilisez le `CLAUDE.md` de votre image runner ou du dépôt.695En dehors des sessions [Claude Tag](https://claude.com/docs/claude-tag/overview), une session dans un environnement auto-hébergé s'exécute avec la [mémoire automatique](/docs/fr/memory#auto-memory) désactivée par défaut. Pour les instructions qui doivent persister d'une session à l'autre, utilisez le `CLAUDE.md` de votre image runner ou du dépôt.
590 696
591L'instantané du `~/.claude/` de l'hôte pris par le runner exclut le répertoire `projects/`. L'emplacement de stockage par défaut de la mémoire automatique se trouve sous ce répertoire. Si vous y placez des fichiers de mémoire, le runner ne les sème pas dans les sessions, et ils n'activent pas la mémoire automatique.697L'instantané du `~/.claude/` de l'hôte pris par le runner exclut le répertoire `projects/`. L'emplacement de stockage par défaut de la mémoire automatique se trouve sous ce répertoire. Si vous y placez des fichiers de mémoire, le runner ne les sème pas dans les sessions, et ils n'activent pas la mémoire automatique.
