Sistemas de Delegación en Subagentes: OpenCode, Codex CLI y Claude Code — Clase Magistral

1 Introducción — El Problema Fundamental

¿Cómo hacer que un agente de IA delegue trabajo a otro agente especializado? Este es el problema arquitectónico central de la programación agentica moderna. Cada plataforma lo aborda de forma radicalmente diferente:

Tres modelos mentales distintos, tres implementaciones diferentes, y un mismo objetivo: permitir que múltiples agentes de IA colaboren de forma segura y eficiente en un mismo proyecto. Analicemos cada uno en profundidad.

2 OpenCode — El Modelo de Permisos Whitelist

OpenCode implementa un sistema de delegación basado en control granular de permisos. Los subagentes se definen como archivos Markdown con YAML frontmatter y se invocan mediante la herramienta task. La filosofía es clara: cada subagente tiene exactamente los permisos que necesita y nada más.

Formato de Definición

Los subagentes se definen en .opencode/agents/<name>.md con YAML frontmatter:

---
name: git-expert
description: "AUTORIDAD EN GIT. Toda operacion git DEBE ser delegada."
mode: subagent
permission:
  "*": deny
  bash:
    "git *": allow
    "gh *": allow
  read: allow
---

Campos del Frontmatter

El Sistema de Permisos

El sistema de permisos de OpenCode es el más granular de las tres plataformas. Se basa en un diccionario whitelist con la regla "*": deny como primera línea de defensa, seguida de excepciones explícitas.

Whitelist Pattern

permission:
  "*": deny          # Denegar todo por defecto
  read: allow           # Leer archivos (siempre seguro)
  edit: allow           # Edit cubre write/patch/multiedit
  bash:
    "npm run *": allow  # Glob patterns en bash
    "node *": deny     # Excepción específica
  task:
    "git-*": allow     # Solo delegar a agentes git-*

Estrategia Query-type vs Command-type

La Herramienta task

El mecanismo de delegación en OpenCode es la herramienta task. Parámetros principales:

Autodiscovery: Si se omite subagent_type, OpenCode selecciona automáticamente el agente más adecuado basado en la descripción del agente y el prompt. El continuation-passing protocol permite que tareas largas retomen desde checkpoints.

Routing por Agente Autoritativo

OpenCode introduce el concepto único de agente autoritativo: ciertos dominios tienen un agente designado como autoridad exclusiva. La delegación forzosa se implementa mediante una combinación de:

1. load_skills — Skills obligatorias que imponen reglas de routing
2. task permissions — Solo ciertos agentes pueden ser invocados en ciertos contextos
3. System prompt — Instrucciones explícitas de delegación
4. AGENTS.md — Reglas globales del proyecto
5. description — Descripciones autoritativas que el autodiscovery respeta

Patrones de Permisos Comunes

Modos de Agente

Built-in Agents

OpenCode incluye agentes predefinidos que cubren necesidades comunes:

Workspace/Worktree Experimental

OpenCode incluye una API experimental de workspaces y worktrees descubierta en el SDK de plugins, aunque sin documentación oficial estable:

3 Codex CLI — El Modelo de Sandboxing OS-level

Codex CLI de OpenAI implementa un sistema de subagentes basado en sandboxing a nivel de sistema operativo. En lugar de controlar qué tools puede usar cada agente, controla qué partes del filesystem puede tocar. La filosofía: "aísla al agente, no a la herramienta".

Formato de Definición

Los subagentes se definen en .codex/agents/<name>.toml con formato TOML:

name = "reviewer"
description = "PR reviewer focused on correctness"
developer_instructions = """
Review code like an owner.
"""
model = "gpt-5.4-mini"
model_reasoning_effort = "medium"
sandbox_mode = "read-only"

Campos del Frontmatter

Sandbox Modes — 3 Niveles

Codex CLI es la única plataforma con sandboxing real a nivel OS. Tres niveles de creciente permisividad:

