TL;DR En segundo plano un subagente conserva todas sus herramientas MCP pero solo 19 nativas. Compara tu campo
toolscon esa lista y pide primer plano cuando declare algo que no esté, porque el filtro se aplica igual y en silencio. Así dejas de depurar un subagente que parece ignorar su propia configuración.
Declaras ListAgents en el tools de tu subagente. Lo lanzas. No la tiene. No hay error, no hay aviso, y el archivo está bien escrito.
La causa no está en tu configuración: está en dónde corre. Desde la v2.1.198 los subagentes arrancan en segundo plano por defecto, y el segundo plano tiene su propio recorte de herramientas.
Dos filtros, no uno
Un subagente hereda las herramientas nativas y las MCP de la conversación principal, y luego pasa por dos filtros encadenados.
El primero se aplica a todo subagente, corra donde corra, y quita estas aunque las declares:
AskUserQuestion EndConversation EnterPlanMode ExitPlanMode
ScheduleWakeup TaskOutput WaitForMcpServers Workflow
ExitPlanMode sobrevive si el subagente tiene permissionMode: plan. Y Agent solo desaparece cuando el subagente ya está en el límite de profundidad, así que un subagente normal sí puede lanzar los suyos.
Ahí está la primera sorpresa: un subagente nunca puede preguntarte nada. No es cosa del segundo plano, es de todos. Hace lo que puede con lo que entendió.
El segundo filtro solo se aplica en segundo plano. Conserva todas las herramientas MCP, y de las nativas deja exactamente estas 19:
Read Grep Glob Bash PowerShell
Edit Write NotebookEdit WebFetch WebSearch
TodoWrite Skill ToolSearch EnterWorktree ExitWorktree
Monitor TaskStop SendMessage Artifact
Todo lo demás se va. Aunque lo hayas escrito en tools. Y sin error: la eliminación solo protesta si te deja la lista vacía, en cuyo caso el subagente no llega a arrancar.
El efecto práctico es que el mismo archivo resuelve a herramientas distintas según dónde acabe corriendo.
Lo que más se nota
SendMessage está en la lista y ListAgents no. O sea que un subagente de fondo puede enviar un mensaje a otra sesión pero no puede descubrir a quién enviárselo. Si le encargas algo que dependa de hablar con tus otras sesiones, en primer plano funciona y en segundo plano se queda a medias.
Los teammates de un agent team son la excepción: además de las 19 conservan TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete y CronList.
La otra excepción son los forks de la conversación, que se saltan los dos filtros y reciben el pool exacto de la principal.
Y dónde corre decide algo más que duele igual: lo que edita un subagente de fondo no lo devuelve un rewind. Solo una skill con context: fork en primer plano queda cubierta por los checkpoints; para el resto, el botón de deshacer es git.
Cómo lo controlas
1. Compara tu tools con las 19
Si tu subagente declara algo fuera de esa lista y no es un fork ni un teammate, en segundo plano no lo va a tener.
2. Pide primer plano al delegar
No hay ningún background: false. La forma documentada es decírselo a Claude en la propia petición:
Investiga el fallo de auth con un subagente, en primer plano
En primer plano el subagente bloquea la conversación hasta terminar, y a cambio conserva todas las herramientas que le corresponden por el primer filtro.
3. O al revés: fuerza el fondo siempre
En el frontmatter del subagente:
---
name: researcher
description: Investiga y resume, nunca escribe
background: true
---
Con background: true ese subagente irá al fondo aunque Claude necesite el resultado ya. Sin el campo, decide Claude, y por defecto elige fondo. Es el campo que falta en la tabla de campos de cómo crear un agente, que cubre la otra pieza: --agent convierte tu sesión principal en el agente, y ahí no hay filtro de fondo que valga.
Lo que ganas a cambio
El recorte no es gratuito para Anthropic tampoco: el fondo es lo que permite que la sesión no se congele. Desde la v2.1.186, cuando un subagente de fondo llega a una llamada que necesita permiso, el aviso te aparece en la sesión principal con el nombre de quién pregunta; aceptas, o con Esc deniegas esa llamada sin matar al subagente. Antes de esa versión, un subagente de fondo auto-denegaba en silencio cualquier cosa que requiriese permiso, que es bastante peor que perder ListAgents.
Mientras corre lo tienes en el panel /tasks, donde los terminados se quedan listados debajo de lo que sigue trabajando. Si lo que quieres es mandar al fondo algo que ya está corriendo, eso es Ctrl+B y vive en el modo bash. Y si el nivel que te interesa es el de sesiones enteras y no el de subagentes dentro de una, el mapa está en background agents.
Referencia
| Quieres… | Usa |
|---|---|
| Que un subagente conserve todas sus herramientas | Pídelo en primer plano al delegar |
| Que vaya siempre al fondo | background: true en su frontmatter |
| Ver los que están corriendo | /tasks |
| Subir o bajar el tope de 20 concurrentes | CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS |
| Desactivar el segundo plano por completo | CLAUDE_CODE_DISABLE_BACKGROUND_TASKS=1 |
Con 20 subagentes corriendo, el siguiente falla con Concurrent subagent limit reached y Claude tiene instrucciones de no reintentar. Vuelve a admitir cuando alguno termina.
Documentación oficial: Create custom subagents