Skip to content

routing-plugin.md

Latest commit

 

History

History
103 lines (76 loc) · 4.6 KB

routing-plugin.md

File metadata and controls

103 lines (76 loc) · 4.6 KB

The Routing Plugin

Why It Exists

The MCP server delivers 28 tools and a detailed server_instructions block that tells the AI when to use each one. In a single-agent session this works well — the main agent receives the instructions and generally follows them.

The problem is subagents.

Every time Claude Code spawns a subagent (a code reviewer, a parallel worker, a debugging agent), that subagent starts with a blank slate. It has the MCP tools available, but it has never seen the server_instructions. Its default instinct is to reach for the native tools it was trained on: Read, Grep, Glob, Bash cat. Without intervention it will happily read whole files, grep walls of text, and never touch find_symbol or semantic_search.

The routing plugin exists to close that gap. It injects guidance into every agent and every subagent, and hard-blocks the native tool patterns that codescout is designed to replace.

How It Integrates with the MCP Server

The plugin is intentionally tightly coupled to codescout:

  • It reads codescout's SQLite embeddings DB to check index staleness and surface drift warnings at session start
  • It calls the codescout CLI binary to trigger background reindexing when the index is behind HEAD
  • It injects the .codescout/system-prompt.md file — generated by the onboarding() tool — verbatim into every agent's context. This file contains project-specific navigation hints, entry points, and memory pointers that onboarding() tailored to the codebase.

The plugin should be updated whenever codescout adds features that affect exploration workflows.

Hooks

Hook Event What it does
session-start.sh SessionStart Injects tool guide, memory hints, drift warnings, and onboarding nudge into the main agent
subagent-guidance.sh SubagentStart Injects compact tool-use directive + system-prompt.md into every subagent
pre-tool-guard.sh PreToolUse on Read/Grep/Glob/Bash Hard-blocks Read/Grep/Glob and Bash cat/grep/head/tail/sed -i on source files; redirects to codescout equivalents
worktree-activate.sh PostToolUse on EnterWorktree Symlinks .codescout/ into the new worktree and injects activate_project guidance

Why Hard Blocks, Not Soft Warnings

The plugin went through a soft-warning phase (v1.1–v1.4): a PostToolUse hook would fire after a Read or Grep call and append a message suggesting codescout alternatives. This did not work.

By the time the PostToolUse hook fires, the tool output is already in context. The AI has the file contents or grep results it was looking for — the warning is noise it ignores, and the damage (token waste, context pollution) is already done.

Switching to PreToolUse hard blocks (v1.5) fixed this. The block fires before the tool executes. No output lands in context; the AI is forced to re-plan with a codescout tool instead. This is the approach that actually changes behaviour.

The Subagent Coverage Problem

SubagentStart guidance (v1.5.3) always fires, even when .codescout/system-prompt.md doesn't exist. Before this fix, the hook silently exited when the file was absent — leaving subagents (code reviewers, design agents, parallel workers) with no guidance at all. The result was that subagent behaviour was completely inconsistent: the main agent used codescout correctly, subagents fell back to native tools immediately.

The fix was simple: always inject a minimal tool-use directive into subagents, regardless of whether a project-specific system prompt exists.

Auto-Reindex and Drift Warnings

At SessionStart, the plugin checks whether the semantic index is behind HEAD:

  1. Queries the embeddings DB for the last-indexed commit
  2. Compares against git rev-parse HEAD
  3. If stale, triggers codescout index --project . in the background (non-blocking)
  4. If high-drift files are detected (files where meaning changed significantly since last index), surfaces a warning in the session context

This means the index is usually up to date by the time the AI needs it, without requiring a manual index_project call.

Installation

/plugin marketplace add mareurs/sdd-misc-plugins
/plugin install code-explorer-routing@sdd-misc-plugins

See the Routing Plugin setup guide for configuration options.

Further Reading