Pluggable Tool Registry -- runtime registration, config.toml overrides, and plugin tools

[aboimpinto]

Summary

Layer 3 of the Pluggable Tool Registry (#1802): runtime tool registration with config.toml overrides, auto-discovery of plugin scripts from ~/.deepseek/tools/, and an enterprise audit wrapper example.

Changes

Config.toml overrides ([tools.overrides])

Users can replace any built-in tool or disable it entirely — no fork, no recompile:

• { type = "script", path = "wrapper.sh" } — run a script as the implementation
• { type = "command", command = "bat", args = [...] } — run a command
• { type = "disabled" } — remove the tool from the model's catalog

Plugin tool auto-discovery

Scripts dropped in ~/.deepseek/tools/ with frontmatter headers are auto-registered:

• Supports #, //, and -- comment prefixes
• Frontmatter: name, description, schema, approval
• Script receives JSON on stdin, returns ToolResult JSON on stdout
• Shebang resolution routes through the correct interpreter

Enterprise audit wrapper example

An exec_shell override script that logs every command with a timestamp before executing.

Implementation

• ScriptPluginTool, CommandPluginTool — implement ToolSpec
• ToolRegistry: remove_tool(), apply_overrides(), load_plugins()
• Plugin tools are never deferred (immediately visible to the model)
• Shebang + extension-based interpreter resolution

Parent

Closes the Layer 3 portion of #1802

[aboimpinto]

Implementation Notes

No [tools] config required

The default ~/.deepseek/tools/ directory is always scanned — no config change needed. Just drop a script there with frontmatter and it works. The [tools] table in config.toml is only needed for:

• Custom plugin directory path
• Built-in tool overrides ([tools.overrides])
• Disabling tools

How it works end-to-end (count_words example)

1. The script — ~/.deepseek/tools/count-words.mjs:

#!/usr/bin/env node
// name: count_words
// description: Count words, lines, and characters in text
// schema: {"type":"object","properties":{"text":...},"required":["text"]}
// approval: auto

process.stdin.on('data', c => {
  const { text } = JSON.parse(c);
  const words = text.trim() ? text.trim().split(/\s+/).length : 0;
  const lines = text.split('\n').length;
  process.stdout.write(JSON.stringify({
    content: `${words} words, ${lines} lines, ${chars} characters`,
    success: true
  }));
});

2. Registration — On session start, the engine scans ~/.deepseek/tools/, reads the frontmatter (// name:, // description:, // schema:), and registers a ScriptPluginTool in the ToolRegistry. Plugin tools are automatically marked as non-deferred, so the model sees them immediately alongside built-in tools.

3. How the model discovers the tool — The tool appears in the API tool catalog sent with every request, just like read_file or exec_shell. The model reads its name (count_words), description (Count words, lines, and characters in text), and JSON schema, then decides to call it when the task matches.

4. Prompt to trigger it — The user types:

count the words in "hello world this is a test of the plugin system"

The model recognizes count_words as the right tool, calls it with {"text": "hello world this is a test of the plugin system"}. The engine spawns node count-words.mjs, pipes the JSON to stdin, reads the ToolResult JSON from stdout, and returns it to the model.

5. Interpreter resolution — The shebang #!/usr/bin/env node is parsed. On Windows, env doesn't exist, so the resolver strips it and runs node count-words.mjs directly. Extension-based fallback handles .ps1 -> powershell, .py -> python, .sh -> sh, etc.

Key design decisions

• stdin/stdout protocol: Simple pipe model — JSON in, ToolResult JSON out. No file system coupling, no temp files.
• Frontmatter over shebang: The # name:, # schema: headers use #, //, or -- comment prefixes so scripts in any language self-describe.
• Plugin tools are never deferred: User-registered tools are immediately visible to the model, unlike deferred built-in tools that require tool search first.
• PR feat: ShellDispatcher, ExternalTool wrappers, and pluggable tool registry #1848: Squashed into one commit, 9 files, +971/-14, on feat/pluggable-tool-registry-pr targeting main.