Multi-Agent v1 (Legacy)

La primera versión del sistema multi-agente de Codex CLI se activaba con features.multi_agent = true y exponía tools específicas:

Multi-Agent v2 (Nuevo)

La versión más reciente simplifica el modelo. Una sola tool spawn_agent con:

• task_name — Identificador único para task-path routing
• message — Instrucciones para el subagente
• fork_turns — Número de turnos antes de autofork (hereda conversación padre)

Task-path routing: los subagentes se organizan en un árbol jerárquico (/root/parent/child/task). A diferencia de v1, ignora agents.max_depth, permitiendo anidamiento sin límite predefinido (aunque controlado por max_concurrent_threads_per_session, default 4).

spawn_agents_on_csv — Fan-out Batch

Codex CLI tiene una capacidad única: fan-out sobre CSV para procesamiento batch. Requiere features.enable_fanout = true y soporta timeout via max_runtime_seconds.

# Un agente por fila del CSV, procesamiento paralelo
features:
  enable_fanout = true

Configuración Global de Subagentes

En config.toml, sección [agents]:

Herencia de Configuración

Codex CLI implementa herencia de configuración padre → hijo:

• Sandbox/approval — Heredado del padre y re-aplicado. Un hijo nunca puede tener más permisos que el padre.
• Modelo — Heredado si se omite en el subagente
• reasoning_effort — Heredado si se omite
• mcp_servers — Heredados si se omiten en la definición
• skills.config — Ruta y enabled heredados

Built-in Agent

Codex CLI incluye un built-in explorer que puede ser overriden por un custom. Es el equivalente funcional al explore de OpenCode.

4 Claude Code — El Modelo de Aislamiento Físico y Memoria Persistente

Claude Code de Anthropic implementa el sistema de subagentes más completo y maduro de las tres plataformas. Su filosofía: cada subagente es un mini-entorno autocontenido con su propio filesystem aislado, su propia memoria persistente, y la capacidad de ejecutarse en background concurrentemente.

Formato de Definición

Los subagentes se definen en .claude/agents/<name>.md con YAML frontmatter:

---
name: code-reviewer
description: "Expert code reviewer. Use proactively after code changes."
tools: Read, Glob, Grep
disallowedTools: Write, Edit
model: sonnet
permissionMode: acceptEdits
maxTurns: 20
memory: project
effort: high
isolation: worktree
---

Los 17 Campos

Permission Modes — 6 Niveles

Claude Code tiene el sistema de control de permisos más matizado de las tres plataformas:

Aislamiento con Worktree — Exclusivo de Claude Code

Claude Code ofrece la implementación más madura de aislamiento físico mediante git worktrees, aunque OpenCode tiene una API experimental similar:

# En la definición del subagente:
isolation: worktree

# Crea un git worktree temporal en .claude/worktrees/<name>/
# Rama default desde origin/HEAD
# Auto-limpieza al terminar
# .worktreeinclude para archivos gitignored

Limitaciones Conocidas del Worktree Isolation

A pesar de ser la solución más madura, el sistema de worktree isolation de Claude Code tiene bugs documentados por la comunidad:

• Isolation incompleta — El aislamiento con worktree no aísla completamente todos los aspectos del entorno; hay reportes de filtraciones entre subagentes que comparten el mismo contexto.
• Agent Teams ignora isolation — Cuando se usa Agent Teams (múltiples subagentes coordinados), la configuración isolation: worktree no se aplica correctamente, anulando la protección.
• Sin solución confirmada — Los mantenedores han reconocido estos issues pero no hay un fix publicado en versiones estables recientes.

Memoria Persistente — Exclusivo de Claude Code

Claude Code es la única plataforma con memoria persistente para subagentes:

La memoria se almacena en un directorio dedicado con archivo MEMORY.md. Las primeras 200 líneas o 25KB se cargan al contexto automáticamente. Esto permite que un subagente aprenda y recuerde entre sesiones — único entre las tres plataformas.

