feat(sdk): expose context-window / context-tier selection (default vs long-context/1M) in config, charter, and spawn pipeline #1446

Summary

Squad can select a model and a reasoning effort, but has no way to select the context window / context tier (e.g. Default vs Long context / 1M). The underlying GitHub Copilot runtime fully supports this today, so Squad is leaving a first-class capability unexposed.

This mirrors the reasoning-effort work in #773 (config support) and #1148 (feat(sdk): thread reasoningEffort through agent spawning pipeline) — we want the same end-to-end plumbing for context tier.

Evidence the runtime supports it

The Copilot CLI /model flow for Claude Opus 4.8 exposes three selectors:

1. Model — Claude Opus 4.8, etc.
2. Effort Level — Low / Medium / High / Extra High / Max
3. Context Window — Default = 264K tokens or Long context = 1M tokens (with distinct credit cost: input 500 / cache-read 50 / cache-write 625 / output 2,500 per 1M).

The spawn tools Squad builds on (create_session kickoff.context_tier, task context_tier) accept "default" | "long_context". So the capability exists at the runtime layer — Squad just needs to surface and thread it.

Current gap

A repo-wide search confirms zero references to contextTier / context_tier / contextWindow / long_context anywhere in packages/. Note: SquadSessionConfig.infiniteSessions (adapter/types.ts) is auto-compaction, not context-window sizing — it does not cover this.

By contrast, reasoningEffort is plumbed through every layer:

• packages/squad-sdk/src/config/schema.ts — ModelConfig.defaultReasoningEffort, agentReasoningEffortOverrides
• packages/squad-sdk/src/adapter/types.ts — SquadSessionConfig.reasoningEffort, SquadReasoningEffort type, model supportedReasoningEfforts / defaultReasoningEffort
• packages/squad-sdk/src/config/models.ts — VALID_REASONING_EFFORTS, resolution + clamping helpers
• packages/squad-sdk/src/agents/charter-compiler.ts — ## Model -> **Reasoning Effort:**
• packages/squad-sdk/src/coordinator/spawn-backend.ts + fan-out.ts — threading into the spawn
• packages/squad-cli/src/cli/commands/config.ts — CLI surface

Proposed scope (mirror #1148 for context tier)

Add a context tier concept with the same layering as reasoning effort:

• Type — SquadContextTier = "default" | "long_context" in adapter/types.ts (plus auto sentinel semantics if we follow the effort pattern).
• Session config — SquadSessionConfig.contextTier?: SquadContextTier.
• Model catalog — per-model supportedContextTiers / defaultContextTier (and window sizes, e.g. Opus 4.8 -> 264K default / 1M long) so we can validate/clamp requests against what a model actually supports.
• Config schema — ModelConfig.defaultContextTier + agentContextTierOverrides in schema.ts.
• Resolution/clamping helpers — in models.ts, mirroring the effort resolvers (clamp an unsupported tier down gracefully; treat unknown as default).
• Charter — ## Model -> **Context Tier:** compiled by charter-compiler.ts.
• Spawn pipeline — thread contextTier through spawn-backend.ts / fan-out.ts and map to the runtime spawn param (context_tier / kickoff.context_tier).
• CLI — squad config context-tier [<tier>] [--agent <name>] [--clear] (parallel to squad config model).
• Coordinator guidance — document per-agent context-tier selection in squad.agent.md (analogous to the reasoning-effort section) so the coordinator resolves and passes it on spawn.
• Tests + changeset.

Secondary observation (optional, can split out)

SquadReasoningEffort (adapter/types.ts) = "low" | "medium" | "high" | "xhigh" and VALID_REASONING_EFFORTS (models.ts) omits max, while Copilot's picker offers Max. EFFORT_RANK already maps max->xhigh (i.e. "Max" is currently clamped to Extra High). If we want true parity with the Copilot picker we may want to admit max as a distinct level — but that's a separate decision; flagging here for visibility.

Acceptance criteria

• A user can set a default context tier and per-agent overrides via squad config and/or .squad/config.json.
• A charter can declare a context tier; the coordinator resolves it and passes it to the spawn.
• Requesting long_context on a model that supports it (e.g. Opus 4.8) results in the long-context/1M window being requested at spawn time; unsupported requests clamp gracefully.
• npm run build passes; new behavior is covered by tests; a .changeset is included.

References

• Precedent: config.json support for defaultEffort and agentEffortOverrides #773 (config support for effort), feat(sdk): thread reasoningEffort through agent spawning pipeline #1148 (thread reasoningEffort through spawn pipeline)
• Related umbrella: feat: add cost policy support and refresh model catalog for GitHub AI Credits billing #1080 (model catalog refresh)