Aller au contenu

Docs · Internals

Comment un agent qui lance des agents reste dans ses limites

Une session ouverte par un agent, comme un sous-agent ou une tâche déléguée, reçoit un jeton lié et révocable, et une enveloppe qui ne peut que restreindre ce que son parent a le droit de faire.

Ce que ça fait

Chaque session d'agent reçoit un jeton signé, lié à cette session, avec un plafond de permissions et un profil d'outils. Le jeton ne vaut que tant qu'il est enregistré, et fermer la session le révoque.

Certaines routes sont réservées à un humain (configuration, providers, rôles, politique de modèle, réponses aux permissions), et un agent n'a pas de WebSocket.

Une session enfant ne peut jamais être plus permissive que son parent : même projet et même espace de travail, dossiers dans ceux du parent, profondeur 1, au plus 4 enfants vivants.

Le schéma

Jeton de session, contrôles de requête et enveloppe d'une session enfantSchéma de flux en trois parties. D'abord, un jeton de session est émis avec une portée signée, enregistré dans une liste d'autorisation en mémoire et révoqué à la fermeture de la session. Ensuite, chaque requête portant un jeton d'agent est contrôlée dans l'ordre : le jeton doit être encore enregistré sinon 401 ; la route du ticket WebSocket est refusée en 403 ; les mutations réservées aux humains sont refusées en 403 ; les routes derrière des outils que le profil retient sont refusées avec tool_not_in_profile. Enfin, l'appelant est identifié depuis le jeton signé, puis l'enveloppe de l'enfant est contrôlée : profondeur, nombre d'enfants vivants, plafond de permissions, dossiers, projet et espace de travail, et pour finir le mode de permission, qui ne peut que se restreindre. La session enfant est créée et note son parent.on closenoyesyesnoyes (not GET)noyesnoyesnoyesnonoyesnoyesminted at launchsigned scope: session, ceiling, tool profileunique jtiagent_tokens::registerin-memory allow-lista new token replaces the old onesclose_session revokes the tokenjti still registered?401WebSocket ticket route?403: an agent gets no WebSockethuman-only mutation?config, providers, roles, model policy,permission answers403: reserved to a humanroute behind a tool the profile withholds?403 tool_not_in_profileclaims injectedreads and day-to-day work stay openidentify_callerbound agent token: parent and ceiling from the signed token(X-Session-Id header ignored)unbound agent token: 403 envelope_unbound_tokenother token: human, no envelopeparent already a child?403 envelope_depth_exceededdepth 14 or more live children?403 envelope_too_many_childrenceiling = min(live mode, signed ceiling)cwd and add_dirs inside the parent's?403 envelope_cwd_outside_parentenvelope_add_dir_outside_parentsame project and workspace?403 envelope_project_mismatchenvelope_workspace_mismatchpermission_mode = restrict(ceiling, requested)plan < default < acceptEdits < auto < bypassPermissionschild session createdspawned_by records the parent

Fais glisser pour te déplacer. Pince, Ctrl + molette ou les touches + et - pour zoomer ; flèches pour bouger ; 0 ou double-clic pour ajuster. Choisis un nœud pour allumer ses liens.

DézoomerZoomerPlein écran
Redessiné depuis le diagramme vérifié po-spawn-envelope (vérifié 878281ca). Les libellés sont les noms utilisés dans le code.
Description textuelle du schéma

Schéma de flux en trois parties. D'abord, un jeton de session est émis avec une portée signée, enregistré dans une liste d'autorisation en mémoire et révoqué à la fermeture de la session. Ensuite, chaque requête portant un jeton d'agent est contrôlée dans l'ordre : le jeton doit être encore enregistré sinon 401 ; la route du ticket WebSocket est refusée en 403 ; les mutations réservées aux humains sont refusées en 403 ; les routes derrière des outils que le profil retient sont refusées avec tool_not_in_profile. Enfin, l'appelant est identifié depuis le jeton signé, puis l'enveloppe de l'enfant est contrôlée : profondeur, nombre d'enfants vivants, plafond de permissions, dossiers, projet et espace de travail, et pour finir le mode de permission, qui ne peut que se restreindre. La session enfant est créée et note son parent.

