MCP tools lack readOnlyHint annotations — Claude Code plan mode blocks/prompts every codesearch call #339

Summary

None of codesearch's MCP tools declare annotations (no readOnlyHint). As a result, Claude Code's plan mode blocks or prompts on every codesearch call. This happens in the main session and in subagents (Explore/Plan). In -p mode the call fails with Cannot call mcp__codesearch__search while in plan mode.

Plan mode auto-allows only MCP tools that declare readOnlyHint: true. Plugin hooks cannot work around this anymore. On Claude Code 2.1.301, an allow returned from a plugin's tool.check hook is ignored in plan mode:

tool.check mcp__codesearch__search …: ask -> allow by plugin …
tool.check mcp__codesearch__search …: plan mode holds the call, so the plugins' allow is ignored; continuing with the engine's own decision (ask)
mcp_tool tool permission denied

Evidence

• On v1.2.4, a tools/list response showed annotations: null for all six tools: search, find, explore, get_chunk, status, find_impact.
• On v1.5.2 (current main), none of the #[tool(...)] attributes in src/mcp/*.rs set annotations.

Proposal

All six tools are read-only queries against the index. rmcp supports annotations directly in the attribute, for example:

#[tool(
    description = "…",
    annotations(read_only_hint = true, destructive_hint = false, idempotent_hint = true, open_world_hint = false)
)]

Declaring these on search, find, explore, get_chunk, status and find_impact would make codesearch usable in plan mode without any wrapper. If a write-capable tool is added later, it should keep these hints off.

Current workaround

We wrap the server with a small stdio proxy. It adds { readOnlyHint: true, destructiveHint: false } to these six tools in the tools/list response and leaves any annotations that are already present unchanged. With the proxy, plan mode works: the main session and subagents can call search/status with no prompt. We would happily drop the proxy once the annotations ship upstream.

Thanks for codesearch!