feat(mcp): gate duplicate read tools behind MCP_READ_TOOLS (native-first retrieval)

[bamaas]

Summary

Filesystem-capable agents (e.g. the Hermes daemon, which mounts the vault) were over-relying on the MCP content-read tools that merely duplicate direct file access. That funnels reactive exploration through narrower, capped tool contracts (grep_vault is substring-only, ≤20 results) and undercuts the reason an agent was chosen over RAG: free file access.

This gates the seven duplicate content-read tools behind a new MCP_READ_TOOLS env var (default false), so the existing AGENTS.md guidance ("read directly") is enforced, not just suggested.

• Gated (off by default): get_soul, search_index, read_wiki, grep_vault, read_note, read_raw, vault_overview
• Always registered: graph tools related_notes, expand_graph (need the SQLite edge index — not reconstructable from a single file read) and all writes add_bookmark, add_note, update_wiki, delete_page
• Clients without filesystem access (e.g. OpenWebUI over HTTP) set MCP_READ_TOOLS=true to restore the read tools — no client is permanently broken.

The flag threads through Run / NewServer / registerTools and RegisteredTools(readTools), plus cmd (loadConfig, the in-process server, AGENTS.md generation, and the standalone mcp subcommand), so the auto-generated AGENTS.md tool list always matches the live tool surface. The template's "optional accelerators" section now tells agents to trust the live Available MCP Tools list and read files directly when a named tool is absent.

Citation/source-attribution behaviour is unaffected — native reads expose each wiki page's source: frontmatter and *Source: [title](url)* footer, which AGENTS.md already requires agents to cite.

Why a flag (reversible experiment)

Native-first retrieval trades purpose-built guardrails for raw flexibility; whether it beats MCP-read retrieval depends on the agent's navigation competence — an empirical question. The flag enables an A/B comparison (citation rate, recall, wasted reads) per deployment.

ADR: docs/adr/023-native-first-retrieval-read-tool-gating.md

Test plan

• New cmd test: MCP_READ_TOOLS parsing (unset/empty/garbage → off; true/1 → on).
• mcpserver tests: RegisteredTools(false) excludes the 7 read tools and includes always-on; RegisteredTools(true) includes all; live server omits read tools when readTools=false; existing RegisteredToolsMatchesServer now runs for both flag states.
• Full suite green; all linters pass (go, dockerfile, actions, yaml, markdown, vuln).

🤖 Generated with Claude Code