feat(forwarder): query SQL tool + OpenAI tool-use loop (#415)

[jonathaneoliver]

Summary

• Adds the SQL query tool that the LLM uses to read archived sessions, and the multi-step tool-use loop that drives multi-iteration interactions.
• Sub-issue 3 of epic epic: AI-assisted session analysis (chat + Analyze + compare) #412. Closes #415.
• Stacked on feat(forwarder): OpenAI-compatible LLM client + profile registry (#414) #423 (the LLM client + profiles). Once feat(forwarder): OpenAI-compatible LLM client + profile registry (#414) #423 lands, GitHub will retarget this PR's base to main automatically.

What's in the box

• llm_tool_query.go — QueryTool struct + Run(ctx, sql) *QueryToolResult + OpenAITool() schema. Hits ClickHouse via the same HTTP transport the forwarder already uses for inserts but as the constrained llm_reader identity. Forwarder enforces hard 10k-row / 10MB cap on response read because ClickHouse 24.8's max_result_rows is cooperative for streaming SELECTs (the real server fence is max_rows_to_read on input).
• llm_chat.go — RunChatTurn(ctx, profile, messages, opts) (*ChatTurnResult, error). Implements the OpenAI tool-use loop: model emits tool_calls → forwarder runs each via dispatcher → appends role:"tool" results → re-invokes → stops when model returns no tool_calls (final answer). Iteration cap from LLM_MAX_TOOL_CALLS_PER_TURN env (default 20). Per-iteration timeout 30s, aggregate turn timeout 120s.
• MakeQueryDispatcher(qt) — maps the query tool name through to QueryTool; rejects unknown names. The same dispatcher pattern will pick up the read-only control tools in forwarder + dashboard: read-only session control tools (get_session_state, get_failure_settings, …) #424.

Notable design choice — tool-budget exhaustion

Initial implementation just synthesized a "budget exhausted" tool-result message and let the loop continue. Pre-commit code-reviewer caught that the model could then keep emitting tool_calls right up to the iteration cap and never produce text — the wrap-up was aspirational, not enforced.

Fix: when the budget is blown, the forwarder sets ToolChoice: "none" on the next request, forcing the model to produce final text. If the model still ignores the directive (some providers don't honor it), we bail out with StoppedReason="tool_budget" and surface whatever content arrived. New body-inspection test (TestRunChatTurn_ToolBudgetForcesToolChoiceNone) verifies the gate actually fires by checking the JSON the scripted LLM received.

Other pre-commit-review fixes

• Defensive guard for finish_reason: "tool_calls" with an empty ToolCalls array (known provider bug) — returns StoppedReason="error" with "empty assistant message" detail.
• MarshalForTool's overflow path produced invalid JSON (...\"]}); replaced with a clean {"error":"result exceeded N bytes","truncated":true,"elapsed_ms":N} literal. Should never fire in practice (10k-row cap upstream), but if it does the LLM gets parseable data.
• Trimmed several "what" comments per the CLAUDE.md / memory rule. Kept the "why" comments and the cross-issue pointers.
• Test ID generator switched from '0'+i (silently breaks past i=9) to strconv.Itoa(i).

Test plan

• go test ./... — 33/33 pass.
• Tool-budget loop terminates with FinalText after exhaustion (verified by behavior test).
• tool_choice: "none" actually fires on the wrap-up request (verified by body-inspection test).
• QueryTool truncates at exactly 10000 rows when ClickHouse returns more.
• Outer context.Cancel propagates into QueryTool (sub-second response).
• Dispatcher errors round-trip back to the model without stopping the loop.
• Live-network smoke against a real ClickHouse + real LLM — manual / deploy-time, not in unit-test scope.

🤖 Generated with Claude Code