---
name: token-mizer-route
description: Opt-in context-first routing across verified built-in models and independently eligible Foundry workers, including task-scoped token-mizer-integrate calls.
---

# Context-first routing

Apply only when Token Mizer is selected or explicitly activated through `token-mizer-integrate`. Discover the actual host-listed skill names before loading dependencies. The inherited coordinator cannot switch its own model or context window. If its context is insufficient, use an authorized new session with a compact lossless handoff, or block.

Estimate complete context (instructions, tools, history, evidence, output, headroom). Require host-confirmed sufficient capacity, exact accepted runtime ID, provider identity, actor authorization, permitted role, and current availability before assignment and again immediately before each host invocation. Unknown capacity is not a fit. Foundry runtime IDs must be connection-qualified and verified against host catalog or the user-confirmed local provider mapping; GitHub/built-in models require host evidence. A bare built-in ID is GitHub-billed absent authoritative contrary evidence. Never fabricate provider mappings, capacity, effort settings, billing, or a speed/quality advantage.

| Route | Eligibility and use |
|---|---|
| Built-in GPT-6 Sol (`sol6`, `gpt-6-sol`) | Ordinary substantial eligible work; preferred when local built-in opt-in is true |
| Built-in GPT-6 Astra (`astra`, `gpt-6-astra`) | Hard diagnosis or evidenced failed first fix; never spawn an alternative worker for the same unresolved fix |
| Built-in Grok 4.7 (`grok`, `grok-4.7`) | Explicitly urgent user request only; preference does not prove measured latency |
| Foundry DeepSeek-V4.1-Flash (`deepseek`) | User-approved, deployment-repair-only pilot: one bounded implementation attempt with original reproduction, full applicable CI, and live verification; block unknown capacity/runtime/authorization; failed repair escalates to Astra, not another DeepSeek attempt |
| Foundry GPT-5.6 Luna (`luna`) | Independently eligible, context-fitting economy route, not an automatic substitute for a blocked large task |

Gemini 3.8 Flash and GPT-5.6 Sol are **retired for fresh allocation/admission**, including explicit requests. Historical v4 assignments remain readable but cannot be re-admitted; create a new v5 assignment after separately rechecking the original task identity and acceptance boundary. Do not silently remap a previous route. Terra has no route.

Read `token-mizer-budget` before built-in use or any other paid route. The public policy example defaults `github_models.builtin_uncapped_opt_in` to false. Only the current user's explicit *private local* opt-in authorizes uncapped automatic routing of the exact three allowed built-in models. It does not authorize arbitrary built-ins, bypass actor permissions, or assert a hard dollar ceiling. All other paid routes retain the dated, metered spending gate. DeepSeek is Foundry and has no implied GitHub billing approval.

Operational allocator requests supply `paid_policy: {"builtin_uncapped_opt_in": true, "source": "local"}` only after reading the user's genuine private opt-in; absence/false blocks built-ins. The allocator itself rereads `$COPILOT_HOME/token-mizer/policy.json` (or `~/.copilot/token-mizer/policy.json`) on selection, resume and admission of a built-in assignment. It requires `github_models` to contain exactly a true `builtin_uncapped_opt_in` and the three-model `allowed_builtin_models` list; missing, duplicate, contradictory or changed fields fail closed. The dated `github_budget` is a separate gate and its zero/expired values are not a fake cap on this explicit built-in exception. For fresh built-in candidates, only the exact bare allowlisted model ID is accepted. A qualified GitHub runtime requires independent host-issued provider proof unavailable to this local helper, so it is blocked rather than trusting a caller-supplied prefix. Supply host `route_evidence` bound to family/provider/runtime, capacity and actor authorization; the helper cannot independently verify those host annotations, so the dispatching caller still must confirm live host identity, role, permission, context and accepted runtime. Urgent Grok additionally needs `intent_evidence: {"kind": "urgent", "source": "user", "evidence_reference": "<actual user request>"}`. Astra uses kind `hard-diagnosis` or `failed-first-fix`, source `user` or `host`, and an actual evidence reference. DeepSeek requires `path: "deepseek-pilot"`, `task_class: "deployment-repair"`, a builder role, and user-sourced intent with kind `deployment-repair-pilot`, nonempty evidence reference, `bounded_attempts: 1`, and `reproduction`, `ci`, `live_verification` all true. The helper validates annotations, not their truth: verify them at dispatch and enforce the one-attempt bound in the caller. Select then freshly admit; use only `handoff.selected_runtime_id`, never cached admission or `selected_model`. A handoff is not an execution lease, spending reservation, or proof that the host accepted the model.

DeepSeek candidates additionally require `capacity_evidence` with `source: "host"`, `verified: true`, the exact qualified `runtime_id`, and an observed integer `context_capacity` matching the candidate. The allocator durably permits only one pilot assignment for a task ID and one fresh pilot admission; a new ID cannot reset that attempt within the same state. The caller must still verify that the host evidence is genuine.

For pilot `intent_evidence.source: "user"`, a prior explicit user approval may authorize **standing** use on future bounded deployment-repair tasks when the user-approved private local policy has `foundry_pilots.deepseek_deployment_repair_enabled` exactly `true`. `intent_evidence.evidence_reference` points to that original approval (a safe private reference, not policy contents); it may be reused across *different* task IDs. Missing/false standing flag requires a new explicit user approval for this task before filling the intent, or blocks – never interpret `provider.repair_pilot_model` alone as approval. The caller reads the private flag and verifies approval provenance at each dispatch; this instruction-only allocator validates supplied `source` and reference annotations, not policy contents. Standing approval does not authorize a second attempt on one task, other task classes, unknown context/capacity, a different provider, or a caller lacking actor permission. The original task ID and acceptance boundary remain unchanged.

Do not rotate routes just to balance counts. A large-context task cannot silently use Foundry Luna. Keep tasks requiring five or fewer calls in a suitable inherited coordinator. Delegate only self-contained substantial work; preserve specialist agents, approvals, original task identity, and acceptance target. Reproduce reported bugs through the closest feasible user flow. After a failed first fix, conduct a bounded Astra rubber-duck diagnosis; in the opted-in bounded-RUG workflow permit at most one diagnosed repair, then block if verification fails again. Run the applicable repository-wide CI-equivalent checks and affected-package tests; edited-file checks alone are insufficient.

Classify authentication/environment, provider configuration, capacity, and task failures separately. Credential errors stop inference with recovery guidance, never automatic login or provider substitution. Only explicit 429/TPM/quota/capacity evidence enables contention retries. On a constrained Foundry connection use one active worker, reuse its checkpoint, respect `Retry-After`, and allow at most three retries/five minutes cumulative waiting. Do not launch duplicate sessions or silently treat a shared connection switch as independent capacity. Five minutes of observed Foundry throttling makes a distinct paid capacity route *eligible for evaluation*, never approved. Report missing proof and stop rather than polling or promising an unscheduled retry.

Keep private policy/provider IDs out of shared diagnostics. Record policy eligibility, approval, attempted and accepted runtime, actual observed use, verified outcome, and unknown measurements separately. Historical reports can label retired routes without suggesting fresh eligibility.