Tool System

Tools are the agent's actions. All tools implement the Tool ABC from navi/tools/base.py.

Two tiers

Built-in tools (navi/tools/)

Registered in build_default_registries() as builtins. Never removed on hot-reload.

User tools (tools/*.py)

Written by the agent via write_tool or manually. Auto-discovered at startup.

• Files starting with _ are ignored.
• tools/enabled.json — list of user tool names to include in all profiles automatically.
• tools/_template.py — canonical format reference (not loaded).

Currently present: get_current_datetime.py, gmail.py, weather.py.

Tool formats

Module-level format (preferred for user tools)

name = "my_tool"
description = "What it does and when to use it — be specific."
parameters = {
    "type": "object",
    "properties": {
        "param": {"type": "string", "description": "..."}
    },
    "required": ["param"]
}

async def execute(params: dict) -> str:
    # Return a plain string on success.
    # Raise an exception to signal failure.
    return "result"

No classes, no module-level print(). The loader wraps execute in a Tool subclass automatically.

Class-based format (built-in tools)

from navi.tools.base import Tool, ToolResult

class MyTool(Tool):
    name = "my_tool"
    description = "..."
    parameters = {"type": "object", "properties": {...}, "required": [...]}

    async def execute(self, params: dict) -> ToolResult:
        return ToolResult(success=True, output="result")

ToolResult fields:

• success: bool
• output: str — always a string; LLM sees this
• error: str | None — included in output on failure via to_message_content()
• metadata: dict — internal hints (e.g. is_image: True → triggers image injection into context)

Tool loading (navi/tools/loader.py)

load_tools_from_dir(tools_dir) returns LoadResult(loaded, errors).

Load order:

1. Try module-level format (checks for name, description, parameters, execute).
2. Fall back to class-based (scans for Tool subclasses).

Errors are isolated per file — one broken file does not prevent others from loading. Errors are logged and returned in LoadResult.errors.

Hot-reload

reload_tools tool calls ToolRegistry.reload_user_tools(tools_dir):

1. Drops all tools that are NOT in _builtin_names.
2. Re-runs load_tools_from_dir.
3. New tools registered without server restart.

New tools become available from the next user message (tool schemas are built at run_stream() entry, not during execution).

Self-extension via write_tool

WriteToolTool validates the code before writing (checks for the 4 required definitions). On success:

1. Writes the file to tools/{name}.py.
2. Adds the name to tools/enabled.json.
3. Calls reload_user_tools() — tool is registered immediately.

The agent should call tool_manual("write_tool") before using write_tool for the first time — the manual at manuals/write_tool.md has the full format reference and a complete example.

Scratchpad and Todo

Both are per-session, stored in-memory keyed by current_session_id.

Scratchpad — named sections for working notes within a task. Operations: write, append, read, clear. Subagents get isolated scratchpads (unique UUID-based session ID in run_ephemeral()).

Todo — checklist for tracking multi-step plans. Operations: set (replace all tasks), update (set status of one task), read. Statuses: pending, in_progress, done, failed, skipped.

Image tool flow

When image_view succeeds, it returns ToolResult with metadata={"is_image": True, "base64": "..."}.

The agent detects this and appends a synthetic user message with the image to session.context (but not session.messages). This makes the image visible to the next LLM call without polluting the display history.

See sessions.md for the dual-buffer design.