Other Plugins

Additional built-in plugins for specialized functionality including clarification workflows, reference handling, multimodal support, subagent orchestration, and background task management.

Clarification Plugin

Structured question-and-answer workflow for gathering information from the user before proceeding with a task.

Name	clarification
Tools	askClarification
Auto-approved	Yes

Question Types

• single_choice: Select one option from a list
• multiple_choice: Select multiple options
• free_text: Open-ended text response

Use Cases

• Disambiguating vague requests
• Gathering missing parameters
• Confirming before destructive operations

# Model asks for clarification
askClarification(
    question="Which environment should I deploy to?",
    question_type="single_choice",
    options=["development", "staging", "production"]
)

# Response
{
  "answer": "staging",
  "question_type": "single_choice"
}

askClarification(
    question="Which tests should I run?",
    question_type="multiple_choice",
    options=["unit", "integration", "e2e", "performance"]
)

# Response
{
  "answer": ["unit", "integration"],
  "question_type": "multiple_choice"
}

Memory Plugin

Model self-curated persistent memory across sessions. The model can store valuable explanations and insights, then retrieve them in future sessions to build a persistent knowledge base.

Name	memory
Tools	store_memory, retrieve_memories, list_memory_tags
Subscribes to	Prompt enrichment (priority: 80)
Auto-approved	Yes

Two-Phase Retrieval

1. Prompt Enrichment: Plugin injects lightweight hints about available memories
2. Model Decision: Model decides whether to retrieve full content

Session Flow

Visual representation of how memories work across sessions:

Configuration

storage_path

Path to JSONL storage file (default: .jaato/memories.jsonl)

Use Cases

• Remember architecture explanations across sessions
• Build project-specific knowledge base over time
• Reduce redundant explanations of the same topics

# Session 1: Model provides comprehensive explanation
# then stores it
store_memory(
    content="The Runtime/Session split allows...",
    description="jaato Runtime/Session architecture",
    tags=["architecture", "runtime", "session", "subagents"]
)

# Response
{
  "status": "success",
  "memory_id": "mem_20231211_143022",
  "message": "Stored memory: jaato Runtime/Session architecture"
}

# Session 2: User asks related question
# Plugin enriches prompt with hint:

💡 **Available Memories** (use retrieve_memories to access):
  - [architecture, runtime, session, subagents]: jaato Runtime/Session architecture

# Model sees hint, retrieves memory
retrieve_memories(
    tags=["subagents", "runtime"],
    limit=3
)

# Response
{
  "status": "success",
  "count": 1,
  "memories": [{
    "id": "mem_20231211_143022",
    "description": "jaato Runtime/Session architecture",
    "content": "The Runtime/Session split allows...",
    "tags": ["architecture", "runtime", "session", "subagents"],
    "stored": "2023-12-11T14:30:22",
    "usage_count": 3
  }]
}

registry.expose_tool('memory', config={
    'storage_path': '.jaato/memories.jsonl',
})

# Default storage location: .jaato/memories.jsonl
# Add to .gitignore for private knowledge
# Or commit for team-shared knowledge base

References Plugin

Manages a catalog of documentation and reference sources. Sources can be automatically injected or user-selected on demand.

Name	references
Tools	selectReferences, listReferences
Auto-approved	Yes

Source Types

• LOCAL: Local files on filesystem
• URL: HTTP/HTTPS URLs
• MCP: MCP server tool calls
• INLINE: Content embedded in config

Injection Modes

• AUTO: Included in system instructions at startup
• SELECTABLE: User chooses via selectReferences tool

Subagent Configuration

preselected	List of source IDs to pre-select at startup
transitive_injection	Enable transitive detection (default: true). Scans pre-selected content for mentions of other catalog references.
exclude_tools	List of tools to hide (e.g., ["selectReferences"])
sources	Override available sources (IDs or full objects)

Transitive Injection

