fix(upgrade): scope the claude-code-guide freshness spawn to survive its context window

[elhoim]

What happened

The Upgrade skill's Step 2a freshness check spawns claude-code-guide and asks it to cover the whole Claude Code API surface in one go — hook event types, settings.json fields, slash commands, SKILL.md frontmatter, subagent frontmatter, MCP, Agent SDK and Claude API.

On a real run it died with Prompt is too long about ten seconds after spawn, returning nothing. Five sibling Explore agents dispatched in the same batch all completed normally.

Why

claude-code-guide runs on a small-context model — the spawn record shows "model":"haiku", which is a 200k window, and no model was passed at the call site.

The prompt itself is not the problem. Ruled out by measurement:

• The prompt was ~200 words.
• The parent conversation was 76,754 tokens at spawn — comfortably under 200k, so inherited context does not explain it either.
• Control: a deliberately trivial prompt (Reply with exactly the word: OK) to the same agent type, in the same session, spawned when the parent conversation was larger, completed normally and returned OK.

Same agent, same model pin, same inherited context, opposite outcome — the only variable is how much the prompt makes it fetch. A request that broad makes the agent fan out a batch of documentation lookups in its first turn, and their combined results exceed the window on the very next request. The ~10s timing matches a first tool-call turn returning rather than any slow accumulation.

The fix

• Cap the ask at three areas per spawn, and tell it to look things up rather than pull whole pages.
• Split the surface across parallel spawns, so losing one costs a slice instead of the entire freshness check.
• Record the fallback: the claude-code/CHANGELOG.md raw URL is already in sources.json, and reading the version range directly answers most freshness questions without an agent at all.
• Add the lesson to the skill's ## Gotchas, including the diagnostic tell — the sibling agents succeed while this one dies, which points at the model rather than the batch.