Log code_search/search rate-limit buckets and surface GitHub MCP search_code 429 hints #68666

We run docs review and issue scoping agents on gh-aw (v0.89.17) in elastic/docs-content, and search_code from the GitHub MCP server keeps coming back with 429s. We can work around it, but we can't see it coming, so I'd like to ask for better visibility and a documented path.

In this run, all three search_code calls failed. The first one returned:

failed to search code with query '…': GET https://api.github.com/search/code?…: 429 try again in 216.007769ms

The agent retried about 19 seconds later and again at about 45 seconds, and both calls failed too. So the bucket was already empty when the run started. The agent's own calls did not use it up. The review then had to report that it could not verify its main claim.

This isn't specific to us. gh-aw's own workflows hit the same wall: #67163 (daily compat audit, 429 try again in 719.5s, then 429 try again in 10.2s on the next query) and #64493 (recurring search_code 429s in the MCP structural analysis). Both closed without a fix, one by an expiry job. The retry hints vary from 216 ms to 719 s, so an agent can't tell whether waiting is worth it.

What I can't tell from the logs is why the bucket was empty. The core bucket is the only one gh-aw logs today. My guess is that concurrent runs share one GITHUB_TOKEN identity, and so share the code-search limit, but I can't confirm that without the numbers. GET /rate_limit already returns separate code_search and search resources.

Three small things would help:

1. Log the code_search and search buckets (limit, remaining, reset) next to core in the rate-limit step, at the start and end of the agent job.
2. Surface MCP 429 responses in the agent log summary, with the retry hint, so a failed run points at the cause quickly.
3. Document in the GitHub tools reference that search_code has its own, much smaller budget than the other tools, and that checkout: with sparse-checkout is the recommended way to look at code in another repository (which works in v0.89.17).

On our side, we're moving code lookups to a sparse checkout: of the target repository so the agent can use grep, and we're keeping the search_code budget low. We'll report back if the shared-identity guess turns out to be right.