When enabled (default), pre-selected references are scanned for mentions of other catalog reference IDs. Discovered references are automatically added to the injection set, recursively with cycle detection.

{
  "version": "1.0",
  "sources": [
    {
      "id": "api-spec",
      "name": "API Specification",
      "type": "local",
      "path": "./docs/openapi.yaml",
      "mode": "auto",
      "tags": ["api", "endpoints"]
    }
  ]
}

{
  "name": "my-skill-agent",
  "plugins": ["cli", "file_edit", "references"],
  "plugin_configs": {
    "references": {
      "preselected": ["adr-001", "eri-001"],
      "exclude_tools": ["selectReferences"]
    }
  }
}

Multimodal Plugin

Image loading for multimodal model interactions. Enables the model to analyze images referenced in prompts or loaded on demand.

Name	multimodal
Tools	loadImage
Subscribes to	Prompt enrichment (priority: 60)
Model Requirements	gemini-3-*, gemini-3.5-*

Configuration

base_path	Base directory for relative paths
max_image_size_mb	Maximum image size in MB

# Reference image in prompt
"What's in this image? @./screenshot.png"

# Model loads image explicitly
loadImage(path="./diagram.png")

# Response includes image data
{
  "path": "./diagram.png",
  "mime_type": "image/png",
  "_multimodal": true,
  "image_data": "base64..."
}

Template Plugin

Jinja2-based template rendering with automatic extraction from documentation. When prompts contain code blocks with template syntax (like MODULE.md content), the plugin extracts them to .jaato/templates/ for later use.

Name	template
Tools	writeFileFromTemplate, listAvailableTemplates
Subscribes to	Prompt enrichment (priority: 40)
Auto-approved	listAvailableTemplates only

Automatic Template Extraction

The plugin scans prompts for code blocks containing Jinja2 syntax ({% raw %}{{ }}{% endraw %} or {% raw %}{% %}{% endraw %}). Detected templates are:

1. Extracted to .jaato/templates/
2. Named based on frontmatter ID + heading
3. Annotated in the prompt with usage instructions

Enrichment Pipeline Position

Runs at priority 40, after the references plugin (20) injects MODULE.md content, and before multimodal (60) and memory (80) plugins.

# Prompt contains MODULE.md with embedded template:
```java
@CircuitBreaker(name = "{{ circuitBreakerName }}")
public {{ returnType }} {{ methodName }}() { ... }
```

# After enrichment, agent sees:
---
**Extracted Templates:**
[Template extracted: .jaato/templates/mod-code-001-basic.java.tmpl]
  Variables: circuitBreakerName, methodName, returnType
  Use: writeFileFromTemplate(template_path="...", variables={...})
---

# Use extracted template
writeFileFromTemplate(
    template_path=".jaato/templates/mod-code-001-basic.java.tmpl",
    variables={
        "circuitBreakerName": "orderService",
        "returnType": "Order",
        "methodName": "getOrder"
    },
    output_path="src/main/java/OrderService.java"
)

# Or use inline template
writeFileFromTemplate(
    template="Hello {{ name }}!",
    variables={"name": "Alice"},
    output_path="greeting.txt"
)

listAvailableTemplates()
# Returns:
{
  "templates": [
    {
      "path": ".jaato/templates/mod-code-001-basic.java.tmpl",
      "variables": ["circuitBreakerName", "methodName", "returnType"],
      "exists": true
    }
  ],
  "count": 1
}

Subagent Plugin

Spawn child agents with configurable profiles for delegating specialized tasks. Supports parallel execution, cancellation propagation, and shared state for inter-agent communication.

Name	subagent
Tools	spawn_subagent, continue_subagent, close_subagent, cancel_subagent, get_subagent_result, list_active_subagents, list_subagent_profiles, set_shared_state, get_shared_state, list_shared_state

Parallel Execution

Spawn subagents in background threads for concurrent task execution using background=True. Use get_subagent_result to collect results when ready.

Cancellation Propagation