Built-in Subagents

Scopes y Precedencia

La resolución de definiciones de subagentes sigue este orden de precedencia:

1. Managed (admin) — Mayor prioridad. Definiciones gestionadas por el administrador del sistema.
2. CLI flag — --agents flag al iniciar la sesión
3. Project — .claude/agents/ en el proyecto actual
4. User — ~/.claude/agents/ global del usuario
5. Plugin — Subagentes empaquetados en plugins (sin hooks/mcpServers/permissionMode)

Los directorios se escanean recursivamente, permitiendo organización por subdirectorios.

Mecanismos de Invocación

Agent SDK (Python + TypeScript)

Claude Code es la única plataforma con un Agent SDK oficial para integración programática:

• Python — claude-agent-sdk pip package. query(), AgentDefinition, ClaudeAgentOptions.
• TypeScript — @anthropic-ai/agent-sdk npm package. Misma API.
• Session management — Resume sessions, manejo de estado, checkpoints.

5 Tabla Comparativa Detallada (20+ dimensiones)

Esta es la tabla más completa que existe comparando los sistemas de delegación de las tres plataformas. Cada fila es una dimensión arquitectónica clave.

6 Análisis: Fortalezas y Debilidades

OpenCode — Fortalezas

• ✔ Control granular de permisos — La whitelist "*": deny es el estándar más seguro. Ninguna otra plataforma ofrece este nivel de granularidad.
• ✔ Routing autoritativo forzoso — Único con este concepto. Dominios críticos (git, DAG, lecciones) tienen agentes exclusivos que no pueden ser eludidos.
• ✔ Continuation-passing protocol — Tareas largas con checkpoints. Ninguna otra plataforma tiene equivalente.
• ✔ Flexibilidad total — Cualquier agente puede llamar a cualquier otro si los permisos lo permiten. Sin restricciones de topología.
• ✔ Sin límite de anidamiento — Árboles profundos de delegación posibles. Ideal para workflows complejos multi-nivel.
• ✔ Model-agnóstico — OpenAI, Anthropic, Google, OpenRouter, Ollama, providers locales.

OpenCode — Debilidades

• ✘ Aislamiento físico solo experimental — La API experimental_workspace existe pero no es estable ni está documentada oficialmente. En producción, los subagentes comparten el filesystem.
• ✘ Sin memoria persistente — No hay equivalente de memory: project. Cada sesión empieza desde cero.
• ✘ Sin background tasks — No hay concurrencia real. Todo es síncrono y secuencial.
• ✘ Sin Agent SDK — No hay API programática para gestionar subagentes desde código.
• ✘ MCP per-agente parcial — Los MCP servers se definen globalmente; solo se puede habilitar/deshabilitar su acceso por agente via glob patterns. No permite servers independientes por subagente.

Codex CLI — Fortalezas

• ✔ Sandboxing OS-level real — 3 niveles con true read-only filesystem. El más seguro de los 3 para código no confiable.
• ✔ spawn_agents_on_csv — Único para procesamiento batch. Los otros no tienen equivalente.
• ✔ Multi-Agent v2 — Task-path routing simplificado, fork_turns, herencia de conversación.
• ✔ Herencia de configuración — Padre → hijo: sandbox, modelo, reasoning_effort, MCP, skills.
• ✔ MCP scoped — Servidores MCP específicos por subagente.

Codex CLI — Debilidades

• ✘ Solo spawn explícito — No hay matching automático por descripción. El agente principal debe invocar explícitamente.
• ✘ Formato TOML — Diferente a las otras plataformas. No hay tooling nativo para edición programática.
• ✘ Sin aislamiento físico ni memoria persistente — Como OpenCode, comparte filesystem y no recuerda entre sesiones.
• ✘ Sin Agent SDK — No hay API programática.
• ✘ Multi-Agent v2 incompatible con max_depth — La nueva versión ignora el límite de profundidad de v1, creando ambigüedad.
• ✘ Solo OpenAI — No hay soporte multi-provider.

