feat(mcp): reduce agent token burn with text-v1 format and code_read cap

[jlitola]

Summary

• Real-session traces showed GitHits MCP responses dominating agent context (4M tokens / session), driven by JSON wrapping plus broad code_read calls (300-600 line windows, occasional unbounded reads).
• This change adds a compact text-v1 default to search / code_files / code_grep, hard-caps code_read at 150 lines per call on the MCP surface, and rewrites the MCP server instructions block to lead with delegation guidance.

Results across three test sessions

Run	Total tokens	code_read max single payload
baseline (githits1)	2.43M	22.8 KB
text format only (githits2)	4.05M	22.8 KB
text format + code_read cap (githits3)	2.06M	6.8 KB

Total dropped 4.06M → 2.06M; max code_read dropped 22.8 KB → 6.8 KB.

Changes

Tool surface

• Add format: "json" \| "text" \| "text-v1" to search, code_files, and code_grep. Default is text-v1; programmatic / parity callers opt into JSON.
• New text formatters in src/shared/{unified-search,list-files,grep-repo}-text.ts — ASCII-only, snapshot-tested.
• MCP-side cap on code_read (MCP_READ_MAX_SPAN = 150) with a hint field describing returned vs. requested ranges. CLI githits code read bypasses the cap so humans piping whole files still works.
• Hint reads the actual returned range from the response payload (not the pre-clamp request) and is suppressed when the cap was a no-op (file fits within cap or returned range reaches EOF).

Instructions

• Expand CORE_BLOCK trigger criteria to cover comparative cross-OSS questions and "how does X actually work" archaeology.
• Strengthened MULTI_TURN_TIP leads the gated package-tools section: "Delegate multi-call work to a sub-agent. Code-navigation tools are inherently multi-call — answering even simple questions usually takes 3-10 tool calls..."
• New REFERENCE_FIRST_TIP workflow paragraph after the per-tool bullets.
• Per-tool bullets and DESCRIPTION constants rewritten to reflect text-v1 defaults instead of JSON-shaped fields.

Docs

• docs/implementation/tools.md documents the text-v1 spec (per-tool anatomy), the code_read cap and hint field, and the expanded server-instructions composition.

Test plan

• bun test — 1446 tests passing
• bun run build — clean
• Three real-session runs against .mcp.json showing the token / payload reductions above
• Codex review pass 1 — fixed before merge: ASCII separators only, text-v1 versioning, dropped invalid feedback footer / license field / > snippet prefix from draft, replaced code_read truncation hint with envelope hint field
• Codex review pass 2 — fixed before merge: hint suppression refactored to use actual returned span (not explicitness flags); doc-comments updated; parity test header refreshed; implicit-default test coverage added
• Codex review pass 3 — fixed before merge: hint now reports actual returned range from payload (not pre-clamp request), suppresses when cap is no-op or response reaches EOF; per-tool bullets describe text-v1 default behavior

Open follow-ups (not in this PR)

• Multi-range code_read (accept ranges: Array<{start_line, end_line}> with per-range cap and total cap) — only worth it if the fixed cap doesn't deliver enough savings on real traffic.
• format: "text-v1" on search_status once the format has soaked elsewhere.
• Once stable, consider text-v2 that drops the query= echo from the search header and the score field.

🤖 Generated with Claude Code