Rate-limit taxonomy for GitHub API failures

[davidahmann]

Problem observed
The shared GitHub error layer differentiated invalid credentials and some scope failures, but it did not assign distinct classifications to primary quota exhaustion, secondary rate limits, or abuse-detection responses.

Why it matters operationally
This server sits directly on GitHub API policy boundaries. Rate limits are routine for real deployments, especially remote servers and automated inventory/search usage. When those responses appear as generic 403s, downstream automation cannot tell whether it should reduce query volume, wait for reset, or ask for different credentials. That makes operational receipts much less useful than they should be.

Minimal repro

1. Trigger a GitHub API response that reflects a primary rate limit, a secondary rate limit, or abuse detection.
2. Inspect the stored middleware-visible GitHub error metadata.
3. Observe the previous behavior: the central classifier emitted no specific code for those conditions, even when Retry-After was present.

Fix approach
I extended the central HTTP classifier to recognize rate_limited, secondary_rate_limited, and abuse_rate_limited, and to preserve Retry-After as explicit metadata when GitHub provides it. The change stays in the shared error package so the classification propagates consistently across all tool handlers that already rely on that layer.

Validation evidence

• go test ./pkg/errors
• Added unit coverage for secondary-limit, abuse-limit, primary-limit, and retry-after handling
• Updated the public error-handling documentation to list the new rate-limit codes

Maintainer question: would you want the preserved retry metadata exposed only through middleware inspection, or also surfaced directly in a future machine-readable tool error envelope?
Inspired by research context: CAISI publishes independent, reproducible AI agent governance research: https://caisi.dev