Subagents
Child agent sessions that handle complex, multi-step tasks autonomously using preconfigs.
The task tool lets agents spawn child sessions to handle complex, multi-step tasks autonomously. Each child runs its own conversation using a preconfig that defines its system prompt, tools, model, and behavior.
How it works
When the LLM calls the task tool, the server resolves subagent_type to a preconfig from ~/.jean2/preconfigs/. A new child session is created with its own conversation history, linked to the parent via parentId.
The child session runs using the preconfig's system prompt, tools, and model. Only the last text part of the child's response is returned to the parent, along with a task_id for potential resumption.
The LLM can launch multiple subagents concurrently to maximize performance. Each subagent starts with fresh context unless you provide a task_id to resume a previous session.
Parameters
| Parameter | Required | Description |
|---|---|---|
description | Yes | Short 3-5 word description of the task |
prompt | Yes | Detailed task description specifying exactly what the agent should return |
subagent_type | Yes | Preconfig ID to use (must have mode: 'subagent' or mode: 'both') |
task_id | No | Resume a previous child session by its ID |
Preconfig modes
Preconfigs have a mode field that controls where they appear.
| Mode | Available as primary agent | Available as subagent |
|---|---|---|
primary (default) | Yes | No |
subagent | No | Yes |
both | Yes | Yes |
Only preconfigs with mode: 'subagent' or mode: 'both' are listed as available subagent types.
Subagent depth limit
Max depth is 2 levels. Primary session (depth 0) can spawn children. Children (depth 1) can spawn grandchildren. Grandchildren (depth 2) cannot spawn further.
This limit will be configurable through an
.envvariable in a future update.
This prevents runaway recursion. A common pitfall is using an exploration-type subagent as a middleman that spawns further subagents. This just adds latency and burns context on information passing with no real benefit.
When to use nested subagents:
The child agent has a genuinely different role than the grandchild (e.g., a code reviewer spawning a test runner).
Each level adds clear, distinct value that the parent couldn't do itself. The task is inherently hierarchical. A manager delegating to specialists.
When NOT to nest:
Passing information between agents that could have been one session. An exploration/research agent that just relays its findings to another agent.
Any pattern where a subagent's main job is calling another subagent and returning its result.
Model inheritance
If the subagent's preconfig doesn't specify a model or provider, it inherits from the parent session. Define a subagent preconfig with just a system prompt and tools, and it will automatically use the same model the parent is running on.
Key behaviors
Parent abort propagates. If the parent session is interrupted, child sessions are marked as interrupted.
Independent permissions. Child sessions have their own permission request handler, so tool approvals are handled separately.
Retry. Child sessions automatically retry on transient API errors (rate limits, server errors).
Real sessions. Child sessions appear in the client and their messages are stored normally.
Resumption. Pass task_id to continue a previous child session with its full conversation history.