Comment permettre à Codex CLI de confier une tâche à un agent, une équipe ou une boucle osFoundry

À la fin, Codex CLI pourra confier le travail qu'il ne devrait pas faire lui-même à une session osFoundry : une session d'agent, une session d'équipe ou une boucle (loop). Il envoie un objectif, un résumé de ce qu'il sait déjà et le résultat qu'il attend en retour. Le propriétaire de la session reçoit une notification et clique sur Accept and run (accepter et lancer) ou sur Decline (refuser). Une fois l'exécution terminée, Codex lit le résultat dans la même session de terminal et continue. Si vous lui donnez plutôt une place de Runner, il peut lancer lui-même une exécution bornée, sans aucun clic.

Qui fait quoi

	Codex CLI	osFoundry
Connexion	Votre propre connexion Codex. Codex détient le jeton OAuth osFoundry	Approuve la connexion une seule fois, pour un workspace et les scopes que vous cochez
Ce à quoi il a accès	Les sessions auxquelles il a été invité, via sept outils *_session_*	C'est la place qui décide : Viewer lit, Contributor publie des notes et propose des handoffs, Runner peut en plus demander des exécutions
Qui fait le travail	Codex continue de travailler dans votre dépôt	La session tourne sur son propre agent runtime, avec ses propres agents, outils et réglages de modèle
Qui valide	Codex vous demande avant chaque outil d'écriture (default_tools_approval_mode = "writes")	Un handoff attend le Accept and run du propriétaire de la session. Une place de Runner vaut approbation permanente pour request_session_run
Durée de l'exécution	max_rounds de 1 à 10 dans l'appel	Affiché au propriétaire sous la forme "Up to N rounds on your agent runtime"
Ce qui revient	Statut et résultat des tâches lancées par cette connexion, et les notes qui lui sont adressées	L'analyse interne des agents de la session reste dans osFoundry

Mise en place

1. Créer la connexion

Dans osFoundry, cliquez sur l'icône de clé dans l'en-tête et ouvrez l'onglet Connected ("Connected agents"). Sous "Connect in three steps", réglez Assistant sur Other MCP client, donnez un nom d'affichage comme Codex CLI et cliquez sur Add assistant. Le propriétaire verra ce nom sur chaque handoff, choisissez donc un nom qu'il reconnaîtra.

Exemple : L'onglet Connected agents avec une connexion Codex CLI

2. Ajouter le serveur à Codex, avec le scope d'exécution

codex mcp add osfoundry --url https://api.osfoundry.io/api/v1/external-mcp

Ouvrez ensuite ~/.codex/config.toml et réduisez la table à ce dont ce travail a besoin :

[mcp_servers.osfoundry]
url = "https://api.osfoundry.io/api/v1/external-mcp"
scopes = ["osfoundry:read", "osfoundry:write", "osfoundry:run"]
default_tools_approval_mode = "writes"
enabled_tools = [
  "list_granted_resources",
  "list_project_resources",
  "read_session_state",
  "read_session_task_result",
  "read_session_mail",
  "post_session_note",
  "propose_session_handoff",
  "cancel_session_handoff",
  "request_session_run",
]

osfoundry:run est le scope derrière request_session_run. Retirez-le si Codex ne doit jamais faire que proposer. Les outils de handoff et de notes ont besoin de osfoundry:write, les trois outils de lecture de osfoundry:read. Avec "writes", Codex demande confirmation avant les quatre outils qui ne sont pas marqués en lecture seule, et lance les outils de lecture sans demander.

3. Se connecter

codex mcp login osfoundry

Le navigateur ouvre la page "Connect an agent" d'osFoundry. Avec les scopes ci-dessus, "Requested capabilities" affiche trois lignes. La troisième est "Run sessions where you grant a runner role". Choisissez le workspace, sélectionnez "Use pending: Codex CLI", cochez la case d'approbation et cliquez sur Connect.

4. Ajouter la connexion au projet qui contient la session

De retour dans l'onglet Connected, la connexion affiche "Connected." Sous Projects, choisissez le projet et cliquez sur Add to project. La connexion voit alors les sessions éligibles du projet. Elle ne peut encore écrire dans aucune.

Exemple : La section Projects avec un projet ajouté

5. Lui donner une place dans la session

Plus bas se trouve "Agent, Team, and Loop sessions". La ligne d'aide dit tout : "Invite it to a session as Contributor to post notes and propose handoffs, or Runner to also request runs. A handoff still needs the session owner's approval."

Agent, Team, and Loop sessions
  [ Team session ▾ ]  [ Release desk ▾ ]  [ Contributor ▾ ]  [ Save role ]

Exemple : La section Agent, Team, and Loop sessions avec Codex CLI en Contributor dans une session d’équipe

La liste ne propose que les sessions des projets auxquels cette connexion a été ajoutée. Choisissez le type, la session et un rôle, puis cliquez sur Save role. Commencez par Contributor. Enregistrer plus tard Runner pour la même session remplace le rôle.

Une exécution réelle

