feat: improve codegraph tool visibility for AI agents

[HUQIANTAO]

Background

CodeGraph provides symbol-level code intelligence (call graphs, impact analysis, symbol search) via MCP tools, but AI agents overwhelmingly default to grep/read_file/ls even for architecture and call-graph questions where codegraph tools are strictly superior.

Root Cause Analysis

The issue is systemic — multiple reinforcing factors create a "guidance vacuum" around codegraph tools:

Factor	Impact
System prompt mentions only ask and todo_write	Model unaware of codegraph's existence
bashToolSteer explicitly directs to grep, read_file, ls, glob, edit_file	Reinforces file-level toolchain every turn
explore skill body: "Use read_file, grep, glob, ls as your primary tools"	Subagents cannot use codegraph
Subagent AllowedTools whitelist excludes codegraph	Even if mentioned, subagents can't call them
Tool name mcp__codegraph__codegraph_context (32 chars) vs read_file (9 chars)	Naming asymmetry reduces discoverability
Alphabetical sort places mcp__codegraph__* last	Positional bias in tool selection

The result is a self-reinforcing cycle: the model uses grep → succeeds → never discovers codegraph → continues using grep.

Solution

Four targeted interventions at the guidance layer, ordered by blast radius:

1. System prompt steering (highest impact)

Inject a SteerText block into the system prompt when codegraph tools are registered, mapping each tool to its use case (e.g. codegraph_context for "how does X work", codegraph_callers for "who calls X"). This is the single highest-leverage change — it reaches every turn without requiring the model to discover tools on its own.

Files: internal/codegraph/codegraph.go, internal/boot/boot.go

2. Tool description cross-reference

Append a codegraph hint to bashToolSteer so the bash tool's description (visible every turn) reminds the model that symbol-level questions have a dedicated tool class.

File: internal/tool/builtin/bash.go

3. Skill body and allowed-tools update

Update all four read-only subagent skill bodies (explore, research, review, security-review) to prefer codegraph tools for symbol/code-structure questions, with grep/read_file as fallback. Introduce SetExtraReadTools() to dynamically inject codegraph tool names into the subagent AllowedTools whitelist at boot time — avoids hardcoding MCP-prefixed names that change with the strip prefix.

File: internal/skill/builtins.go

4. Tool name deduplication

Add StripRawPrefix field to plugin.Spec. When set, the prefix is stripped from each MCP tool's raw name before namespacing — codegraph_context becomes context, yielding mcp__codegraph__context instead of the redundant mcp__codegraph__codegraph_context. Applied in both listTools() (live handshake) and the lazy-tier cache path. The original raw name is preserved for MCP protocol calls.

Files: internal/plugin/plugin.go, internal/plugin/lazy.go

Verification

go test ./internal/...    # all packages pass

• System prompt injection is gated on cfg.Codegraph.Enabled and tool presence in registry — no-op when codegraph is disabled or unavailable
• SetExtraReadTools() is empty by default; existing TestBuiltinSubagentSkillsDeclareAllowedTools passes unchanged
• StripRawPrefix does not affect SpecFingerprint (cache stores raw names; strip is applied at read time), so no cache invalidation side effects