Cómo hacer que Codex CLI pase una tarea a un agente, equipo o loop de osFoundry

Al terminar, Codex CLI podrá pasar el trabajo que no le toca hacer a él a una sesión de osFoundry: una sesión de agente, una sesión de equipo o un loop. Envía un objetivo, un resumen de lo que ya sabe y el resultado que espera recibir. El propietario de la sesión recibe una notificación y hace clic en Accept and run (aceptar y ejecutar) o en Decline (rechazar). Cuando termina la ejecución, Codex lee el resultado en la misma sesión de terminal y sigue trabajando. Si en lugar de eso le das un puesto de Runner, puede lanzar por su cuenta una ejecución acotada, sin ningún clic.

Quién hace qué

	Codex CLI	osFoundry
Login	Tu propio inicio de sesión de Codex. Codex guarda el token OAuth de osFoundry	Aprueba la conexión una vez, para un workspace y los scopes que marques
A qué puede acceder	A las sesiones a las que lo invitaron, mediante siete herramientas *_session_*	Lo decide el puesto: Viewer lee, Contributor publica notas y propone handoffs, Runner además puede pedir ejecuciones
Quién hace el trabajo	Codex sigue trabajando en tu repositorio	La sesión se ejecuta en su propio agent runtime, con sus propios agentes, herramientas y ajustes de modelo
Quién aprueba	Codex te pregunta antes de cada herramienta de escritura (default_tools_approval_mode = "writes")	Un handoff espera a que el propietario de la sesión pulse Accept and run. Un puesto de Runner es la aprobación permanente para request_session_run
Cuánto dura	max_rounds de 1 a 10 en la llamada	El propietario lo ve como "Up to N rounds on your agent runtime"
Qué vuelve	Estado y resultado de las tareas que inició esta conexión, y las notas dirigidas a ella	El análisis interno de los agentes de la sesión se queda dentro de osFoundry

Configuración

1. Crea la conexión

En osFoundry, haz clic en el icono de la llave de la cabecera y abre la pestaña Connected ("Connected agents"). En "Connect in three steps", pon Assistant en Other MCP client, dale un nombre visible como Codex CLI y haz clic en Add assistant. El propietario verá ese nombre en cada handoff, así que elige uno que reconozca.

Ejemplo: La pestaña Connected agents con una conexión de Codex CLI

2. Añade el servidor a Codex, con el scope de ejecución

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

Después abre ~/.codex/config.toml y limita la tabla a lo que necesita esta tarea:

[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 es el scope que hay detrás de request_session_run. Quítalo si Codex solo debe proponer. Las herramientas de handoff y de notas necesitan osfoundry:write, y las tres de lectura, osfoundry:read. Con "writes", Codex pregunta antes de las cuatro herramientas que no están marcadas como de solo lectura y ejecuta las de lectura sin preguntar.

3. Inicia sesión

codex mcp login osfoundry

El navegador abre la página "Connect an agent" de osFoundry. Con los scopes de arriba, "Requested capabilities" muestra tres líneas. La tercera es "Run sessions where you grant a runner role". Elige el workspace, selecciona "Use pending: Codex CLI", marca la casilla de aprobación y haz clic en Connect.

4. Añade la conexión al proyecto que contiene la sesión

De vuelta en la pestaña Connected, la conexión aparece como "Connected." En Projects, elige el proyecto y haz clic en Add to project. Así la conexión puede ver las sesiones elegibles del proyecto, pero todavía no puede escribir en ninguna.

Ejemplo: La sección Projects con un proyecto añadido

5. Dale un puesto en la sesión

Más abajo está "Agent, Team, and Loop sessions". La línea de ayuda lo resume todo: "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 ]

Ejemplo: La sección Agent, Team, and Loop sessions con Codex CLI como Contributor en una sesión de equipo

La lista solo ofrece sesiones de proyectos a los que se añadió esta conexión. Elige el tipo, la sesión y un rol, y haz clic en Save role. Empieza con Contributor. Si más adelante guardas Runner para la misma sesión, sustituye al rol anterior.

Una ejecución real

En la máquina donde se escribió esto no está instalado Codex, así que la sesión de abajo es un ejemplo simulado. Los nombres de las herramientas y de los argumentos son los que devuelve el servidor real en tools/list, con el prefijo mcp__osfoundry__ que Codex añade a las herramientas MCP. El repositorio, la sesión y todos los valores son contenido de demostración.

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.

Del lado del propietario es rápido. La notificación dice "Codex CLI requests a handoff" con "Review the request in Release desk." y un botón Review handoff. Ese botón abre la pestaña Handoffs de la sesión. En "Outside assistant requests" se ve el objetivo completo, "Context and expected output" se puede desplegar y la línea "Up to 4 rounds on your agent runtime" indica hasta dónde puede llegar la ejecución. Accept and run la pone en cola ("Handoff accepted and run queued"). Decline la descarta.

Ejemplo: La notificación Codex CLI requests a handoff con su botón Review handoff

Ejemplo: Una solicitud pendiente de un asistente externo en la pestaña Handoffs de la sesión, con Accept and run y Decline

Si Codex envió algo que no era, cancel_session_handoff con el handoff_id lo retira, siempre que el propietario no lo haya aceptado todavía.

Dónde está el límite

Proponer y ejecutar son dos herramientas a propósito. propose_session_handoff le pregunta a una persona. Necesita osfoundry:write, un puesto de Contributor y un context_summary y un requested_output legibles por humanos, y no arranca nada hasta que el propietario hace clic. request_session_run se salta el clic. Necesita osfoundry:run y un puesto de Runner que el propietario concedió de antemano, así que el clic se hizo una sola vez, al dar el puesto. Las dos limitan max_rounds a 10. La propuesta limita goal a 5.000 caracteres; la ejecución, a 10.000.

Codex ve resultados, no razonamientos. read_session_task_result solo devuelve tareas que inició esta conexión. read_session_mail devuelve las notas dirigidas a la conexión y las que ella publicó, y la descripción de la herramienta dice "Internal agent analysis is excluded." post_session_note añade una nota con autor a la que pueden responder los agentes de la sesión, y "does not trigger an automatic run".

La sesión se ejecuta donde siempre. Un handoff no lleva a osFoundry el modelo, las claves ni el repositorio de Codex. Lleva texto, y la sesión trabaja con sus propios agentes y herramientas. Lo que solo existe en el escritorio, como una carpeta local o un elemento sin sincronizar, queda fuera de alcance. La respuesta initialize del servidor lo dice: "Local-only data is unavailable to cloud clients."

Quitar el acceso es un clic. Quita el puesto en la pestaña Connected o revoca la conexión, y la siguiente llamada de Codex a la sesión se rechaza.

Para una primera prueba, un buen candidato es un loop que ya ejecutas a mano. Invita a Codex CLI como Contributor, termina un cambio en tu repositorio y pídele a Codex que proponga la siguiente ejecución del loop con un resumen de lo que cambió. Handoffs muestra cómo los propios agentes de osFoundry se pasan el contexto entre pasos, y agent sessions muestra dónde está la pestaña Handoffs.