Codex n'est pas installé sur la machine où cet article a été écrit, la session ci-dessous est donc un exemple simulé. Les noms d'outils et d'arguments sont ceux que renvoie le serveur réel dans tools/list, avec le préfixe mcp__osfoundry__ que Codex ajoute aux outils MCP. Le dépôt, la session et toutes les valeurs sont du contenu de démonstration.

Example (simulated)

> The CSV export fix is merged. Hand the customer note and the KB update
  to the osFoundry Release desk team, then tell me what they wrote.

• mcp__osfoundry__list_granted_resources {}
  ← 1 project: "Billing v2"
• mcp__osfoundry__list_project_resources {"project_id": "…", "resource_type": "team_session",
      "search": "release"}
  ← team_session "Release desk"
• mcp__osfoundry__propose_session_handoff {
      "session_type": "team_session", "session_id": "…",
      "goal": "Write the customer note for the CSV export fix and update the KB article on exports.",
      "context_summary": "Exports over 10k rows were cut at 10,000. Fixed in PR #212 (streams rows, no cap). Affects plans with scheduled exports. No data was lost; re-running an export now returns all rows.",
      "requested_output": "Draft note (<120 words) and the KB article diff, for review.",
      "max_rounds": 4, "idempotency_key": "codex-csv-212-note"}
  [Codex asks: allow this tool call? → yes]
  ← handoff pending owner review

  (in osFoundry the owner opens "Codex CLI requests a handoff" → Review handoff
   → Handoffs → Outside assistant requests → Accept and run)

• mcp__osfoundry__read_session_state {"session_type": "team_session", "session_id": "…"}
  ← running, recent task "Requested by an outside assistant"
• mcp__osfoundry__read_session_task_result {"session_type": "team_session",
      "session_id": "…", "task_id": "…"}
  ← completed: draft note + KB diff
• mcp__osfoundry__post_session_note {"session_type": "team_session", "session_id": "…",
      "subject": "Thanks, one correction",
      "body": "The fix shipped in 3.18.2, not 3.18.1.", "idempotency_key": "codex-csv-212-fix"}
  [Codex asks: allow this tool call? → yes]

The Release desk drafted a 96-word note and a KB diff that replaces the
"exports are capped at 10,000 rows" paragraph. I posted a version
correction back to the session.

Côté propriétaire, c'est rapide. La notification indique "Codex CLI requests a handoff" avec "Review the request in Release desk." et un bouton Review handoff. Il ouvre l'onglet Handoffs de la session. Sous "Outside assistant requests", l'objectif s'affiche en entier, "Context and expected output" se déplie, et la ligne "Up to 4 rounds on your agent runtime" indique jusqu'où l'exécution peut aller. Accept and run la met en file d'attente ("Handoff accepted and run queued"). Decline y met fin.

Exemple : La notification Codex CLI requests a handoff et son bouton Review handoff

Exemple : Une demande d’assistant externe en attente dans l’onglet Handoffs de la session, avec Accept and run et Decline

Si Codex a envoyé la mauvaise chose, cancel_session_handoff avec le handoff_id la retire, tant que le propriétaire n'a pas encore accepté.

Où passe la limite

Proposer et exécuter sont volontairement deux outils distincts. propose_session_handoff sollicite une personne. Il lui faut osfoundry:write, une place de Contributor, ainsi qu'un context_summary et un requested_output lisibles par un humain, et rien ne démarre tant que le propriétaire n'a pas cliqué. request_session_run se passe du clic. Il lui faut osfoundry:run et une place de Runner accordée à l'avance par le propriétaire : le clic a donc été fait une fois, au moment où la place a été donnée. Les deux plafonnent max_rounds à 10. La proposition limite goal à 5 000 caractères, l'exécution à 10 000.

Codex voit des résultats, pas un raisonnement. read_session_task_result ne renvoie que les tâches lancées par cette connexion. read_session_mail renvoie les notes adressées à la connexion et celles qu'elle a publiées, et la description de l'outil précise "Internal agent analysis is excluded." post_session_note ajoute une note signée à laquelle les agents de la session peuvent répondre, et elle "does not trigger an automatic run".

La session tourne là où elle tourne d'habitude. Un handoff n'emporte ni le modèle, ni les clés, ni le dépôt de Codex dans osFoundry. Il transporte du texte, et la session travaille avec ses propres agents et outils. Tout ce qui n'existe qu'en local sur le poste, comme un dossier local ou un élément non synchronisé, reste hors de portée. La réponse initialize du serveur le dit : "Local-only data is unavailable to cloud clients."

Retirer l'accès se fait en un clic. Supprimez la place dans l'onglet Connected ou révoquez la connexion, et le prochain appel de Codex à la session est refusé.

Pour un premier essai, prenez une boucle que vous lancez déjà à la main. Invitez Codex CLI comme Contributor, terminez une modification dans votre dépôt et demandez à Codex de proposer la prochaine exécution de la boucle avec un résumé de ce qui a changé. Handoffs montre comment les agents d'osFoundry se transmettent le contexte d'une étape à l'autre, et agent sessions montre où se trouve l'onglet Handoffs.