# Routing (codescout-companion 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 `symbols` or `semantic_search`.

The `codescout-companion` 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 `workspace(action: activate)` 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(action: build)` call.

## Installation

```
/plugin marketplace add mareurs/sdd-misc-plugins
/plugin install codescout-companion@sdd-misc-plugins
```

See the [Routing Plugin setup guide](../getting-started/routing-plugin.md) for
configuration options.

## Further Reading

- [Routing Plugin Setup Guide](../getting-started/routing-plugin.md) — installation
  steps, configuration options, and verification
- [Superpowers Workflow](superpowers.md) — the Superpowers plugin that pairs
  with `codescout-companion` for full lifecycle development
