feat(registry): version-gated tool registration via InstanceCapabilities layer

[polaz]

👍 React to this issue if you need this feature — helps us prioritise.

Problem

Several GitLab features are version-dependent (active filter ≥18.5, group restore ≥18.0, future ones in 19.x). Today our registry registers all tools unconditionally — call-time the request fails on older instances with an opaque API error. We should:

1. Detect instance version at bootstrap (already done — ConnectionManager.isFeatureAvailable)
2. Expose a clean InstanceCapabilities map (version, tier, admin, scopes)
3. Either skip tool registration OR mark tool with min-version metadata that registry filters honour

Investigation done (current state)

Verified:

• ✅ services/GitLabVersionDetector.ts:284 has isFeatureAvailable framework — used in 15 places (grep -rn 'getTier\|isFeatureAvailable' src/)
• ✅ ConnectionManager.getInstanceInfo() returns version + tier — caller can decide
• ⚠️ But version-gating is scattered: each handler does its own isFeatureAvailable call. No single InstanceCapabilities blob the registry uses to filter the entire tool list
• ❌ No tool is filtered OUT of the catalog on older instances — they just fail at call time

Re-verify before coding:

grep -rn 'isFeatureAvailable' src/ | head -20
grep -rn 'InstanceCapabilities\|getInstanceCapabilities' src/

Acceptance criteria

• New services/InstanceCapabilities.ts aggregating: version (semver), tier (free/premium/ultimate), isAdmin, adminModeActive (feat(context): probe admin_mode elevation and expose in whoami #434), token scopes
• Cached at session-startup (single bootstrap call instead of N isFeatureAvailable lookups)
• registry-manager.ts consults it during getAllToolDefinitions() to filter out tools whose minVersion/requiresAdmin/requiresTier aren't met
• Tools declare their requirements in schema (e.g. {minGitLabVersion: '18.5'})
• Honest tools/list_changed notification when capabilities are re-detected (e.g. after switch_profile)
• Used by all version-gated features: feat(projects): browse_projects action 'list_deleted' for soft-deleted projects #431, feat(projects): manage_project action 'restore' for soft-deleted projects #432, feat(namespaces): manage_namespace action 'restore' for soft-deleted groups (GitLab 18.0+) #433, feat(projects): support 'active' filter on browse_projects (GitLab 18.5+) #435 — must land before those, or at least in parallel

Estimate

1d

Context

Found during GitLab 18→19 API landscape analysis. Foundational work that prevents repeated version-gating boilerplate across handlers.

[coderabbitai]

🔗 Related PRs

#396 - refactor: thread instanceUrl and key caches by URL [merged]
#399 - refactor(registry): fail-close on unexpected errors in loadInstanceContext/getFilterStats [merged]
#406 - refactor(session): per-session instance URL tracking for session-aware ListTools [merged]

---

📝 Issue Planner

_{Check the box below or use the @coderabbitai plan command to generate an implementation plan and prompts that you can use with your favorite coding assistant.}

• Create Plan

---

🧪 Issue enrichment is currently in open beta.

You can configure auto-planning by selecting labels in the issue_enrichment configuration.

To disable automatic issue enrichment, add the following to your .coderabbit.yaml:

issue_enrichment:
  auto_enrich:
    enabled: false

💬 Have feedback or questions? Drop into our discord!