Tool Plugins
Tool plugins give the agent capabilities to interact with the outside world. Each tool registers itself via the event bus — agents discover tools automatically.
Available Tools
| Plugin | ID | Tool Name | Description |
|---|---|---|---|
| Shell | nexus.tool.shell | shell | Execute shell commands |
| File I/O | nexus.tool.file | read_file, write_file, list_files | Read, write, and list files |
| PDF Reader | nexus.tool.pdf | read_pdf | Extract text from PDF files |
| File Opener | nexus.tool.opener | open_path | Open files in the OS default app |
| Human-in-the-Loop | nexus.control.hitl | ask_user | Ask the user a question or approve an action (multi-choice supported) |
| Code Exec | nexus.tool.code_exec | run_code | Run a Go script that orchestrates multiple tool calls in one turn |
| Knowledge Search | nexus.tool.knowledge_search | knowledge_search | Semantic search over configured RAG namespaces; returns top-k chunks with source paths for citation |
How Tools Work
- Tool plugin initializes and emits
tool.registerwith its tool definition (name, description, JSON Schema parameters) - The agent collects registered tools and includes them in
llm.request - When the LLM responds with a tool call, the agent emits
before:tool.invoke(vetoable for approval) - If not vetoed, the agent emits
tool.invoke - The tool plugin handles the invocation and emits
before:tool.result(vetoable — gates can inspect/block results) - If not vetoed, the tool plugin emits
tool.result - The agent feeds the result back to the LLM
Tool Registration Event
Each tool emits a tool.register event with a ToolDef:
type ToolDef struct {
Name string // Tool name the LLM will use
Description string // Description shown to the LLM
Parameters string // JSON Schema for parameters
}
Approval Flow
The before:tool.invoke event is vetoable. I/O plugins (TUI, Browser) can intercept this to show an approval dialog, especially for high-risk operations like shell commands.