Tools & plugins#
Tools are the leaf functions agents call. Plugins are how you ship new tools, skills, commands, sub-agents, and hooks — either internal packages or Claude Code marketplace-format plugins.
Tools, built-in#
swarm ships 38 tools across 10 categories. They're regular Python functions; their docstrings become OpenAI-format schemas the LLM sees.
| Category | Examples |
|---|---|
| Data | load_dataset, profile_data, clean_data, split_train_test |
| Training | train_classifier, train_regressor, tune_hyperparams, cross_validate |
| Evaluation | evaluate_model, compare_models, explain_model, detect_drift |
| Compliance | fairness_audit, generate_model_card, export_audit_report |
| Deployment | package_model, deploy_serving, shadow_traffic, promote_challenger |
| Knowledge | retrieve_knowledge (RAG), search_algorithm_registry |
| Execution | execute_python, execute_shell (behind allowlist) |
| Search | web_search (Tavily / SerpAPI) |
| Filesystem | read_file, write_file, list_directory |
| MCP-bridged | any MCP server's tools (see below) |
Tools are listed in ml_team/tools/IMPLEMENTATION_README.md.
Per-agent allowlists#
An agent can only call tools on its allowlist. Attempts to call outside the list are caught by the permission engine, logged, and returned as a denied result with an attribution.
# In config/agent_defs.py
AgentConfig(
name="data_cleaner",
tools=["load_dataset", "clean_data", "execute_python"], # allowlist
...
)
If data_cleaner's LLM decides to call deploy_serving, the dispatch is denied before the function runs. See Permissions & audit.
Parallel tool dispatch#
Tools tagged parallel_safe=True can be called concurrently by the same agent turn. On a turn where the LLM emits 3 parallel-safe tool calls, they run in a thread pool. Unsafe tools fall back to sequential. Implemented at ml_team/core/tool_executor.py.
Plugins#
A plugin is a directory containing .claude-plugin/plugin.json + optional skills/, commands/, agents/, hooks/, .mcp.json. swarm's loader is fully compatible with the Claude Code marketplace plugin format.
What a plugin can ship#
| Surface | What it is | Fires when |
|---|---|---|
Skills (skills/<name>/SKILL.md) |
Procedural knowledge — keyword-matched, injected into system prompt | Agent context matches skill keywords |
Commands (commands/<name>.md) |
Slash-command templates with $ARGUMENTS substitution |
Invoked explicitly via REST/CLI |
Sub-agents (agents/<name>.md) |
Specialized agent definitions | Pipeline or user invokes by name |
Hooks (hooks/hooks.json) |
Lifecycle callbacks — SessionStart, PreTool, PostTool, compaction events |
Corresponding lifecycle event fires |
MCP servers (.mcp.json) |
External tool providers over MCP protocol | Tools proxied through on first use |
Install + uninstall#
# Install from local path
swarm plugins install /path/to/superpowers
# List
swarm plugins list
# Uninstall (cleans up all contributed surfaces)
swarm plugins uninstall superpowers
Verified compat#
We run a matrix smoke test against 16 real Claude Code marketplace plugins:
| Plugin | Skills | Commands | Agents | Hooks | MCP |
|---|---|---|---|---|---|
plugin-dev |
7 | 1 | 3 | — | — |
pr-review-toolkit |
— | 1 | 6 | — | — |
hookify |
1 | 4 | 1 | 1 | — |
feature-dev |
— | 1 | 3 | — | — |
superpowers |
14 | 3 | 1 | 1 | — |
claude-mem |
5 | — | — | 1 | 1 |
github / context7 / discord / … |
— | — | — | — | 1 |
See How-to: Install a Claude Code plugin for the full matrix + setup.
Shell-command hooks (security)#
Plugins can ship type: command hooks that execute shell commands on lifecycle events. This is disabled by default behind the plugin_shell_hooks_enabled feature flag, because shell execution is a material trust choice.
When enabled, invocations:
- Validate each command against a global allowlist + the plugin's own declared allowed_shell_commands
- Inject CLAUDE_PLUGIN_ROOT env var; scrub the rest
- Apply rlimits (CPU / AS / NOFILE on Linux) and a hard timeout
- Log every execution to the plugin_shell_executions audit table
See Source code protection for the BFSI-appropriate security model.
MCP servers#
A plugin's .mcp.json declares MCP servers. On install, each server is registered with the CompositeToolExecutor under the namespace plugin:<plugin>:<server>. Tools exposed by the MCP server become agent-callable with the same namespace prefix.
Supported transports: stdio (subprocess) and streamable HTTP / SSE (spec 2025-11-25).
Writing your own plugin#
See How-to: Write a custom tool and Tutorial: Plugin authoring.
Next#
- Permissions & audit — how tool calls are gated
- Hooks & ops — the lifecycle callbacks plugins register for
- Install a CC plugin