Instruction Sources & Priority Hierarchy
JAATO assembles model instructions from multiple sources in a carefully layered architecture. Instructions are combined at runtime in a specific priority order, while runtime messages follow a separate priority queue for agent communication.
System Instruction Assembly Order
When a session is configured, system instructions are assembled in a fixed order from first to last in the final prompt. Each layer adds context that shapes the model's behavior:
| Layer | Source | Est. Tokens | Purpose |
|---|---|---|---|
| 1. Base Instructions | .jaato/system_instructions.md |
0–500+ | Behavioral rules that apply to all agents (transparency, operational constraints) |
| 2. Session Instructions | session.configure() parameter |
0–1,000+ | Task-specific guidance provided programmatically |
| 3. Plugin Instructions | Each plugin's get_system_instructions() |
200–3,000+ | Tool-specific usage guides (how to use readFile, run, etc.) |
| 4. Permission Instructions | Permission plugin | ~100–200 | Permission requirements and constraints |
| 5. Task Completion | Framework constant (always) | ~30 | Encourages agentic continuation without unnecessary pauses |
| 6. Parallel Tool Guidance | Conditional on JAATO_PARALLEL_TOOLS=true |
~60 | Instructs model to batch independent tool calls |
| 7. Sandbox Guidance | Conditional on workspace root | ~70 | File operation restrictions in sandboxed environments |
Token Budget Overview
The total instruction overhead depends on which plugins are enabled:
| Configuration | Estimated Tokens | Use Case |
|---|---|---|
| Minimal | ~500–800 | Single simple plugin (e.g., web_search only) |
| Typical | ~2,000–2,500 | Standard setup with 4–5 common plugins |
| Full | ~3,500–4,500 | All plugins + sandbox + extensive base instructions |
With JAATO_DEFERRED_TOOLS=true (the default), initial context is smaller because only core tools are loaded upfront. The model discovers other tools via introspection as needed.
Plugin Token Breakdown
| Plugin | Tokens | Description |
|---|---|---|
cli | ~800 | Shell access, examples, backgrounding |
file_edit | ~700 | CRUD operations, multiFileEdit, backups |
subagent | ~875 | Complex orchestration, event handling |
filesystem_query | ~300 | glob_files, grep_content |
web_search | ~225 | Internet search |
web_fetch | ~200 | URL fetching |
mcp | ~400 | Model Context Protocol servers |
memory | ~250 | Session memory management |
references | ~150 | @file reference handling |
permission | ~100 | Permission system rules |
Prompt Enrichment Pipeline
User prompts are processed through an enrichment pipeline before being sent to the model. Plugins subscribe to this pipeline and are called in priority order (lower numbers run first):
User Prompt → references(20) → template(40) → multimodal(60) → memory(80) → session(90) → Enriched Prompt
Each plugin receives the output of the previous plugin, enabling chained transformations. For example, the references plugin injects @file content, then the template plugin extracts embedded templates from that injected content.
| Priority | Plugin | Purpose |
|---|---|---|
| 20 | references | Injects MODULE.md and other @reference content |
| 40 | template | Extracts embedded templates from injected content |
| 60 | multimodal | Handles @image references |
| 80 | memory | Adds memory hints based on prompt content |
| 90 | session | Adds session description hints |
Runtime Message Priority
During agent execution, messages between agents are queued with priority-based processing. High-priority messages (from PARENT, USER, SYSTEM) can interrupt the model mid-turn, while low-priority messages (from CHILD agents) are queued and processed when the agent becomes idle.
| Source Type | Priority | Processing Mode |
|---|---|---|
PARENT | HIGH | Mid-turn interrupt |
USER | HIGH | Mid-turn interrupt |
SYSTEM | HIGH | Mid-turn interrupt |
CHILD | LOW | Process when idle (FIFO within group) |