Subagents

The task tool lets agents spawn child sessions to handle complex, multi-step tasks autonomously. Each child session runs its own independent conversation using a preconfig that defines its system prompt, tools, model, and behavior. The parent agent gets back the child's final response plus a task_id for potential resumption.

How It Works

When the LLM calls the task tool:

1. The server resolves subagent_type to a preconfig from ~/.jean2/preconfigs/
2. A new child session is created with its own conversation history, linked to the parent via parentId
3. The child session runs using the preconfig's system prompt, tools, and model
4. Only the last text part of the child's response is returned to the parent
5. The result includes a task_id (the child session ID) — pass it back to resume the child session later

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)
• Child of primary = depth 1 (can spawn grandchildren)
• Child of child = depth 2 (cannot spawn further)

This limit will be configurable through an .env variable in a future update.

This prevents runaway recursion, but steering agents to use the depth budget wisely matters. A common pitfall is using an exploration-type subagent (one that searches, reads, and summarizes) 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. This means you can 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