Subagent Architecture
JAATO's subagent system enables a main agent to delegate specialized tasks to child agents. Subagents share the parent's JaatoRuntime (provider configs, plugin registry, permissions, token ledger) but get their own isolated JaatoSession with independent conversation state, model selection, and GC configuration.
Runtime vs Session Split
The core architectural insight is separating shared environment (JaatoRuntime) from per-agent state (JaatoSession). The runtime holds provider configurations, plugin registry, permissions, and the token ledger. Each session holds its own conversation history, model selection, system instructions, and GC state. This split enables fast subagent spawning — runtime.create_session() is lightweight with no redundant SDK connections.
Agent Profiles
Agent behavior is configured through SubagentProfile dataclasses, which can be defined inline in code or discovered from .jaato/profiles/*.json files. Each profile specifies the model, provider, plugins, system instructions, max turns, auto-approved tools, GC configuration, and an icon for UI display.
Profiles are used in two contexts:
- Subagent delegation — The main agent delegates tasks to subagents configured by profiles (the original use case)
- Main session creation — Any SDK client can create a new session with a profile via
create_session(profile="..."), applying the profile's model, provider, tools, system instructions, and GC configuration to the main session itself. See the IPCRecoveryClient Sessions API.
| Profile Field | Purpose |
|---|---|
model | Model name for this subagent (can differ from parent) |
provider | Provider name (enables cross-provider delegation) |
plugins | List of tool plugin names to expose |
system_instructions | Custom instructions for the subagent's role |
max_turns | Maximum agentic turns before forced completion |
auto_approved | List of tools that skip permission checks |
gc | GC plugin configuration (type, thresholds) |
Delegation Lifecycle
When the main agent delegates a task, the subagent plugin resolves the profile, creates a session via the shared runtime, configures tools and permissions, executes the task loop, and returns the result. Permission requests from the subagent are bridged to the parent's approval channel via ParentBridgedChannel.
Resource Sharing vs Isolation
| Resource | Sharing | Why |
|---|---|---|
| Provider configs | Shared | Avoid redundant SDK connections |
| Plugin registry | Shared | Single source of tool definitions |
| Permissions | Shared (bridged) | Consistent policy enforcement |
| Token ledger | Shared | Unified usage tracking and billing |
| Conversation history | Isolated | Independent context per agent |
| System instructions | Isolated | Role-specific behavior |
| GC state | Isolated | Independent context management |
Cross-Provider Subagents
Because provider configs are held at the runtime level, a subagent can use a different provider than its parent. For example, a main agent on Anthropic Claude can delegate research tasks to a subagent running Google Gemini, with both sessions sharing the same tool registry and permission policies.