Come far passare a Codex CLI un task a un agente, un team o un loop di osFoundry

Alla fine, Codex CLI potrà passare il lavoro che non dovrebbe fare da solo a una sessione di osFoundry: una sessione agente, una sessione team o un loop. Invia un obiettivo, un riepilogo di quello che sa già e l'output che vuole ricevere. Il proprietario della sessione riceve una notifica e clicca Accept and run (accetta ed esegui) oppure Decline (rifiuta). Quando l'esecuzione finisce, Codex legge il risultato nella stessa sessione di terminale e va avanti. Se invece gli dai un posto da Runner, può avviare da solo un'esecuzione limitata, senza nessun clic.

Chi fa cosa

	Codex CLI	osFoundry
Login	Il tuo login di Codex. Codex conserva il token OAuth di osFoundry	Approva la connessione una volta, per un workspace e gli scope che spunti
A cosa può accedere	Alle sessioni in cui è stato invitato, tramite sette tool *_session_*	Decide il posto: Viewer legge, Contributor pubblica note e propone handoff, Runner può anche richiedere esecuzioni
Chi esegue il lavoro	Codex continua a lavorare nel tuo repository	La sessione gira sul proprio agent runtime, con i propri agenti, tool e impostazioni del modello
Chi approva	Codex ti chiede conferma prima di ogni tool di scrittura (default_tools_approval_mode = "writes")	Un handoff aspetta l'Accept and run del proprietario della sessione. Un posto da Runner è l'approvazione permanente per request_session_run
Quanto dura	max_rounds da 1 a 10 nella chiamata	Mostrato al proprietario come "Up to N rounds on your agent runtime"
Cosa torna indietro	Stato e risultato dei task avviati da questa connessione, e le note indirizzate a lei	L'analisi interna degli agenti della sessione resta dentro osFoundry

Configurazione

1. Crea la connessione

In osFoundry, clicca l'icona della chiave nell'header e apri la scheda Connected ("Connected agents"). In "Connect in three steps" imposta Assistant su Other MCP client, dagli un nome visualizzato come Codex CLI e clicca Add assistant. Il proprietario vedrà questo nome su ogni handoff, quindi scegline uno che riconosca.

Esempio: La scheda Connected agents con una connessione Codex CLI

2. Aggiungi il server a Codex, con lo scope di esecuzione

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

Poi apri ~/.codex/config.toml e restringi la tabella a quello che serve per questo lavoro:

[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 è lo scope dietro request_session_run. Toglilo se Codex deve solo proporre. I tool di handoff e delle note richiedono osfoundry:write, i tre di lettura osfoundry:read. Con "writes", Codex chiede conferma prima dei quattro tool non marcati come read-only ed esegue quelli di lettura senza chiedere.

3. Accedi

codex mcp login osfoundry

Il browser apre la pagina "Connect an agent" di osFoundry. Con gli scope qui sopra, "Requested capabilities" mostra tre righe. La terza è "Run sessions where you grant a runner role". Scegli il workspace, seleziona "Use pending: Codex CLI", spunta la casella di approvazione e clicca Connect.

4. Aggiungi la connessione al progetto che contiene la sessione

Tornando alla scheda Connected, la connessione mostra "Connected." In Projects scegli il progetto e clicca Add to project. Così la connessione vede le sessioni idonee del progetto, ma non può ancora scrivere in nessuna.

Esempio: La sezione Projects con un progetto aggiunto

5. Dalle un posto nella sessione

Più in basso c'è "Agent, Team, and Loop sessions". La riga di aiuto dice già tutto: "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 ]

Esempio: La sezione Agent, Team, and Loop sessions con Codex CLI come Contributor in una sessione di team

L'elenco propone solo le sessioni dei progetti a cui è stata aggiunta questa connessione. Scegli il tipo, la sessione e un ruolo, poi clicca Save role. Parti con Contributor. Se più avanti salvi Runner per la stessa sessione, il ruolo viene sostituito.

Un'esecuzione reale

Sulla macchina su cui è stato scritto questo articolo Codex non è installato, quindi la sessione qui sotto è un esempio simulato. I nomi dei tool e degli argomenti sono quelli che il server reale restituisce in tools/list, con il prefisso mcp__osfoundry__ che Codex aggiunge ai tool MCP. Il repository, la sessione e tutti i valori sono contenuti dimostrativi.

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.

Dal lato del proprietario è una cosa veloce. La notifica dice "Codex CLI requests a handoff" con "Review the request in Release desk." e un pulsante Review handoff, che apre la scheda Handoffs della sessione. In "Outside assistant requests" l'obiettivo è mostrato per intero, "Context and expected output" si può espandere e la riga "Up to 4 rounds on your agent runtime" dice quanto può fare l'esecuzione. Accept and run la mette in coda ("Handoff accepted and run queued"). Decline la chiude.

Esempio: La notifica Codex CLI requests a handoff con il pulsante Review handoff

Esempio: Una richiesta in attesa di un assistente esterno nella scheda Handoffs della sessione, con Accept and run e Decline

Se Codex ha mandato la cosa sbagliata, cancel_session_handoff con l'handoff_id la ritira, purché il proprietario non l'abbia ancora accettata.

Dov'è il confine

Proposta ed esecuzione sono due tool distinti di proposito. propose_session_handoff chiede a una persona. Richiede osfoundry:write, un posto da Contributor e un context_summary e un requested_output leggibili da un umano, e non parte nulla finché il proprietario non clicca. request_session_run salta il clic. Richiede osfoundry:run e un posto da Runner concesso in anticipo dal proprietario, quindi il clic è stato fatto una volta sola, quando è stato dato il posto. Entrambi limitano max_rounds a 10. La proposta limita goal a 5.000 caratteri, l'esecuzione a 10.000.

Codex vede i risultati, non il ragionamento. read_session_task_result restituisce solo i task avviati da questa connessione. read_session_mail restituisce le note indirizzate alla connessione e quelle che ha pubblicato lei, e la descrizione del tool dice "Internal agent analysis is excluded." post_session_note aggiunge una nota firmata a cui gli agenti della sessione possono rispondere, e "does not trigger an automatic run".

La sessione gira dove gira sempre. Un handoff non porta in osFoundry il modello, le chiavi o il repository di Codex. Porta testo, e la sessione lavora con i propri agenti e tool. Tutto ciò che esiste solo in locale sul desktop, come una cartella locale o un elemento non sincronizzato, resta fuori portata. Lo dice anche la risposta initialize del server: "Local-only data is unavailable to cloud clients."

Togliere l'accesso è un clic. Rimuovi il posto nella scheda Connected o revoca la connessione, e la chiamata successiva di Codex alla sessione viene rifiutata.

Per una prima prova va bene un loop che già lanci a mano. Invita Codex CLI come Contributor, completa una modifica nel tuo repository e chiedi a Codex di proporre la prossima esecuzione del loop con un riepilogo di cosa è cambiato. Handoffs mostra come gli agenti di osFoundry si passano il contesto tra un passaggio e l'altro, e agent sessions mostra dove si trova la scheda Handoffs.