feat: add config option to disable MCP response hints

[HumanBean17]

Summary

• Add hints.enabled YAML key (.java-codebase-rag.yml) and JAVA_CODEBASE_RAG_HINTS_ENABLED env var to suppress hints_structured and advisories from all MCP tool responses
• Defaults to true (enabled) so existing users see no behavior change
• When disabled, skips generate_hints() entirely — saves ~300–800 tokens per response for capable models that don't need navigation guidance

User-visible changes

• New YAML section: hints.enabled: true|false
• New env var: JAVA_CODEBASE_RAG_HINTS_ENABLED (1/true/yes or 0/false/no)
• java-codebase-rag meta now reports hints_enabled and hints_enabled_source
• No re-index required, no schema changes

Test plan

• All 617 tests pass (python3 -m pytest tests -v)
• ruff check clean on all changed files
• Manual: set hints.enabled: false in .java-codebase-rag.yml, verify tool responses have empty hints_structured and advisories

🤖 Generated with Claude Code

[HumanBean17]

Review

Implementation is clean, follows project conventions, and is low-risk. One actionable item:

No test coverage

This is the main gap. The repo has an established pattern for config resolution tests (e.g. test_embedding_device_precedence_cli_over_env_over_yaml_over_default at line 208). A comparable test for hints.enabled precedence should be added:

def test_hints_enabled_defaults_to_true(tmp_path, monkeypatch):
    monkeypatch.delenv("JAVA_CODEBASE_RAG_HINTS_ENABLED", raising=False)
    r = resolve_operator_config(source_root=tmp_path)
    assert r.hints_enabled is True
    assert r.hints_enabled_source == "default"

def test_hints_enabled_env_over_yaml_over_default(tmp_path, monkeypatch):
    monkeypatch.delenv("JAVA_CODEBASE_RAG_HINTS_ENABLED", raising=False)
    (tmp_path / ".java-codebase-rag.yml").write_text("hints:\n  enabled: false\n")
    r = resolve_operator_config(source_root=tmp_path)
    assert r.hints_enabled is False
    assert r.hints_enabled_source == "yaml"
    monkeypatch.setenv("JAVA_CODEBASE_RAG_HINTS_ENABLED", "1")
    r2 = resolve_operator_config(source_root=tmp_path)
    assert r2.hints_enabled is True
    assert r2.hints_enabled_source == "env"

A test verifying set_hints_enabled gates generate_hints in at least one tool handler would also be valuable (mock generate_hints and assert it's not called when disabled).

Minor: inconsistent ternary formatting in mcp_v2.py

In describe_v2, the ternary splits across 3 lines with the condition on the second line, while the other 4 handlers put the condition at the end of the first line. Consider a small helper to deduplicate the pattern and keep formatting consistent:

def _hints_or_skip(tool: str, payload: dict) -> tuple[list, list]:
    return generate_hints(tool, payload) if _hints_enabled else ([], [])

This reduces the 5 repeated ternaries to a single call each.

Everything else looks good — _pick_bool follows the same pattern as _pick_optional_device, docs are thorough, the module-level flag is appropriate for a stdio server initialized once at startup.