opencode-model-router 1.0.6 → 1.1.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-model-router",
-  "version": "1.0.6",
+  "version": "1.1.0",
   "description": "OpenCode plugin that routes tasks to tiered subagents (fast/medium/heavy) based on complexity",
   "type": "module",
   "main": "./src/index.ts",
@@ -35,5 +35,9 @@
   ],
   "peerDependencies": {
     "@opencode-ai/plugin": ">=1.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "typescript": "^5.9.3"
   }
 }

package/src/index.ts

@@ -22,6 +22,7 @@ interface TierConfig {
   variant?: string;
   thinking?: ThinkingConfig;
   reasoning?: ReasoningConfig;
+  costRatio?: number;
   color?: string;
   description: string;
   steps?: number;
@@ -31,21 +32,45 @@ interface TierConfig {
 
 type Preset = Record<string, TierConfig>;
 
+interface FallbackConfig {
+  global?: Record<string, string[]>;
+  presets?: Record<string, Record<string, string[]>>;
+}
+
+interface ModeConfig {
+  defaultTier: string;
+  description: string;
+  overrideRules?: string[];
+}
+
 interface RouterConfig {
   activePreset: string;
+  activeMode?: string;
   presets: Record<string, Preset>;
   rules: string[];
   defaultTier: string;
+  fallback?: FallbackConfig;
+  taskPatterns?: Record<string, string[]>;
+  modes?: Record<string, ModeConfig>;
 }
 
 interface RouterState {
   activePreset?: string;
+  activeMode?: string;
 }
 
 // ---------------------------------------------------------------------------
-// Config loader
+// Config loader with caching
 // ---------------------------------------------------------------------------
 
+let _cachedConfig: RouterConfig | null = null;
+let _configDirty = true;
+
+/** Mark config cache as stale so it is re-read on next access. */
+function invalidateConfigCache(): void {
+  _configDirty = true;
+}
+
 function getPluginRoot(): string {
   const __dirname = dirname(fileURLToPath(import.meta.url));
   return join(__dirname, ".."); // src/ -> plugin root
@@ -72,8 +97,93 @@ function resolvePresetName(cfg: RouterConfig, requestedPreset: string): string |
   return Object.keys(cfg.presets).find((name) => name.toLowerCase() === normalized);
 }
 
+function validateConfig(raw: unknown): RouterConfig {
+  if (typeof raw !== "object" || raw === null) {
+    throw new Error("tiers.json: expected a JSON object at root");
+  }
+
+  const obj = raw as Record<string, unknown>;
+
+  if (typeof obj.activePreset !== "string" || !obj.activePreset) {
+    throw new Error("tiers.json: 'activePreset' must be a non-empty string");
+  }
+  if (typeof obj.presets !== "object" || obj.presets === null || Array.isArray(obj.presets)) {
+    throw new Error("tiers.json: 'presets' must be a non-null object");
+  }
+
+  const presets = obj.presets as Record<string, unknown>;
+  for (const [presetName, preset] of Object.entries(presets)) {
+    if (typeof preset !== "object" || preset === null || Array.isArray(preset)) {
+      throw new Error(`tiers.json: preset '${presetName}' must be an object`);
+    }
+    const tiers = preset as Record<string, unknown>;
+    for (const [tierName, tier] of Object.entries(tiers)) {
+      if (typeof tier !== "object" || tier === null) {
+        throw new Error(`tiers.json: tier '${presetName}.${tierName}' must be an object`);
+      }
+      const t = tier as Record<string, unknown>;
+      if (typeof t.model !== "string" || !t.model) {
+        throw new Error(`tiers.json: '${presetName}.${tierName}.model' must be a non-empty string`);
+      }
+      if (typeof t.description !== "string") {
+        throw new Error(`tiers.json: '${presetName}.${tierName}.description' must be a string`);
+      }
+      if (!Array.isArray(t.whenToUse)) {
+        throw new Error(`tiers.json: '${presetName}.${tierName}.whenToUse' must be an array`);
+      }
+    }
+  }
+
+  if (!Array.isArray(obj.rules)) {
+    throw new Error("tiers.json: 'rules' must be an array of strings");
+  }
+  if (typeof obj.defaultTier !== "string") {
+    throw new Error("tiers.json: 'defaultTier' must be a string");
+  }
+
+  // Validate modes if present
+  if (obj.modes !== undefined) {
+    if (typeof obj.modes !== "object" || obj.modes === null || Array.isArray(obj.modes)) {
+      throw new Error("tiers.json: 'modes' must be an object");
+    }
+    const modes = obj.modes as Record<string, unknown>;
+    for (const [modeName, mode] of Object.entries(modes)) {
+      if (typeof mode !== "object" || mode === null) {
+        throw new Error(`tiers.json: mode '${modeName}' must be an object`);
+      }
+      const m = mode as Record<string, unknown>;
+      if (typeof m.defaultTier !== "string") {
+        throw new Error(`tiers.json: mode '${modeName}.defaultTier' must be a string`);
+      }
+      if (typeof m.description !== "string") {
+        throw new Error(`tiers.json: mode '${modeName}.description' must be a string`);
+      }
+    }
+  }
+
+  // Validate taskPatterns if present
+  if (obj.taskPatterns !== undefined) {
+    if (typeof obj.taskPatterns !== "object" || obj.taskPatterns === null || Array.isArray(obj.taskPatterns)) {
+      throw new Error("tiers.json: 'taskPatterns' must be an object");
+    }
+    const tp = obj.taskPatterns as Record<string, unknown>;
+    for (const [tierName, patterns] of Object.entries(tp)) {
+      if (!Array.isArray(patterns)) {
+        throw new Error(`tiers.json: taskPatterns.'${tierName}' must be an array of strings`);
+      }
+    }
+  }
+
+  return raw as RouterConfig;
+}
+
 function loadConfig(): RouterConfig {
-  const cfg = JSON.parse(readFileSync(configPath(), "utf-8")) as RouterConfig;
+  if (_cachedConfig && !_configDirty) {
+    return _cachedConfig;
+  }
+
+  const raw = JSON.parse(readFileSync(configPath(), "utf-8"));
+  const cfg = validateConfig(raw);
 
   try {
     if (existsSync(statePath())) {
@@ -84,14 +194,43 @@ function loadConfig(): RouterConfig {
           cfg.activePreset = resolved;
         }
       }
+      if (state.activeMode && cfg.modes?.[state.activeMode]) {
+        cfg.activeMode = state.activeMode;
+      }
     }
   } catch {
-    // Ignore state read errors and keep tiers.json active preset
+    // Ignore state read errors and keep tiers.json defaults
   }
 
+  _cachedConfig = cfg;
+  _configDirty = false;
   return cfg;
 }
 
+// ---------------------------------------------------------------------------
+// State persistence helpers
+// ---------------------------------------------------------------------------
+
+/** Read current persisted state (or empty object on failure). */
+function readState(): RouterState {
+  try {
+    if (existsSync(statePath())) {
+      return JSON.parse(readFileSync(statePath(), "utf-8")) as RouterState;
+    }
+  } catch {
+    // ignore
+  }
+  return {};
+}
+
+/** Write state to disk (merges with existing keys). */
+function writeState(patch: Partial<RouterState>): void {
+  const state = { ...readState(), ...patch };
+  const p = statePath();
+  mkdirSync(dirname(p), { recursive: true });
+  writeFileSync(p, JSON.stringify(state, null, 2) + "\n", "utf-8");
+}
+
 function saveActivePreset(presetName: string): void {
   const cfg = loadConfig();
   const resolved = resolvePresetName(cfg, presetName);
@@ -101,14 +240,22 @@ function saveActivePreset(presetName: string): void {
 
   cfg.activePreset = resolved;
 
-  // Persist user-selected preset outside package cache so it survives npm updates
-  const presetState: RouterState = { activePreset: resolved };
-  const p = statePath();
-  mkdirSync(dirname(p), { recursive: true });
-  writeFileSync(p, JSON.stringify(presetState, null, 2) + "\n", "utf-8");
+  // Persist user-selected preset to state file only — never mutate tiers.json
+  writeState({ activePreset: resolved });
+
+  // Invalidate cache so next read picks up the new active preset
+  invalidateConfigCache();
+}
+
+function saveActiveMode(modeName: string): void {
+  const cfg = loadConfig();
+  if (!cfg.modes?.[modeName]) {
+    return;
+  }
 
-  // Keep local tiers.json in sync as best effort
-  writeFileSync(configPath(), JSON.stringify(cfg, null, 2) + "\n", "utf-8");
+  cfg.activeMode = modeName;
+  writeState({ activeMode: modeName });
+  invalidateConfigCache();
 }
 
 function getActiveTiers(cfg: RouterConfig): Preset {
@@ -142,6 +289,73 @@ function buildAgentOptions(tier: TierConfig): Record<string, unknown> {
   return Object.keys(opts).length > 0 ? opts : {};
 }
 
+// ---------------------------------------------------------------------------
+// Mode helpers
+// ---------------------------------------------------------------------------
+
+function getActiveMode(cfg: RouterConfig): ModeConfig | undefined {
+  if (!cfg.modes || !cfg.activeMode) return undefined;
+  return cfg.modes[cfg.activeMode];
+}
+
+// ---------------------------------------------------------------------------
+// Fallback instructions builder
+// ---------------------------------------------------------------------------
+
+function buildFallbackInstructions(cfg: RouterConfig): string {
+  const fb = cfg.fallback;
+  if (!fb) return "";
+
+  const presetMap = fb.presets?.[cfg.activePreset];
+  const map = presetMap && Object.keys(presetMap).length > 0 ? presetMap : fb.global;
+  if (!map) return "";
+
+  const providerLines = Object.entries(map).flatMap(([provider, presetOrder]) => {
+    if (!Array.isArray(presetOrder)) return [];
+    const validOrder = presetOrder.filter(
+      (preset) => preset !== cfg.activePreset && Boolean(cfg.presets[preset]),
+    );
+    return validOrder.length > 0 ? [`- ${provider}: ${validOrder.join(" -> ")}`] : [];
+  });
+
+  if (providerLines.length === 0) return "";
+
+  return [
+    "Fallback on delegated task errors:",
+    "1. If Task(...) returns provider/model/rate-limit/timeout/auth errors, retry once with a different tier suited to the same task.",
+    "2. If retry also fails, stop delegating that task and complete it directly in the primary agent.",
+    "3. Use the failing model prefix and this preset fallback order for next-run recovery (`/preset <name>` + restart):",
+    ...providerLines,
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Cost & taxonomy builders
+// ---------------------------------------------------------------------------
+
+function buildTaskTaxonomy(cfg: RouterConfig): string {
+  if (!cfg.taskPatterns || Object.keys(cfg.taskPatterns).length === 0) return "";
+
+  const lines = ["Coding task routing guide:"];
+  for (const [tier, patterns] of Object.entries(cfg.taskPatterns)) {
+    if (Array.isArray(patterns) && patterns.length > 0) {
+      lines.push(`- @${tier}: ${patterns.join(", ")}`);
+    }
+  }
+  return lines.join("\n");
+}
+
+function buildCostAwareness(cfg: RouterConfig): string {
+  const tiers = getActiveTiers(cfg);
+  const costs = Object.entries(tiers)
+    .filter(([_, t]) => t.costRatio != null)
+    .map(([name, t]) => `@${name}=${t.costRatio}x`)
+    .join(", ");
+
+  if (!costs) return "";
+  return `Cost ratios: ${costs}. Always use the cheapest tier that can reliably handle the task.`;
+}
+
 // ---------------------------------------------------------------------------
 // System prompt builder
 // ---------------------------------------------------------------------------
@@ -157,21 +371,44 @@ function buildDelegationProtocol(cfg: RouterConfig): string {
     })
     .join(" | ");
 
+  // Build per-tier whenToUse descriptions so the agent knows when to pick each tier
+  const tierDescriptions = Object.entries(tiers)
+    .map(([name, t]) => {
+      const uses = t.whenToUse.length > 0 ? t.whenToUse.join(", ") : t.description;
+      return `- @${name}: ${uses}`;
+    })
+    .join("\n");
+
+  // Task taxonomy from config
+  const taxonomy = buildTaskTaxonomy(cfg);
+
+  // Cost awareness
+  const costLine = buildCostAwareness(cfg);
+
+  // Mode-aware rules: if active mode has overrideRules, use those; otherwise use global rules
+  const mode = getActiveMode(cfg);
+  const effectiveRules = mode?.overrideRules?.length ? mode.overrideRules : cfg.rules;
+  const numberedRules = effectiveRules
+    .map((rule, i) => `${i + 1}. ${rule}`)
+    .join("\n");
+
+  const fallbackInstructions = buildFallbackInstructions(cfg);
+
   return [
     "## Model Delegation Protocol",
     `Preset: ${cfg.activePreset}. Tiers: ${tierSummary}.`,
     "",
+    "Tier capabilities:",
+    tierDescriptions,
+    ...(taxonomy ? ["", taxonomy] : []),
+    ...(costLine ? ["", costLine] : []),
+    ...(mode ? [`\nActive mode: ${cfg.activeMode} (${mode.description})`] : []),
+    "",
     "Apply to every user message (plan and ad-hoc):",
-    "1. Split multi-part requests into atomic tasks.",
-    "2. Respect explicit tier instructions and [tier:fast|medium|heavy] tags.",
-    "3. Route read-only search/exploration tasks to @fast.",
-    "4. Route implementation/edit/refactor/test/bugfix tasks to @medium.",
-    "5. Route architecture/security/performance/complex debugging to @heavy.",
-    "6. For mixed requests, delegate each subtask to the matching tier, then synthesize one final response.",
-    "7. For trivial single read/grep tasks, execute directly.",
-    `8. If uncertain, default to @${cfg.defaultTier}.`,
+    numberedRules,
+    ...(fallbackInstructions ? ["", fallbackInstructions] : []),
     "",
-    "Delegate with Task(subagent_type=\"fast|medium|heavy\", prompt=\"...\").",
+    `Delegate with Task(subagent_type="fast|medium|heavy", prompt="...").`,
     "Keep orchestration and final synthesis in the primary agent.",
   ].join("\n");
 }
@@ -209,6 +446,50 @@ function buildTiersOutput(cfg: RouterConfig): string {
   return lines.join("\n");
 }
 
+// ---------------------------------------------------------------------------
+// /budget command output
+// ---------------------------------------------------------------------------
+
+function buildBudgetOutput(cfg: RouterConfig, args: string): string {
+  const modes = cfg.modes;
+  if (!modes || Object.keys(modes).length === 0) {
+    return 'No modes configured in tiers.json. Add a "modes" section to enable budget mode.';
+  }
+
+  const requested = args.trim().toLowerCase();
+  const currentMode = cfg.activeMode || "normal";
+
+  // No args: show current mode and available modes
+  if (!requested) {
+    const lines = ["# Routing Modes\n"];
+    for (const [name, mode] of Object.entries(modes)) {
+      const active = name === currentMode ? " <- active" : "";
+      lines.push(`- **${name}**${active}: ${mode.description} (default tier: @${mode.defaultTier})`);
+    }
+    lines.push(`\nSwitch with: \`/budget <mode>\``);
+    return lines.join("\n");
+  }
+
+  // Switch mode
+  if (modes[requested]) {
+    saveActiveMode(requested);
+    const mode = modes[requested];
+    return [
+      `Routing mode switched to **${requested}**.`,
+      "",
+      mode.description,
+      `Default tier: @${mode.defaultTier}`,
+      ...(mode.overrideRules?.length
+        ? ["", "Active rules:", ...mode.overrideRules.map((r) => `- ${r}`)]
+        : []),
+      "",
+      "Mode change takes effect immediately on the next message.",
+    ].join("\n");
+  }
+
+  return `Unknown mode: "${requested}". Available: ${Object.keys(modes).join(", ")}`;
+}
+
 // ---------------------------------------------------------------------------
 // /preset command output
 // ---------------------------------------------------------------------------
@@ -302,6 +583,10 @@ const ModelRouterPlugin: Plugin = async (_ctx: PluginInput) => {
         template: "$ARGUMENTS",
         description: "Show or switch model presets (e.g., /preset openai)",
       };
+      opencodeConfig.command["budget"] = {
+        template: "$ARGUMENTS",
+        description: "Show or switch routing mode (e.g., /budget, /budget budget, /budget quality)",
+      };
       opencodeConfig.command["annotate-plan"] = {
         template: [
           "Annotate the plan with tier directives for model delegation.",
@@ -332,19 +617,19 @@ const ModelRouterPlugin: Plugin = async (_ctx: PluginInput) => {
     },
 
     // -----------------------------------------------------------------------
-    // Inject delegation protocol — re-reads config each time for live updates
+    // Inject delegation protocol — uses cached config (invalidated on /preset or /budget)
     // -----------------------------------------------------------------------
     "experimental.chat.system.transform": async (_input: any, output: any) => {
       try {
-        cfg = loadConfig(); // Re-read for live preset switches
+        cfg = loadConfig(); // Returns cache unless invalidated
       } catch {
-        // Use cached config if file read fails
+        // Use last known config if file read fails
       }
       output.system.push(buildDelegationProtocol(cfg));
     },
 
     // -----------------------------------------------------------------------
-    // Handle /tiers and /preset commands
+    // Handle /tiers, /preset, and /budget commands
     // -----------------------------------------------------------------------
     "command.execute.before": async (input: any, output: any) => {
       if (input.command === "tiers") {
@@ -363,6 +648,16 @@ const ModelRouterPlugin: Plugin = async (_ctx: PluginInput) => {
           text: buildPresetOutput(cfg, input.arguments ?? ""),
         });
       }
+
+      if (input.command === "budget") {
+        try {
+          cfg = loadConfig();
+        } catch {}
+        output.parts.push({
+          type: "text" as const,
+          text: buildBudgetOutput(cfg, input.arguments ?? ""),
+        });
+      }
     },
   };
 };

package/tiers.json

@@ -1,9 +1,11 @@
 {
   "activePreset": "anthropic",
+  "activeMode": "normal",
   "presets": {
     "anthropic": {
       "fast": {
         "model": "anthropic/claude-haiku-4-5",
+        "costRatio": 1,
         "description": "Haiku 4.5 for exploration, search, and simple reads",
         "steps": 30,
         "prompt": "You are a fast exploration agent. Focus on speed and efficiency. Read files, search code, and return findings concisely. Do NOT make edits unless explicitly asked.",
@@ -17,6 +19,7 @@
       "medium": {
         "model": "anthropic/claude-sonnet-4-5",
         "variant": "max",
+        "costRatio": 5,
         "description": "Sonnet 4.5 max for implementation, refactoring, and tests",
         "steps": 50,
         "prompt": "You are an implementation agent. Write clean, production-quality code matching existing project patterns. Run linters/tests after changes when possible.",
@@ -31,6 +34,7 @@
       "heavy": {
         "model": "anthropic/claude-opus-4-6",
         "variant": "max",
+        "costRatio": 20,
         "description": "Opus 4.6 max for architecture, complex debugging, and security",
         "steps": 30,
         "prompt": "You are a senior architecture consultant. Analyze deeply, consider tradeoffs, and provide thorough reasoning. Be exhaustive in your analysis.",
@@ -45,6 +49,7 @@
     "openai": {
       "fast": {
         "model": "openai/gpt-5.3-codex-spark",
+        "costRatio": 1,
         "description": "GPT-5.3 Codex Spark for fast exploration and simple tasks",
         "steps": 30,
         "prompt": "You are a fast exploration agent. Focus on speed and efficiency. Read files, search code, and return findings concisely. Do NOT make edits unless explicitly asked.",
@@ -56,6 +61,7 @@
       },
       "medium": {
         "model": "openai/gpt-5.3-codex",
+        "costRatio": 5,
         "description": "GPT-5.3 Codex default settings for implementation and standard coding",
         "steps": 50,
         "prompt": "You are an implementation agent. Write clean, production-quality code matching existing project patterns. Run linters/tests after changes when possible.",
@@ -69,6 +75,7 @@
       "heavy": {
         "model": "openai/gpt-5.3-codex",
         "variant": "xhigh",
+        "costRatio": 20,
         "description": "GPT-5.3 Codex xhigh for architecture and complex tasks",
         "steps": 30,
         "prompt": "You are a senior architecture consultant. Analyze deeply, consider tradeoffs, and provide thorough reasoning.",
@@ -83,6 +90,7 @@
     "github-copilot": {
       "fast": {
         "model": "github-copilot/claude-haiku-4-5",
+        "costRatio": 1,
         "description": "Claude Haiku 4.5 via GitHub Copilot for fast exploration and simple tasks",
         "steps": 30,
         "prompt": "You are a fast exploration agent. Focus on speed and efficiency. Read files, search code, and return findings concisely. Do NOT make edits unless explicitly asked.",
@@ -95,6 +103,7 @@
       },
       "medium": {
         "model": "github-copilot/claude-sonnet-4-5",
+        "costRatio": 5,
         "description": "Claude Sonnet 4.5 via GitHub Copilot for implementation, refactoring, and tests",
         "steps": 50,
         "prompt": "You are an implementation agent. Write clean, production-quality code matching existing project patterns. Run linters/tests after changes when possible.",
@@ -109,6 +118,7 @@
       "heavy": {
         "model": "github-copilot/claude-opus-4-6",
         "variant": "thinking",
+        "costRatio": 20,
         "description": "Claude Opus 4.6 via GitHub Copilot for architecture, complex debugging, and security",
         "steps": 30,
         "prompt": "You are a senior architecture consultant. Analyze deeply, consider tradeoffs, and provide thorough reasoning. Be exhaustive in your analysis.",
@@ -123,6 +133,7 @@
     "google": {
       "fast": {
         "model": "google/gemini-2.5-flash",
+        "costRatio": 1,
         "description": "Gemini 2.5 Flash for fast exploration and simple tasks",
         "steps": 30,
         "prompt": "You are a fast exploration agent. Focus on speed and efficiency. Read files, search code, and return findings concisely. Do NOT make edits unless explicitly asked.",
@@ -135,6 +146,7 @@
       },
       "medium": {
         "model": "google/gemini-2.5-pro",
+        "costRatio": 5,
         "description": "Gemini 2.5 Pro for implementation, refactoring, and tests",
         "steps": 50,
         "prompt": "You are an implementation agent. Write clean, production-quality code matching existing project patterns. Run linters/tests after changes when possible.",
@@ -148,6 +160,7 @@
       },
       "heavy": {
         "model": "google/gemini-3-pro-preview",
+        "costRatio": 20,
         "description": "Gemini 3 Pro Preview for architecture, complex debugging, and security",
         "steps": 30,
         "prompt": "You are a senior architecture consultant. Analyze deeply, consider tradeoffs, and provide thorough reasoning. Be exhaustive in your analysis.",
@@ -160,6 +173,77 @@
       }
     }
   },
+  "taskPatterns": {
+    "fast": [
+      "Find, search, locate, or grep files and code patterns",
+      "List or show directory structure and file contents",
+      "Read or display specific files or sections",
+      "Check git status, log, diff, or blame",
+      "Lookup documentation, API signatures, or type definitions",
+      "Count occurrences, lines, or matches",
+      "Check if a file, function, or class exists",
+      "Simple rename or string replacement across files"
+    ],
+    "medium": [
+      "Implement a new feature, function, or component",
+      "Refactor or restructure existing code",
+      "Write or update tests",
+      "Fix a bug (first or second attempt)",
+      "Modify or update existing code logic",
+      "Code review with suggested changes",
+      "Run build/lint/test and fix resulting errors",
+      "Create a new file from a template or pattern",
+      "Database migration or schema changes",
+      "API endpoint implementation",
+      "Configuration or dependency updates"
+    ],
+    "heavy": [
+      "Design system or module architecture from scratch",
+      "Debug a problem after 2+ failed attempts",
+      "Security audit or vulnerability review",
+      "Performance profiling and optimization",
+      "Migration strategy (framework, language, infrastructure)",
+      "Complex multi-system integration design",
+      "Evaluate tradeoffs between competing approaches",
+      "Root cause analysis of complex or elusive failures"
+    ]
+  },
+  "modes": {
+    "normal": {
+      "defaultTier": "medium",
+      "description": "Balanced quality and cost — delegates based on task complexity"
+    },
+    "budget": {
+      "defaultTier": "fast",
+      "description": "Aggressive cost savings — defaults to cheapest tier, escalates only when needed",
+      "overrideRules": [
+        "Default ALL tasks to @fast unless they clearly require code edits or complex reasoning",
+        "Use @medium ONLY for: multi-file edits, complex refactors, test suites, or build-fix cycles",
+        "Use @heavy ONLY when explicitly requested by user or after 2+ failed @medium attempts",
+        "Prefer executing simple tasks directly (grep, read, glob) over delegating — zero delegation overhead",
+        "Batch multiple related searches into a single @fast delegation instead of multiple calls",
+        "When uncertain between @fast and @medium, choose @fast — escalate only on failure"
+      ]
+    },
+    "quality": {
+      "defaultTier": "medium",
+      "description": "Quality-first — uses stronger models more liberally for better results",
+      "overrideRules": [
+        "Default to @medium for all tasks including exploration when deep context understanding matters",
+        "Use @heavy for any task involving architecture, debugging, security, or multi-file coordination",
+        "Use @fast only for trivial single-tool operations (one grep, one file read)",
+        "Prefer thoroughness over speed — better to over-qualify a task than under-qualify it"
+      ]
+    }
+  },
+  "fallback": {
+    "global": {
+      "anthropic": ["openai", "google", "github-copilot"],
+      "openai": ["anthropic", "google", "github-copilot"],
+      "github-copilot": ["anthropic", "openai", "google"],
+      "google": ["openai", "anthropic", "github-copilot"]
+    }
+  },
   "rules": [
     "When a plan step contains [tier:fast], [tier:medium], or [tier:heavy], delegate to that agent",
     "When a plan says 'use a fast/cheap model' -> delegate to @fast",
@@ -169,7 +253,10 @@
     "Use @fast for any read-only exploration or research task",
     "Keep orchestration (planning, decisions, verification) for yourself - delegate execution",
     "For trivial tasks (single grep, single file read), execute directly without delegation",
-    "Never delegate to @heavy if you are already running on an opus-class model - do it yourself"
+    "Never delegate to @heavy if you are already running on an opus-class model - do it yourself",
+    "If a task takes 1-2 tool calls, execute directly — delegation overhead is not worth the cost",
+    "Consult the task routing guide below to match task type to the correct tier",
+    "Consider cost ratios when choosing tiers — always use the cheapest tier that can reliably handle the task"
   ],
   "defaultTier": "medium"
 }