Subagentes en Claude Code: el límite que Anthropic quitó y cómo ponerlo tú

TL;DR Claude Code ya no limita cuántos subagentes se lanzan en una sesión. Si quieres un freno, ponlo tú: un hook PreToolUse sobre Agent que cuenta los lanzamientos y bloquea a partir del número que elijas, y maxTurns en el frontmatter de cada agente que lanza a otros. Lo que escribas en el prompt no frena nada.

En la v2.1.212 Claude Code estrenó un tope de 200 subagentes por sesión, y el changelog daba el motivo: "to stop runaway delegation loops". Doce versiones después, en la v2.1.224, lo quitó. Hoy quedan dos límites: 20 subagentes corriendo a la vez y 3 niveles de anidamiento. Ninguno de los dos cuenta el total. La documentación lo dice sin rodeos: "There's no limit on the total number of subagents Claude can spawn over a session".

Por qué un límite en el prompt no sirve

Lo aprendí con delegate, un agente de mi plugin craft que construye una fase entera y lanza revisores por el camino. Su prompt decía que parara hacia los 40 turnos, contados por él mismo. En una ejecución real hizo 195 llamadas a herramientas sin detenerse y lanzó 7 revisiones para una sola fase. Su informe final decía 4.

El modelo no lleva la cuenta de sus propios turnos, y cuando la lleva, se equivoca. Un límite escrito en el prompt es una sugerencia. Uno que aplica Claude Code es un límite. Es la misma idea que con CLAUDE.md frente a los hooks: el texto es contexto, no una garantía.

El límite total: un hook de diez líneas

Un hook PreToolUse salta antes de cada llamada a la herramienta Agent, que es con la que Claude lanza subagentes. Este cuenta los lanzamientos de la sesión y, pasado el tope, bloquea el siguiente.

1. El script, en ~/.claude/hooks/subagent-cap.sh

#!/bin/bash
LIMIT="${SUBAGENT_CAP:-30}"
sid=$(python3 -c 'import json, sys; print(json.load(sys.stdin)["session_id"])')
counter="${TMPDIR:-/tmp}/claude-subagents-$sid"
n=$(( $(cat "$counter" 2>/dev/null || echo 0) + 1 ))
echo "$n" > "$counter"
if [ "$n" -gt "$LIMIT" ]; then
  echo "Subagent limit reached: $LIMIT per session. Do not launch more, finish with what you have." >&2
  exit 2
fi

chmod +x ~/.claude/hooks/subagent-cap.sh

2. Regístralo en ~/.claude/settings.json

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Agent",
        "hooks": [
          { "type": "command", "command": "~/.claude/hooks/subagent-cap.sh" }
        ]
      }
    ]
  }
}

3. Lo que pasa al llegar al tope

Lo probé con SUBAGENT_CAP=2 y un prompt que pedía tres subagentes seguidos. Pasaron dos y el tercero se quedó fuera:

PreToolUse:Agent hook error: [.../subagent-cap.sh]: Subagent limit reached: 2 per session. Do not launch more, finish with what you have.

El exit 2 bloquea la llamada y le entrega el mensaje a Claude, que termina con lo que tiene en vez de reintentar. El contador también cuenta lo que lanzan tus subagentes: el hook salta dentro de ellos con el mismo session_id que la conversación principal. Para empezar de cero, borra el archivo del contador.

El número es tuyo: cambia el 30 del script, o exporta SUBAGENT_CAP antes de lanzar claude. El de Anthropic era 200. Mira cuántos lanzas en una sesión normal y pon el tope un poco por encima. Los workflows dinámicos tienen su propio tope, y este hook no lo he probado con ellos.

El límite por agente: maxTurns

El hook cuenta lanzamientos. maxTurns limita cuánto trabaja cada agente, y es lo que acabé poniendo en delegate:

---
name: delegate
model: sonnet
maxTurns: 777
---

Lo aplica Claude Code, no el modelo. En mi prueba, un agente con maxTurns: 2 al que pedí leer cinco archivos se cortó después del primero y devolvió lo que tenía, con su agentId para continuar si hace falta.

Ese 777 no es un error. Una ejecución sana de delegate pasa de largo los 40 turnos, así que maxTurns funciona como disyuntor: alto para no cortar trabajo bueno, pero finito. Ponlo en cada agente que lance a otros.

Todos los frenos que tienes

Lo que ningún número arregla

Los límites cortan la hemorragia. Estas tres cosas del spec de delegate eran las que la provocaban:

• Un verificador que duda por defecto. Si el spec le dice al revisor que, sin pruebas claras, marque uncertain, y uncertain escala, en un cambio pequeño escalar se vuelve lo normal. La duda se reserva para lo que de verdad no se puede resolver.
• Esperar con sleep. Un agente que comprueba cada poco si sus subagentes en segundo plano han terminado paga la conversación entera en cada comprobación. Claude Code avisa cuando un subagente en segundo plano termina: basta con acabar el turno y esperar ese aviso.
• Dos reglas que chocan sin decir cuál gana. Un presupuesto de revisiones y una garantía de calidad pueden pedir cosas opuestas. Si el spec no dice cuál manda, cada ejecución decide distinto.

Y recuerda que cada subagente arranca sin tu conversación: cuanto peor sea el encargo, más vueltas da.

Documentación oficial: Concurrent subagent limit · Supported frontmatter fields · Hooks: PreToolUse

Requisitos

• Probado en Claude Code v2.1.282 el 26 de septiembre de 2026, con python3 disponible para el hook.
• Sin tope total desde la v2.1.224. El límite de concurrencia existe desde la v2.1.217.