pi-tool-router

A dependency-free-at-runtime Pi extension package that keeps large tool sets manageable without taking ownership of tools it does not manage.

Install

pi install npm:pi-tool-router

Restart Pi, then use /tool-router in the TUI.

Workflow

1. The model calls tool_router_discover to search tool and skill manifests.
2. When candidates are found, Pi additively exposes tool_router_activate on the next model turn; the model calls it with an exact result id such as tool:web-search.
3. tool_router_deactivate is never automatically exposed. Use /tool-router deactivate to remove an on-demand capability manually.

In a normal Pi run, only tool_router_discover is initially active among router model tools; all three are registered. Explicit Pi/CLI tool allowlists such as --no-tools still win, so the router never force-enables discovery. Search never activates a listed capability, excludes router control tools, and combines exact name, category, alias, and BM25 description matching.

Policies

Policy	Router behavior
core	Protected and displayed as core. The router preserves the existing active state of read, edit, write, bash, and tool_router_discover; it never force-enables a core tool disabled by Pi or CLI policy.
always	Router keeps the tool active.
on-demand	Inactive until explicitly activated; branch-local activation is persisted in the Pi session.
disabled	Router keeps the tool inactive.
unmanaged	Router never changes its active state. This is the default for unknown tools.

mcp and mcpScript are always passthrough/unmanaged when present, so this package does not interfere with pi-mcp-adapter.

Commands

• /tool-router — TUI policy editor (SettingsList)
• /tool-router list
• /tool-router search <query>
• /tool-router activate <tool:name|skill:name> [...]
• /tool-router deactivate <tool:name|skill:name> [...]
• /tool-router policy <tool> <always|on-demand|disabled|unmanaged>
• /tool-router help
• /tool-router-resources — temporary, right-center TUI overlay of tools, MCP status, and skills

TUI-only overlays are guarded; textual subcommands work in UI-capable non-TUI modes through notifications.

Global configuration

The package reads and writes only:

$PI_CODING_AGENT_DIR/tool-router.json

or, when that variable is unset:

~/.pi/agent/tool-router.json

It never creates or edits project files. A config can enrich the capability manifests and select policies:

{
  "version": 1,
  "tools": {
    "web_search": {
      "policy": "on-demand",
      "category": "web research",
      "aliases": ["browse", "internet lookup"]
    }
  },
  "skills": {
    "firecrawl-search": {
      "category": "web research",
      "aliases": ["find articles"]
    }
  }
}

Tools are automatically categorized and aliased from their names and descriptions for web, browser, LSP, image, database, test, git, document, cloud, and workspace searches; configuration can refine that metadata.

Skills are Pi-discovered resources, not active Pi tools. Their /tool-router-resources state is discovered, then branch-local selected, loaded, or failed. Raw /skill:name invocation is marked loaded because Pi expands the full skill content. The router also marks an exact, unpaginated SKILL.md read loaded (or an exact failed read failed); partial reads do not change the loaded state. Pi continues to own actual skill discovery and invocation (/skill:name).

MCP integration

The extension subscribes to the shared event channel pi-mcp-adapter/status/v1 without importing pi-mcp-adapter. /tool-router-resources shows the received server snapshot. The router's namespaced footer status (pi-tool-router:anomaly) is set only for configuration failures or failed/auth-required MCP servers.

Development

npm test
npm pack --dry-run

Tests cover the pure ranking and policy reconciliation helpers. The package has no dependencies; Pi-provided packages are peer dependencies.