feat(skills): add model override support via skill frontmatter (#2949)

* feat(skills): add model override support via skill frontmatter

Allow skills to specify a `model` field in YAML frontmatter to override
which model is used for subsequent turns within the same agentic loop.
The override flows through ToolResult → ToolCallResponseInfo →
SendMessageOptions and naturally expires when the loop ends.

Resolves #2052

* fix(core): only include modelOverride in response when defined

Fixes strict equality test failures in nonInteractiveToolExecutor.test.ts
where the extra undefined modelOverride field caused object mismatch.

* fix(skills): fix model override pipeline issues

- Wire up modelOverride in interactive CLI path (useGeminiStream)
- Fix inherit/no-model unable to clear a prior override by using
  'in' operator instead of truthiness checks in scheduler and CLI
- Reject empty/whitespace model strings in parseModelField()
- Extract shared parseModelField() to deduplicate skill-load and
  skill-manager parsing logic
- Propagate modelOverride through stop-hook continuation in client

* fix(skills): persist model override across turns in interactive and cron paths

The interactive path stored the skill model override in a local variable,
causing it to be lost when subsequent non-skill tool turns ran. Use a ref
to persist the override for the duration of the agentic loop, resetting on
new user messages. Also propagate modelOverride in the cron execution loop
for consistency with the main non-interactive path.

* fix(skills): preserve model override on retry and add unit tests

Retry in interactive mode was clearing modelOverrideRef, causing the
skill-selected model to silently fall back to session default. Guard
the reset so retries preserve the active override.

Add unit tests for parseModelField (edge cases, type validation) and
modelOverride propagation through the skill tool result path.

Author: tanzhenxin

packages/cli/src/nonInteractiveCli.ts

@@ -251,6 +251,7 @@ export async function runNonInteractive(
       let currentMessages: Content[] = [{ role: 'user', parts: initialParts }];
 
       let isFirstTurn = true;
+      let modelOverride: string | undefined;
       while (true) {
         turnCount++;
         if (
@@ -270,6 +271,7 @@ export async function runNonInteractive(
             type: isFirstTurn
               ? SendMessageType.UserQuery
               : SendMessageType.ToolResult,
+            modelOverride,
           },
         );
         isFirstTurn = false;
@@ -368,6 +370,13 @@ export async function runNonInteractive(
             if (toolResponse.responseParts) {
               toolResponseParts.push(...toolResponse.responseParts);
             }
+
+            // Capture model override from skill tool results.
+            // Use `in` so that undefined (from inherit/no-model skills) clears a prior override,
+            // while non-skill tools (field absent) leave the current override intact.
+            if ('modelOverride' in toolResponse) {
+              modelOverride = toolResponse.modelOverride;
+            }
           }
           currentMessages = [{ role: 'user', parts: toolResponseParts }];
         } else {
@@ -400,6 +409,7 @@ export async function runNonInteractive(
                       { role: 'user', parts: [{ text: cronPrompt }] },
                     ];
                     let cronIsFirstTurn = true;
+                    let cronModelOverride: string | undefined;
 
                     while (true) {
                       const cronToolCallRequests: ToolCallRequestInfo[] = [];
@@ -412,6 +422,7 @@ export async function runNonInteractive(
                           type: cronIsFirstTurn
                             ? SendMessageType.Cron
                             : SendMessageType.ToolResult,
+                          modelOverride: cronModelOverride,
                         },
                       );
                       cronIsFirstTurn = false;
@@ -476,6 +487,10 @@ export async function runNonInteractive(
                               ...toolResponse.responseParts,
                             );
                           }
+
+                          if ('modelOverride' in toolResponse) {
+                            cronModelOverride = toolResponse.modelOverride;
+                          }
                         }
                         cronMessages = [
                           { role: 'user', parts: cronToolResponseParts },

packages/cli/src/ui/hooks/useGeminiStream.ts

@@ -237,6 +237,7 @@ export const useGeminiStream = (
     null,
   );
   const processedMemoryToolsRef = useRef<Set<string>>(new Set());
+  const modelOverrideRef = useRef<string | undefined>(undefined);
   const {
     startNewPrompt,
     getPromptCount,
@@ -1255,6 +1256,11 @@ export const useGeminiStream = (
         !allowConcurrentBtwDuringResponse
       ) {
         setModelSwitchedFromQuotaError(false);
+        // Clear model override for new user turns, but preserve it on retry
+        // so the same skill-selected model is used again.
+        if (submitType !== SendMessageType.Retry) {
+          modelOverrideRef.current = undefined;
+        }
         // Commit any pending retry error to history (without hint) since the
         // user is starting a new conversation turn.
         // Clear both countdown-based errors AND static errors (those without
@@ -1354,7 +1360,7 @@ export const useGeminiStream = (
             finalQueryToSend,
             abortSignal,
             prompt_id!,
-            { type: submitType },
+            { type: submitType, modelOverride: modelOverrideRef.current },
           );
 
           const processingStatus = await processGeminiStreamEvents(
@@ -1620,6 +1626,15 @@ export const useGeminiStream = (
         (toolCall) => toolCall.request.prompt_id,
       );
 
+      // Persist model override from skill tool results (last one wins).
+      // Uses `in` so that undefined (from inherit/no-model skills) clears a
+      // prior override, while non-skill tools (field absent) leave it intact.
+      for (const toolCall of geminiTools) {
+        if ('modelOverride' in toolCall.response) {
+          modelOverrideRef.current = toolCall.response.modelOverride;
+        }
+      }
+
       markToolsAsSubmitted(callIdsToMarkAsSubmitted);
 
       // Don't continue if model was switched due to quota error

packages/core/src/core/client.ts

@@ -109,6 +109,8 @@ export interface SendMessageOptions {
     iterationCount: number;
     reasons: string[];
   };
+  /** Model override from skill execution. When present, overrides the session model for this turn. */
+  modelOverride?: string;
 }
 
 export class GeminiClient {
@@ -667,6 +669,9 @@ export class GeminiClient {
 
     const turn = new Turn(this.getChat(), prompt_id);
 
+    // Determine the model to use for this turn
+    const model = options?.modelOverride ?? this.config.getModel();
+
     // append system reminders to the request
     let requestToSent = await flatMapTextParts(request, async (text) => [text]);
     if (
@@ -709,11 +714,7 @@ export class GeminiClient {
       requestToSent = [...systemReminders, ...requestToSent];
     }
 
-    const resultStream = turn.run(
-      this.config.getModel(),
-      requestToSent,
-      signal,
-    );
+    const resultStream = turn.run(model, requestToSent, signal);
     for await (const event of resultStream) {
       if (!this.config.getSkipLoopDetection()) {
         if (this.loopDetector.addAndCheck(event)) {
@@ -846,6 +847,7 @@ export class GeminiClient {
           prompt_id,
           {
             type: SendMessageType.Hook,
+            modelOverride: options?.modelOverride,
             stopHookState: {
               iterationCount: currentIterationCount,
               reasons: currentReasons,

packages/core/src/core/coreToolScheduler.ts

@@ -1602,6 +1602,11 @@ export class CoreToolScheduler {
           error: undefined,
           errorType: undefined,
           contentLength,
+          // Propagate modelOverride from skill tools. Use `in` to distinguish
+          // "skill returned undefined (inherit)" from "non-skill tool (no field)".
+          ...('modelOverride' in toolResult
+            ? { modelOverride: toolResult.modelOverride }
+            : {}),
         };
         this.setStatusInternal(callId, 'success', successResponse);
       } else {

packages/core/src/core/turn.ts

@@ -108,6 +108,7 @@ export interface ToolCallResponseInfo {
   error: Error | undefined;
   errorType: ToolErrorType | undefined;
   contentLength?: number;
+  modelOverride?: string;
 }
 
 export interface ServerToolCallConfirmationDetails {

packages/core/src/skills/skill-load.test.ts

@@ -10,6 +10,7 @@ import {
   loadSkillsFromDir,
   validateConfig,
 } from './skill-load.js';
+import { parseModelField } from './types.js';
 import * as fs from 'fs/promises';
 
 // Mock file system operations
@@ -300,4 +301,92 @@ Valid skill.
       expect(result.warnings).toContain('Skill body is empty');
     });
   });
+
+  describe('parseModelField', () => {
+    it('should return the model string for a valid model', () => {
+      expect(parseModelField({ model: 'qwen-max' })).toBe('qwen-max');
+    });
+
+    it('should return undefined when model is omitted', () => {
+      expect(parseModelField({})).toBeUndefined();
+    });
+
+    it('should return undefined for "inherit"', () => {
+      expect(parseModelField({ model: 'inherit' })).toBeUndefined();
+    });
+
+    it('should return undefined for empty string', () => {
+      expect(parseModelField({ model: '' })).toBeUndefined();
+    });
+
+    it('should return undefined for whitespace-only string', () => {
+      expect(parseModelField({ model: '   ' })).toBeUndefined();
+    });
+
+    it('should trim whitespace from model string', () => {
+      expect(parseModelField({ model: '  qwen-max  ' })).toBe('qwen-max');
+    });
+
+    it('should throw for non-string types', () => {
+      expect(() => parseModelField({ model: 123 })).toThrow(
+        '"model" must be a string',
+      );
+      expect(() => parseModelField({ model: true })).toThrow(
+        '"model" must be a string',
+      );
+    });
+
+    it('should treat "inherit" case-sensitively', () => {
+      expect(parseModelField({ model: 'Inherit' })).toBe('Inherit');
+      expect(parseModelField({ model: 'INHERIT' })).toBe('INHERIT');
+    });
+  });
+
+  describe('parseSkillContent model field', () => {
+    const testFilePath = '/test/extension/skills/model-test/SKILL.md';
+
+    it('should parse model from frontmatter', () => {
+      mockParseYaml.mockReturnValue({
+        name: 'model-test',
+        description: 'Test skill with model',
+        model: 'qwen-max',
+      });
+
+      const config = parseSkillContent(
+        `---\nname: model-test\ndescription: Test skill with model\nmodel: qwen-max\n---\n\nBody text.`,
+        testFilePath,
+      );
+
+      expect(config.model).toBe('qwen-max');
+    });
+
+    it('should set model to undefined when omitted', () => {
+      mockParseYaml.mockReturnValue({
+        name: 'model-test',
+        description: 'Test skill without model',
+      });
+
+      const config = parseSkillContent(
+        `---\nname: model-test\ndescription: Test skill without model\n---\n\nBody text.`,
+        testFilePath,
+      );
+
+      expect(config.model).toBeUndefined();
+    });
+
+    it('should set model to undefined for "inherit"', () => {
+      mockParseYaml.mockReturnValue({
+        name: 'model-test',
+        description: 'Test skill with inherit',
+        model: 'inherit',
+      });
+
+      const config = parseSkillContent(
+        `---\nname: model-test\ndescription: Test skill with inherit\nmodel: inherit\n---\n\nBody text.`,
+        testFilePath,
+      );
+
+      expect(config.model).toBeUndefined();
+    });
+  });
 });

packages/core/src/skills/skill-load.ts

@@ -1,4 +1,8 @@
-import type { SkillConfig, SkillValidationResult } from './types.js';
+import {
+  type SkillConfig,
+  type SkillValidationResult,
+  parseModelField,
+} from './types.js';
 import * as fs from 'fs/promises';
 import * as path from 'path';
 import { parse as parseYaml } from '../utils/yaml-parser.js';
@@ -108,10 +112,14 @@ export function parseSkillContent(
     }
   }
 
+  // Extract optional model field
+  const model = parseModelField(frontmatter);
+
   const config: SkillConfig = {
     name,
     description,
     allowedTools,
+    model,
     filePath,
     body: body.trim(),
     level: 'extension',

packages/core/src/skills/skill-manager.ts

@@ -17,7 +17,7 @@ import type {
   ListSkillsOptions,
   SkillValidationResult,
 } from './types.js';
-import { SkillError, SkillErrorCode } from './types.js';
+import { SkillError, SkillErrorCode, parseModelField } from './types.js';
 import type { Config } from '../config/config.js';
 import { validateConfig } from './skill-load.js';
 import { createDebugLogger } from '../utils/debugLogger.js';
@@ -396,10 +396,14 @@ export class SkillManager {
         }
       }
 
+      // Extract optional model field
+      const model = parseModelField(frontmatter);
+
       const config: SkillConfig = {
         name,
         description,
         allowedTools,
+        model,
         level,
         filePath,
         body: body.trim(),

packages/core/src/skills/types.ts

@@ -31,6 +31,14 @@ export interface SkillConfig {
    */
   allowedTools?: string[];
 
+  /**
+   * Optional model override for this skill's execution.
+   * Uses the same selector syntax as subagent model selectors:
+   * bare model ID (e.g., `qwen-coder-plus`), `authType:modelId`
+   * for cross-provider, or omitted/`inherit` to use the session model.
+   */
+  model?: string;
+
   /**
    * Storage level - determines where the configuration file is stored
    */
@@ -58,6 +66,27 @@ export interface SkillConfig {
  */
 export type SkillRuntimeConfig = SkillConfig;
 
+/**
+ * Parse the `model` field from skill frontmatter.
+ * Returns `undefined` for omitted, empty, or "inherit" values.
+ */
+export function parseModelField(
+  frontmatter: Record<string, unknown>,
+): string | undefined {
+  const raw = frontmatter['model'];
+  if (raw === undefined) {
+    return undefined;
+  }
+  if (typeof raw !== 'string') {
+    throw new Error('"model" must be a string');
+  }
+  const trimmed = raw.trim();
+  if (trimmed === '' || trimmed === 'inherit') {
+    return undefined;
+  }
+  return trimmed;
+}
+
 /**
  * Result of a validation operation on a skill configuration.
  */