From 8f6465a5a16f684d61c569aede971b3c5f3aa3c9 Mon Sep 17 00:00:00 2001 From: elhoim Date: Sun, 26 Jul 2026 17:45:22 +0000 Subject: [PATCH] fix(upgrade): scope the claude-code-guide freshness spawn to survive its context window MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The Step 2a freshness check asked one claude-code-guide spawn to cover the whole API surface at once — hook events, settings fields, slash commands, SKILL.md frontmatter, subagent frontmatter, MCP, Agent SDK and Claude API. That agent runs on a small-context model (haiku, 200k). A request that broad makes it fan out a batch of documentation fetches whose combined results exceed the window on the very next request, so it dies with 'Prompt is too long' roughly ten seconds in, having returned nothing. Observed 2026-07-26: five sibling Explore agents in the same batch all completed; only the claude-code-guide spawn failed. The prompt text is not the problem — a trivial prompt to the same agent type runs fine. The tool-result volume is. Cap the ask at three areas per spawn, tell it to look things up rather than pull whole pages, and split the surface across parallel spawns so losing one costs a slice instead of the whole check. Records the CHANGELOG raw URL already in sources.json as the fallback, and adds the lesson to the skill's Gotchas. --- LifeOS/install/skills/Upgrade/SKILL.md | 1 + LifeOS/install/skills/Upgrade/Workflows/Upgrade.md | 8 +++++++- 2 files changed, 8 insertions(+), 1 deletion(-) diff --git a/LifeOS/install/skills/Upgrade/SKILL.md b/LifeOS/install/skills/Upgrade/SKILL.md index c478b6d0f4..ffbd69a5f6 100644 --- a/LifeOS/install/skills/Upgrade/SKILL.md +++ b/LifeOS/install/skills/Upgrade/SKILL.md @@ -151,6 +151,7 @@ These output patterns are **FAILURES**: - **Check ALL sources in parallel** — Anthropic blog, changelog, YouTube channels, GitHub releases. Don't check sequentially. - **Upgrades must not break existing skills or workflows.** Verify backward compatibility before applying. - **Full upgrade check can take 5-7 minutes.** Use `run_in_background: true` for the outer agent. +- **Keep the `claude-code-guide` spawn to three areas or fewer.** That agent runs on a small-context model (haiku, 200k). Asking one spawn to cover the whole API surface makes it fan out a batch of doc fetches whose results exceed the window on the next request, and it dies with `Prompt is too long` about ten seconds in — returning nothing, while the sibling `Explore` agents in the same batch all succeed. The prompt length is not the problem; the tool-result volume is. Split the surface across parallel spawns and tell it to look things up rather than pull whole pages. If one dies anyway, fall back to the `claude-code/CHANGELOG.md` raw URL in `sources.json`. *(2026-07-26.)* ## Execution Log diff --git a/LifeOS/install/skills/Upgrade/Workflows/Upgrade.md b/LifeOS/install/skills/Upgrade/Workflows/Upgrade.md index 4d351c4f2e..e25c19c43b 100644 --- a/LifeOS/install/skills/Upgrade/Workflows/Upgrade.md +++ b/LifeOS/install/skills/Upgrade/Workflows/Upgrade.md @@ -114,7 +114,13 @@ Return within 90s; reduce per_page to 3 if slow. Spawn `Agent(subagent_type="claude-code-guide", run_in_background: true)`: -Verify LifeOS's Claude Code references against the latest API surface. Check: hook event types, slash commands, agent/subagent types, settings.json fields, MCP integration, Agent SDK, Claude API. For each area, return current features, recent additions, deprecated items, and LifeOS staleness risk (LOW/MEDIUM/HIGH). Focus on changes affecting hooks, skills, or Algorithm. Return within 90s. +Verify LifeOS's Claude Code references against the latest API surface. For each area, return current features, recent additions, deprecated items, and LifeOS staleness risk (LOW/MEDIUM/HIGH). Focus on changes affecting hooks, skills, or Algorithm. Return within 90s. + +**Ask for at most three areas per spawn, and say to look things up rather than pull whole pages.** `claude-code-guide` runs on a small-context model (haiku, 200k), so it is the tool-result volume that kills it, not the prompt. A single spawn covering the full surface — hook events, settings fields, slash commands, SKILL.md frontmatter, subagent frontmatter, MCP, Agent SDK, Claude API — makes it fan out a batch of doc fetches whose combined results exceed the window on the very next request, and the agent dies with `Prompt is too long` about ten seconds in, before returning anything. Observed 2026-07-26. + +Split the surface across parallel spawns instead — e.g. one for hooks + settings + subagent frontmatter, one for skills + slash commands + MCP, one for Agent SDK + Claude API. Losing one spawn then costs one slice rather than the whole freshness check. + +If a spawn does die this way, the changelog is the fallback: `WebFetch` the `claude-code/CHANGELOG.md` raw URL already listed in `sources.json` and read the version range directly. Output feeds Step 5 (Filter and Score) as source type `Claude Code Guide` and is cross-referenced against current LifeOS files for staleness.