Claude Code — Fortalezas

• ✔ Aislamiento físico con git worktree — El más maduro. Múltiples subagentes modifican el mismo repo sin colisiones. ⚠️ Bugs conocidos: isolation incompleta, Agent Teams lo ignora.
• ✔ Memoria persistente cross-session — ÚNICO. MEMORY.md, 200 líneas/25KB al contexto. Aprendizaje entre sesiones.
• ✔ 6 permission modes — El sistema más matizado: default, acceptEdits, auto, dontAsk, bypassPermissions, plan.
• ✔ Agent SDK oficial — Python + TypeScript. query(), AgentDefinition, session management.
• ✔ Background tasks concurrentes — ÚNICO. Ctrl+B, auto-deny en prompts, ejecución paralela real.
• ✔ MCP servers scoped a subagentes — Servidores MCP específicos por subagente.
• ✔ Hooks lifecycle en subagentes — SubagentStart/Stop, Pre/PostToolUse.
• ✔ Plugin distribution — Subagentes empaquetados y distribuibles via plugins.

Claude Code — Debilidades

• ✘ Sin anidamiento de subagentes — No pueden spawnear otros subagentes. Es el más restrictivo en topología.
• ✘ Sin continuation-passing — No hay checkpoints. Las tareas largas no tienen punto de reanudación.
• ✘ Sin CSV fan-out — No hay procesamiento batch nativo.
• ✘ Sin whitelist pattern tan granular como OpenCode — tools/disallowedTools es menos expresivo que "*": deny + patrones glob en bash.
• ✘ Solo Anthropic — No hay soporte multi-provider.
• ✘ Worktree isolation con bugs — El aislamiento por git worktree no es completo y Agent Teams ignora isolation: worktree. Bugs reconocidos pero sin fix en versiones estables.

7 Tabla de Equivalencias

El mapa conceptual para portar subagentes entre las tres plataformas. Cada fila responde: "¿cómo hago X en cada plataforma?"

8 Guía de Decisión: ¿Qué plataforma usar para qué?

No se trata de cuál es "mejor" — se trata de cuál se adapta a cada caso de uso. Esta guía te ayuda a elegir según tus necesidades específicas.

📚 Fuentes y Referencias

Todas las afirmaciones en esta clase están respaldadas por documentación oficial y código fuente verificable.

OpenCode

• Documentación oficial de Agentes — Definición, campos, modos, built-in agents
• Documentación oficial de Configuración — Formato opencode.json, load order
• Documentación oficial de Permisos — Whitelist pattern, glob patterns, ejemplos
• Código fuente en GitHub — Repositorio oficial (MIT License)

Codex CLI (OpenAI)

• Documentación oficial de Agentes — Definición, campos, sandbox modes
• Cómo construir agentes — TOML format, developer_instructions, ejemplos
• Documentación oficial de Hooks — Lifecycle events, trust flow
• Código fuente en GitHub — Repositorio oficial (Rust core)

Claude Code (Anthropic)

• Documentación oficial de Subagentes — Definición, 17 campos, scopes, mecanismos de invocación
• Agent SDK Overview — Python + TypeScript, query(), session management
• Settings reference — 125+ keys, precedencia, formatos
• Skills reference — SKILL.md format, progressive disclosure, context: fork
• Hooks reference — Lifecycle events, tipos de hook, ubicaciones
• Plugins oficiales en GitHub — Repositorio curado por Anthropic

MCP (Model Context Protocol)

• Especificación oficial MCP — JSON-RPC 2.0, transportes, seguridad
• GitHub — Model Context Protocol — SDKs, servidores, especificación

Última verificación: Junio 2026. Las especificaciones y documentación pueden cambiar; consulte las fuentes oficiales para información actualizada.