When the parent agent is cancelled (e.g., user presses Ctrl+C), all running subagents are automatically cancelled through shared CancelToken references. Use cancel_subagent to manually cancel a specific agent.

Shared State

Thread-safe shared state for inter-agent communication. All agents can read and write to a shared dictionary using set_shared_state and get_shared_state tools.

Profile Auto-Discovery

Profiles are automatically discovered from .jaato/profiles/. Each .json or .yaml file is parsed as a profile definition.

• auto_discover_profiles: Enable/disable (default: true)
• profiles_dir: Directory to scan (default: .jaato/profiles)

Plugin Configuration

Profiles can include plugin_configs to customize plugin behavior:

plugin_configs

Per-plugin configuration overrides

Environment Variables

JAATO_TRACE_LOG	Path to trace log file for debug output. Useful with rich terminal UIs. Default: /tmp/rich_client_trace.log
PROJECT_ID	Cloud project ID (legacy fallback)
LOCATION	Provider region (legacy fallback)
MODEL_NAME	Default model (fallback)

# Spawn agents in background
spawn_subagent(task="Analyze API module", background=True)
spawn_subagent(task="Review auth code", background=True)

# Check status
list_active_subagents()

# Collect result when ready
get_subagent_result(agent_id="subagent_abc123")

# Store a value (accessible by all agents)
set_shared_state(key="results", value={"count": 42})

# Retrieve a value
get_shared_state(key="results")
# Returns: {'success': True, 'value': {"count": 42}}

# List all keys
list_shared_state()

{
  "name": "skill-add-retry",
  "plugins": ["cli", "file_edit", "references"],
  "plugin_configs": {
    "references": {
      "preselected": ["adr-001", "eri-002"],
      "exclude_tools": ["selectReferences"]
    }
  }
}

# Use predefined profile
spawn_subagent(
    profile="research",
    task="Find best practices for Python async"
)

# Custom inline config
spawn_subagent(
    inline_config={
        "plugins": ["web_search", "cli"],
        "system_instructions": "You are a research assistant..."
    },
    task="Analyze competitor products"
)

Background Plugin

Manage long-running background tasks. Check status, retrieve output, and cancel tasks.

Name	background
Tools	checkBackgroundTask, getBackgroundOutput, cancelBackgroundTask, listBackgroundTasks
Auto-approved	All (read-only management)

Integration with CLI Plugin

When the CLI plugin auto-backgrounds a long-running command, this plugin provides tools to monitor and manage it.

Task Lifecycle

1. CLI command exceeds threshold -> backgrounded
2. Returns task handle immediately
3. Model uses background plugin to check status
4. Retrieve output when complete

# Check task status
checkBackgroundTask(task_id="cli_abc123")

# Response
{
  "task_id": "cli_abc123",
  "status": "running",
  "elapsed_seconds": 45
}

# Get output when complete
getBackgroundOutput(task_id="cli_abc123")

# Response
{
  "task_id": "cli_abc123",
  "status": "completed",
  "result": {
    "stdout": "Build completed successfully...",
    "returncode": 0
  }
}

# List all tasks
listBackgroundTasks()

# Cancel a task
cancelBackgroundTask(task_id="cli_abc123")

GC Plugins

Garbage collection plugins manage context window limits by removing or summarizing old conversation history.

See GC Plugin documentation for detailed information on all three strategies (truncate, summarize, hybrid), configuration options, and programmatic usage.

Available Strategies

• gc_truncate: Simple truncation. Removes oldest messages when context exceeds limit.
• gc_summarize: Summarization. Compresses old messages into a summary.
• gc_hybrid: Generational. Preserves recent, summarizes middle, truncates ancient.

{
  "type": "hybrid",
  "threshold_percent": 80.0,
  "preserve_recent_turns": 5,
  "summarize_middle_turns": 10
}

See gc.html for:
- Detailed strategy comparison
- All configuration options
- File-based and programmatic setup
- Manual GC triggering
- Strategy selection guide