Subagentes de Claude Code: baja su esfuerzo y gastarás menos tokens

TL;DR Añade a tu CLAUDE.md una línea que diga qué subagentes corren en low y cuáles en high. Desde la v2.1.292, Claude la convierte en un parámetro effort en cada subagente que lanza. Sin ella, el subagente sin nivel propio hereda el de tu sesión, y en max una explicación de cinco líneas gasta 18 veces más.

Un subagente corre con el effort de tu sesión salvo que algo le fije otro nivel. Si subes la sesión a max para un problema difícil, el subagente que solo tiene que localizar un archivo razona igual de hondo. Desde la v2.1.292, Claude puede pasar un nivel distinto a cada subagente que lanza: basta con decirle cuál.

Lo que cuesta el nivel en una tarea rápida

El mismo subagente general-purpose, la misma tarea, solo cambiando el nivel. Claude Code v2.1.311 con Sonnet 5.5, sobre un hook de Python de 360 líneas, una ejecución por celda. Tokens de salida del subagente y segundos, leídos de su transcript:

Hasta xhigh, una tarea mecánica cuesta casi lo mismo en cualquier nivel: el effort es adaptativo, y el modelo apenas piensa cuando la tarea no lo pide. En max deja de serlo. La misma explicación de cinco líneas gastó 18 veces más tokens de salida y tardó nueve veces más, y esos tokens se cobran como salida, la tarifa más alta del modelo.

max es justo el nivel que se sube para un rato: Claude Code lo aplica solo a la sesión actual. Y lo hereda todo subagente sin nivel propio. Con la sesión lanzada con --effort max y un subagente al que nadie fijó nivel, la misma explicación corrió en max: 9.577 tokens de salida y 80 segundos.

Donde bajar el nivel sí cuesta

La misma comparación con una revisión de bugs del mismo hook:

En low, el fallo principal era una función que devolvía una lista más corta que su entrada; el código añade un elemento por línea, así que no existe. En high apareció lo que importaba: una comilla sin cerrar en el comando hace que el hook capture la excepción y deje pasar el commit sin revisarlo. En una revisión, pensar es el producto. Ahí el nivel se queda alto.

De dónde saca el nivel cada subagente

Claude Code lo resuelve en este orden, y gana el primero que exista:

Un agente file-finder con effort: low en su frontmatter corrió en low sin pedir nada. Pidiéndolo "at high effort", Claude lanzó esta llamada y el subagente corrió en high:

{"description": "Find file containing \"world\"", "subagent_type": "file-finder", "effort": "high", "prompt": "Find which file(s) in ... contain the word \"world\". Report the file path(s) and the matching lines."}

Cómo dejarlo configurado

1. Una línea en tu CLAUDE.md

Run search and lookup subagents at low effort. Run review subagents at high effort.

Con esa línea en el CLAUDE.md del proyecto y un prompt que no mencionaba el effort ("Use a general-purpose subagent to find which file contains the word world"), Claude pasó "effort": "low" en la llamada. Cubre también los agentes que no son tuyos, como general-purpose, que no tienen un frontmatter que puedas tocar.

2. Fíjalo en la definición de tus agentes

Para un agente propio que siempre hace lo mismo, el nivel se fija en su archivo:

---
name: file-finder
description: Finds files in the repo by name or content. Use for quick lookups.
tools: Glob, Grep, Read
effort: low
---
You find files. Answer with the paths only.

El formato completo está en cómo crear agentes personalizados. Si además quieres sacarlo de tu modelo principal, model: haiku es la otra mitad del ahorro, y la tienes en subagentes con Haiku 5.5.

3. Comprueba en qué nivel corrió

En una sesión interactiva, el panel /tasks añade a la fila de cada subagente el effort fijado para él. Fuera de ella, cada subagente deja un .meta.json junto a su transcript:

cat ~/.claude/projects/<proyecto>/<sesión>/subagents/agent-*.meta.json

{"agentType":"general-purpose","isBuiltIn":true,"launchedWithDefaults":true,"description":"List files in folder","toolUseId":"toolu_01SyzkYKtHeftFPafzT47ZHn","spawnDepth":1,"requestShape":"background","requestNonInteractive":true,"effort":"low","finished":true}

Si el campo effort no aparece, nadie fijó un nivel para ese subagente y corrió con el de tu sesión.

Los casos que te vas a encontrar

• Con CLAUDE_CODE_EFFORT_LEVEL definida, el parámetro desaparece. Con la variable en medium, Claude respondió a la petición de un subagente en max con "the Agent tool has no effort parameter". El subagente corrió en medium, por encima de su effort: low. Si usas esa variable, decides el nivel de todos.
• Los forks no lo aceptan. El parámetro es solo para subagentes que no son un fork; un fork hereda la sesión entera.
• Reanudar conserva el nivel. Un subagente lanzado en low sigue en low cuando le mandas otro mensaje.
• Un nivel que el modelo no tiene baja al más alto que sí tenga. xhigh corre como high en Opus 4.6. Y un tope de maxEffortLevel o de tu organización sigue mandando.
• Tu sesión no cambia. El nivel que Claude pasa al subagente no toca el tuyo: la sesión de las pruebas siguió en medium. Para fijar el de tu sesión por modelo está effort por modelo, y para saber cuál tienes de verdad, el effort no es el que crees.

Documentación oficial: Sub-agents: choose an effort level · Model configuration: adjust effort level

Requisitos

• Claude Code v2.1.292 o superior para el parámetro effort; el campo effort del frontmatter es anterior. Las pruebas corrieron en la v2.1.311 con Sonnet 5.5 en -p, una ejecución por celda: las cifras cambian con el modelo y la tarea, el salto en max es lo que hay que vigilar.
• El panel /tasks, la conservación del nivel al reanudar y el caso de los forks vienen de la documentación.