
tool-routing
- version
- 1.4.0
- GitHub stars
- 13
Install
/plugin install tool-routing@pickled-claude-pluginsRun it inside Claude Code after adding the marketplace with /plugin marketplace add technicalpickles/pickled-claude-plugins.
Contents
Discovered from sourceCommands 1
Validate Tool-Routing Plugin
Run these steps to verify the tool-routing plugin is correctly installed and working.
Monorepo Context
This plugin is part of the pickled-claude-plugins monorepo. Routes are contributed by multiple plugins:
| Plugin | Route Location | Routes |
|---|---|---|
| tool-routing | hooks/tool-routes.yaml | bash-cat-heredoc, bash-echo-*, tool-routing-manual-test |
| dev-tools | hooks/tool-routes.yaml | atlassian |
| git | skills/pull-request/tool-routes.yaml | github-pr |
| buildkite | tool-routes.yaml | buildkite |
Quick Validation (Isolated Environment)
Use test-claude to validate in an isolated environment without affecting your normal Claude config:
# From repo root - sets up config, installs all plugins, starts claude
./bin/test-claude
# Or run validation commands in the isolated env
CLAUDE_CONFIG_DIR="$PWD/tmp/test-claude-config" \
uv run --directory plugins/tool-routing tool-routing list
# Should show: "Routes (merged from 4 sources)"
Use ./bin/test-claude --clean to remove the test config and start fresh.
This approach:
- Doesn't modify your user plugin state
- Installs plugins from local source (not marketplace cache)
- Tests the actual discovery path Claude Code uses
Step 1: Validate Plugin Manifests
Run claude plugin validate on each plugin with a manifest:
# From repo root
for plugin in plugins/*/; do
if [ -d "$plugin/.claude-plugin" ]; then
echo "=== Validating $plugin ==="
claude plugin validate "$plugin"
fi
done
Step 2: Run Plugin Structure Tests
The plugin includes pytest tests that validate hooks.json format:
cd plugins/tool-routing
uv run pytest tests/test_plugin_structure.py -v
These tests catch silent failures where hooks.json is valid JSON but wrong format:
| Wrong Format | Correct Format |
|---|---|
"hooks": [...] (array) | "hooks": {"PreToolUse": [...]} (object keyed by event) |
"matcher": {"tool_name": "X"} | "matcher": "X" (string pattern) |
"type": "preToolUse" | "type": "command" |
$CLAUDE_PLUGIN_ROOT | ${CLAUDE_PLUGIN_ROOT} (with braces) |
Step 3: Run Route Pattern Tests
Test that route patterns match correctly:
Option A: Using test-claude (Recommended)
Uses isolated config with all plugins installed:
# Ensure test config exists (setup + exit immediately)
./bin/test-claude -p ""
# Run tests in isolated env
CLAUDE_CONFIG_DIR="$PWD/tmp/test-claude-config" \
uv run --directory plugins/tool-routing tool-routing test
Option B: Using explicit routes (No discovery)
Bypasses discovery entirely - useful for testing specific route files:
TOOL_ROUTING_ROUTES="plugins/tool-routing/hooks/tool-routes.yaml,plugins/git/skills/pull-request/tool-routes.yaml,plugins/buildkite/tool-routes.yaml" \
uv run --directory plugins/tool-routing tool-routing test
Option C: Using user's enabled plugins
Uses your current Claude config - results depend on which plugins you have enabled:
CLAUDE_PROJECT_ROOT="$PWD" uv run --directory plugins/tool-routing tool-routing test
Step 4: Test at Runtime
After the above pass, test that hooks actually fire:
- Restart Claude Code (hooks are captured at startup)
- Try a blocked tool call, e.g.:
WebFetch https://github.com/owner/repo/pull/123 - Expected: Request blocked with message suggesting
gh pr view
If the WebFetch goes through instead of being blocked, the hooks aren't loading. Check:
- Plugin is enabled:
/plugin→ Manage Plugins - Restart happened after latest changes
claude --debugfor hook loading errors
Step 5: Check Debug Output (if issues)
Run Claude Code with debug logging:
claude --debug
Look for:
[DEBUG] Executing hooks for PreToolUse:WebFetch- Any errors during hook registration
Common Issues
| Symptom | Cause | Fix |
|---|---|---|
| WebFetch not blocked | Hooks not loading | Check format, restart Claude Code |
| "No module named tool_routing" | Wrong working directory | Run from plugin root with uv run |
| Plugin not in list | Missing manifest | Create .claude-plugin/plugin.json |
| Tests fail on matcher format | Old hooks.json format | Update to object-keyed structure |
| Fewer sources than expected | Plugin not enabled, or wrong project path | Use test-claude or TOOL_ROUTING_ROUTES |
Troubleshooting Route Discovery
If tool-routing list shows fewer sources than expected:
-
Use test-claude for reliable results - avoids project path issues:
./bin/test-claude --clean # Remove old config ./bin/test-claude -p "" # Reinitialize (exits immediately) CLAUDE_CONFIG_DIR="$PWD/tmp/test-claude-config" uv run --directory plugins/tool-routing tool-routing list -
Check plugin enabled status:
claude plugin list --json | jq '.[] | select(.enabled) | {id, scope, projectPath}' -
Check routes.json manifests exist:
for p in tool-routing git ci-cd-tools dev-tools; do echo "=== $p ===" cat plugins/$p/.claude-plugin/routes.json 2>/dev/null || echo "No routes.json" done -
Project path matching: Local-scoped plugins require exact
projectPathmatch. Running fromplugins/tool-routing/won't find plugins scoped to the repo root.
See docs/route-discovery.md#troubleshooting for more details.
Step 6: Run Integration Tests (Optional)
For full verification that hooks actually block at runtime, use subagents:
-
Get test cases:
uv run tool-routing integration-test --list > .tmp/integration-tests.json -
Spawn a subagent to execute the tests. The subagent should:
- Attempt each tool call exactly as specified
- Report results as JSON array:
[{"id": 0, "result": "blocked", "message": "..."}, ...]
-
Save the subagent's JSON report to
.tmp/integration-report.json -
Evaluate results:
uv run tool-routing integration-test --evaluate \ --tests .tmp/integration-tests.json \ --report .tmp/integration-report.json
This verifies the full integration path: Claude Code → hooks → tool-routing check → block/allow.
Copying These Tests to Other Plugins
The tests/test_plugin_structure.py file can be adapted for any plugin with hooks. Copy it and adjust:
PLUGIN_ROOTpath- Which tests to skip if plugin doesn't use certain features
Hooks 1
Sponsors
Details
- Marketplace
- technicalpickles/pickled-claude-plugins
- Source
- plugins/tool-routing
- Category
- Community
More from technicalpickles/pickled-claude-plugins
All 26- wait-for-itv0.2.2
- woodpeckerv0.4.0
- working-in-monoreposv1.0.4
- writing-toolsv0.3.0
- actually-lspv0.7.1
- agent-metav3.4.1
- automic-vaultv0.3.0
- buildkitev1.1.4
- ci-cd-toolsv1.2.2
- come-onv0.2.1
- cqv0.3.1
- dev-toolsv1.5.0
- gitv3.6.0
- github-actionsv0.1.1
- hkv0.2.0
- inflight-artifactv0.5.0
- mcpproxyv1.0.2
- petri-dishv0.1.0
- pickle-modev0.3.0
- sandbox-advisorv0.3.0
- second-brainv2.2.0
- stay-on-targetv1.0.1
- stay-principledv0.1.1
- tailscalev0.5.0