Subagentes de Claude Code: cuándo ahorran tokens

Un subagente es un trabajador independiente que Claude Code inicia dentro de la sesión. Tiene ventana de contexto, prompt de sistema y herramientas propios. Lee archivos, busca y ejecuta comandos allí; devuelve solo su respuesta final. Claude también puede delegar automáticamente, por ejemplo en Explore al buscar código.

Así, los subagentes ahorran espacio en la conversación principal, no necesariamente tokens totales. Sus lecturas no entran en tu historial, pero cada uno paga su preparación y exploración. Ejecutar varios multiplica ambos costes.

Qué paga un subagente

Empieza sin el historial, skills invocadas ni archivos ya leídos en tu conversación. Recibe un mensaje que Claude redacta para encargarle la tarea. Cada una de sus peticiones lleva:

• →Su propio prompt de sistema, más corto que el principal, y las herramientas permitidas, incluidas las MCP.
• →Los archivos CLAUDE.md y una instantánea del estado de Git. Explore y Plan integrados omiten ambos para arrancar con menos coste.
• →El encargo y el texto completo de las skills que su definición precargue.

Después recorre su propio bucle. Cada resultado de herramienta, archivo leído y salida de comando entra en su contexto y se reenvía en el paso siguiente. Cuanto más larga la búsqueda, más pesa este trabajo frente al coste inicial.

Su primera petición no puede leer la caché de la conversación principal porque usa otro prefijo. La caché que crea dura cinco minutos por defecto, aun cuando la principal de una suscripción dure una hora. subagentPromptCacheTtl puede ampliarla a una hora, con escrituras más caras.

La respuesta final y un breve resumen con tokens y duración vuelven a la conversación principal. Permanecen en turnos posteriores. Un veredicto de dos líneas cuesta menos en el hilo principal que un informe completo.

Qué ahorra

Evita que la conversación principal acumule todo lo explorado: una docena de archivos para localizar una función o miles de líneas de pruebas detrás de tres fallos. Si se hiciera allí, ese material permanecería y se reenviaría hasta limpiar o compactar. La caché reduce el precio de releerlo, pero sigue consumiendo cuota y espacio en la ventana.

La documentación de Claude Code da un ejemplo: un subagente de investigación lee unos 6.100 tokens de archivos y devuelve 420 a la conversación principal. Ese hilo crece solo en 420; las lecturas se pagaron en la ventana del subagente.

Compensa cuando lo excluido es grande y la sesión principal aún tiene muchos turnos. Pierde ventaja si la tarea es pequeña o el subagente debe releer lo que el hilo principal ya conoce.

Cuándo compensan

• →Explorar código desconocido, donde muchos archivos consultados resultan irrelevantes.
• →Reducir salidas extensas a un veredicto: fallos de pruebas, errores de un registro o una respuesta tomada de documentación.
• →Tareas largas: cuantos más turnos quedan en el hilo principal, más vale cada token que no entra en él.
• →Investigaciones independientes en paralelo: terminan cuando acaba la más lenta, ahorrando tiempo; cada una sigue pagando su preparación.
• →Búsquedas, resúmenes y comprobaciones que un modelo pequeño resuelve bien.

Cuándo desperdician tokens

• →Cambios pequeños y concretos. Si conoces el archivo, la preparación puede superar la exploración ahorrada.
• →Trabajo que depende de lo aprendido en la conversación. El subagente vuelve a leer archivos; planificación, implementación y pruebas con contexto compartido suelen encajar mejor en el hilo principal.
• →Agentes paralelos que se solapan. Tres que necesitan el mismo módulo lo leen tres veces y devuelven tres resultados.
• →Muchos agentes simultáneos en una suscripción. Todos consumen los mismos límites del plan y Claude Code advierte de que el uso se multiplica.

La delegación puede anidarse. A septiembre de 2026, un subagente puede iniciar otros hasta tres niveles por debajo de la conversación y pueden ejecutarse veinte a la vez por defecto. CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH=1 evita el anidamiento; CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS cambia la concurrencia.

Hay dos alternativas para casos concretos. /btw responde una duda lateral con el contexto existente, sin herramientas ni entrada de la respuesta en el historial. /subtask crea una bifurcación que hereda la conversación y su caché: puede salir más barata si necesita ese contexto, aunque arranca con el mismo tamaño.

Usa un modelo más barato en el subagente

Un subagente personalizado es un Markdown con cabecera YAML en .claude/agents/ o ~/.claude/agents/. El campo model acepta haiku, sonnet, opus, fable, un identificador completo o inherit. Para buscar, resumir o comprobar, puedes poner model: haiku.

Claude Code decide el modelo por este orden: el que Claude indique para la llamada, el de la definición, CLAUDE_CODE_SUBAGENT_MODEL y finalmente el de la conversación principal. Si el subagente hereda y cambias tu sesión a Opus, él también cambia.

Explore integrado ya no usa Haiku por defecto: desde v2.1.198 hereda el modelo de la sesión, con un techo de Opus en la API. Un subagente propio llamado Explore con model: haiku lo sustituye, pero carga CLAUDE.md salvo que añadas omitClaudeMd: true. CLAUDE_CODE_SUBAGENT_MODEL_FORCE=1, desde v2.1.257, también aplica el modelo de entorno a Explore y Plan.

A precios de API de Anthropic de septiembre de 2026, Haiku 4.5 cuesta 1 dólar por millón de entrada y 5 por millón de salida; Sonnet 5, 2 y 10; Opus 5.5, 4 y 20. En una suscripción, los modelos mayores también consumen más cuota por turno.

La ventana corresponde al modelo del subagente: Haiku 4.5 dispone de 200.000 tokens y Sonnet 5 u Opus 5.5 de un millón. maxTurns limita sus turnos; effort: low puede reducir el razonamiento en Sonnet u Opus sin cambiar el esfuerzo principal.

$/tasks

Cómo medir lo que consumen

Para obtener totales, usa instrumentos que sumen todas las peticiones:

• →/usage en Pro, Max, Team y Enterprise atribuye uso reciente a subagentes, skills, plugins y MCP. d y w alternan 24 horas y siete días. Solo lee el historial local; Prompt cache (main) se limita al hilo principal.
• →En scripts, claude -p --output-format json devuelve total_cost_usd y modelUsage, que incluyen subagentes. El campo usage del Agent SDK cuenta solo el bucle principal.
• →En equipos, los contadores OpenTelemetry marcan las peticiones de subagente con query_source igual a subagent y agent.name.
• →Los historiales de subagentes, con lo que leyeron y ejecutaron, se guardan en ~/.claude/projects/{project}/{sessionId}/subagents/ durante 30 días por defecto.

$/usage

Antes de delegar

La exploración más barata es la que se evita. Nombra el archivo si lo conoces y formula la pregunta concreta. Mantén breve el campo description de cada subagente: sus descripciones ocupan contexto en la conversación principal, mientras que su prompt completo solo se carga al ejecutarse.

Si quieres poner límite a la exploración, capsul usa la sesión existente de Claude Code, envía lo que pide la tarea en vez del repositorio y se detiene en el presupuesto de tokens elegido, indicando lo que dejó fuera.

$capsul ask 'why does the session expire early' --budget 3000