refactor(mcp): make canonical/LLM-facing tool name boundary type-enforced

[Aaronontheweb]

Summary

PR #1134 introduced an Anthropic-safe sanitized alias (server__tool) for MCP tool names but stored both forms as bare strings. PR #1147 fixed one acute symptom (approval grant lookup mismatch) but the broader drift remained — audit log emitted sanitized while approval grants stored canonical, the LLM saw canonical in search_tools output but emitted sanitized in tool_use, and several touched-but-correct sites were one refactor away from re-introducing the same class of bug.

This PR moves the canonical-vs-LLM-facing distinction to a type boundary so future drift becomes a compile error.

Three commits, each independently reviewable:

1. Foundation — LlmFacingToolName value object with FromCanonical factory that sanitizes / → __ and asserts the result satisfies Anthropic's ^[a-zA-Z0-9_-]{1,128}$. INetclawTool.LlmFacingName is now a required member; the source generator emits it for first-party tools (failing at type-init for any future tool whose name can't be made LLM-safe); McpToolAdapter replaces its SanitizedName string with the value-typed form. No behavior change — every call site that previously read SanitizedName now reads LlmFacingName.Value and gets the same string.

2. LLM-actor boundary seam — LlmSessionActor.HandleToolCallResponse rewrites incoming FunctionCallContent.Name from the sanitized alias to canonical before any internal consumer reads it. Persisted history carries canonical. ChatMessageConverter.ToAiMessages gains an optional toolNameResolver Func threaded from ContextAssemblyInput, which the session actor wires to _toolRegistry.ToLlmFacingName so the outbound LLM request gets the sanitized form back on the wire. Internal re-drive paths (RedriveToolBatchForApproval) leave the resolver null and round-trip canonical, exactly what their two-form registry lookup wants. Result: audit log, ToolCallOutput event stream, duplicate-tool nudge, and memory ledger all now record notion/notion-create-pages instead of notion__notion-create-pages — matching the Slack approval prompt and the persisted approval grant.

3. LLM-facing surface alignment — search_tools, load_tool, and discovered-tool activation logging all surfaced canonical names while the LLM emits sanitized in tool_use. The model saw the same tool under two distinct strings within a single turn. Now those surfaces emit LlmFacingName consistently; TryActivateDiscoveredTool still uses the registry's two-form lookup (no behavior change for older LLM strings) but caches and logs under the canonical name. Operator-facing surfaces from commit (2) and LLM-facing surfaces from this commit are now consistent within their respective audiences.

Test plan

• dotnet build — clean
• dotnet test src/Netclaw.Actors.Tests — 1956 tests pass
• New unit tests:
  • LlmFacingToolNameTests — sanitization, idempotence, regex enforcement, length cap
  • ToolRegistryTests — ToCanonicalName / ToLlmFacingName round-trip for MCP and first-party tools
  • ChatMessageConverterTests — resolver applied / not applied paths
  • McpToolAdapterTests — LlmFacingName replaces the prior SanitizedName getter
• dotnet slopwatch analyze — no new violations
• ./scripts/Add-FileHeaders.ps1 -Verify — all files have headers

Out of scope (potential further follow-up)

• Configuration / CLI surfaces (ToolApprovalConfig.TryGetExplicitMode, netclaw approvals revoke --tool, ToolAudienceProfilesDoctorCheck) still match on exact strings. An operator who writes the sanitized alias into a config key would silently get no effect. Worth either teaching those surfaces to normalize via the registry, or adding a doctor check / schema-fix resolver to catch the misuse. Independent of this PR.