Lecture guidée

  1. Étape 1. Émettre

    Au lancement, le backend signe un jeton dont la portée nomme la session, son plafond de permissions et son profil d'outils, avec un identifiant unique.

  2. Étape 2. Enregistrer

    L'identifiant entre dans une liste d'autorisation en mémoire. Un nouveau jeton pour une session remplace les précédents, et un jeton émis avant un redémarrage est inconnu, donc refusé.

  3. Étape 3. Contrôler chaque requête

    L'identifiant est-il encore enregistré ? Sinon, 401. Est-ce la route du ticket WebSocket ? 403 : un agent n'a pas de socket. Est-ce une mutation réservée à un humain, hors lecture ? 403. La route est-elle derrière un outil que le profil retient ? 403 tool_not_in_profile.

  4. Étape 4. Les profils sont des listes blanches

    Le profil restreint est une liste d'outils autorisés. En REST le défaut est de refuser : seuls les préfixes de routes des outils autorisés sont ouverts, et la suite de tests échoue si une route n'est pas classée. Les routes du coffre lui sont fermées. Les providers autres que Claude Code reçoivent toujours le profil restreint.

  5. Étape 5. Qui demande ?

    Le parent vient du jeton signé, et l'en-tête X-Session-Id est ignoré. Un jeton d'agent sans session est refusé (envelope_unbound_token). Tout autre jeton est un humain, sans enveloppe. Ce n'est que lorsque l'authentification est désactivée que l'en-tête nomme le parent, comme un indice et non comme une frontière.

  6. Étape 6. L'enveloppe

    Dans l'ordre : le parent est-il déjà un enfant (envelope_depth_exceeded), y a-t-il déjà 4 enfants vivants (envelope_too_many_children), le plafond est le plus bas du mode vivant et du plafond signé, les dossiers doivent être dans ceux du parent, le projet et l'espace de travail doivent correspondre, et le mode de permission est celui demandé restreint par le plafond (plan, default, acceptEdits, auto, bypassPermissions, du moins au plus permissif).

  7. Étape 7. Délégation et portée

    Déléguer une tâche demande bypassPermissions mais est borné par le plafond : une session en mode ask ne peut pas déléguer à un enfant bypass. Un agent ne peut écrire que dans les sessions qu'il a lui-même lancées.

  8. Étape 8. Sous-agents natifs

    Le moteur natif n'offre son outil Agent qu'à une session native locale qui n'a pas été lancée elle-même. Un appel Agent tourne comme une session enfant sous l'enveloppe ci-dessus, et cet enfant est une session de profondeur 1 à laquelle AskUserQuestion est refusé : il ne peut pas te poser de question. Un agent ACP n'a pas de sous-agents.

Pourquoi c'est conçu ainsi

Signé, pas affirmé

Le parent et le plafond viennent du jeton signé, pas de ce que dit l'appelant. Un en-tête est une déclaration, une signature est une preuve.

La révocation est immédiate

Une entrée de la liste d'autorisation disparaît à la fermeture de la session. Un jeton qui ne ferait qu'expirer resterait utilisable jusqu'à son échéance.

Restreindre seulement

Chaque contrôle ne peut que réduire ce que l'enfant a le droit de faire. Il n'existe aucun chemin où lancer une session élargit les permissions.

Les nouveaux outils sont fermés par défaut

Comme le profil restreint est une liste blanche et que les routes sont refusées tant qu'elles ne sont pas classées, un outil ajouté demain est retenu jusqu'à ce que quelqu'un décide de l'ouvrir.

Ce qui n'est pas établi

  • Non établi : il n'y a pas de test de bout en bout avec un vrai CLI ; les règles sont testées sur leurs fonctions et sur le middleware. Un budget de l'enfant égal au reste du parent, l'annulation en cascade et le coût des descendants ne sont pas encore écrits.