@ikie-dev/cli 9.8.7 → 9.9.1

package/.ikie/ferments/019f2b8e-9974-700e-b045-cc2244e4d691/reviews/phase-phase-1-1.json

@@ -0,0 +1,62 @@
+{
+  "schemaVersion": 1,
+  "fermentId": "019f2b8e-9974-700e-b045-cc2244e4d691",
+  "phaseId": "phase-1",
+  "phaseName": "Phase 1",
+  "attempt": 1,
+  "timestamp": "2026-07-04T05:16:33.545Z",
+  "goal": "Build 1",
+  "summary": "phase done",
+  "stepSummaries": "  1. Step 1 [done]",
+  "diffAvailable": false,
+  "flags": [],
+  "derivedGrade": "A",
+  "reviewerRationale": "All gates pass; project checks validate.",
+  "gateVerdicts": [
+    {
+      "id": "F1",
+      "verdict": "pass",
+      "rationale": "All step verifications were real.",
+      "evidence": "step-1 used smoke"
+    },
+    {
+      "id": "F2",
+      "verdict": "pass",
+      "rationale": "Phase goal delivered.",
+      "evidence": "feature.ts:1-40"
+    },
+    {
+      "id": "F3",
+      "verdict": "pass",
+      "rationale": "Nothing deferred.",
+      "evidence": "n/a"
+    }
+  ],
+  "projectChecks": {
+    "discovered": true,
+    "anyFailed": false,
+    "commands": [
+      {
+        "kind": "test",
+        "command": "npm test",
+        "exitCode": 0,
+        "durationMs": 0,
+        "timedOut": false
+      },
+      {
+        "kind": "lint",
+        "command": "npm run lint",
+        "exitCode": 0,
+        "durationMs": 0,
+        "timedOut": false
+      },
+      {
+        "kind": "typecheck",
+        "command": "npm run typecheck",
+        "exitCode": 0,
+        "durationMs": 0,
+        "timedOut": false
+      }
+    ]
+  }
+}

package/.ikie/ferments/019f2b8e-9974-700e-b045-cc2244e4d691/runtime.json

@@ -0,0 +1,9 @@
+{
+  "schemaVersion": 1,
+  "stepStartCounts": {},
+  "blockRetries": {},
+  "lastBlockHashes": {},
+  "stepCompleteAttempts": {},
+  "phaseStartRefs": {},
+  "stepStartRefs": {}
+}

package/package.json

@@ -1,126 +1,104 @@
 {
-	"name": "@ikie-dev/cli",
-	"version": "9.8.7",
-	"description": "ikie \u2014 a coding agent CLI powered by ikie AI",
-	"type": "module",
-	"license": "Apache-2.0",
-	"bin": {
-		"ikie-cli": "src/entry.ts"
-	},
-	"scripts": {
-		"clean": "rm -rf dist",
-		"build": "tsc --noEmit && node scripts/copy-resources.js --dev",
-		"build:proxy-helper": "node scripts/build-proxy-helper.js",
-		"build:binary": "node scripts/build-binary.js",
-		"install:local": "node scripts/install-local.js",
-		"build:binary-linux-arm64": "node scripts/build-binary.js --target linux-arm64",
-		"build:binary-linux-x64": "node scripts/build-binary.js --target linux-x64",
-		"build:binary-windows-x64": "node scripts/build-binary.js --target windows-x64",
-		"dev": "make -C tools/proxy-helper/ copy-for-dev && bun run --preload ./src/set-package-dir.ts src/entry.ts",
-		"dev:overlay": "scripts/dev-overlay.sh",
-		"dev:setup": "bun run --preload ./src/set-package-dir.ts src/entry.ts setup",
-		"lint": "biome check src/ scripts/",
-		"lint:fix": "biome check --write src/ scripts/",
-		"typecheck": "tsc --noEmit",
-		"check": "pnpm run lint && pnpm run typecheck",
-		"test": "vitest run --dir src",
-		"test:smoke": "vitest run --config tests/smoke/vitest.config.ts",
-		"test:e2e:tui": "pnpm run build:binary && node scripts/run-tui-e2e.js",
-		"test:e2e:tui:debug": "pnpm run build:binary && node scripts/run-tui-e2e.js --debug",
-		"test:e2e:tui:trace": "pnpm run build:binary && node scripts/run-tui-e2e.js --trace",
-		"test:e2e:tui:trace:replay": "node scripts/run-tui-e2e.js replay",
-		"test:e2e:acp": "pnpm run build:binary && vitest run --config tests/e2e/acp/vitest.config.ts",
-		"prepublishOnly": "node scripts/prepublish-npm.js",
-		"postinstall": "node scripts/patch-pi-ai-oauth.js",
-		"prepare": "husky",
-		"verify": "pnpm run check && pnpm run build:binary && pnpm run test && pnpm run test:smoke"
-	},
-	"piConfig": {
-		"name": "ikie",
-		"configDir": ".config/ikie/harness"
-	},
-	"dependencies": {
-		"@agentclientprotocol/sdk": "0.19.2",
-		"@clack/prompts": "^1.3.0",
-		"@earendil-works/pi-ai": "0.78.1",
-		"@earendil-works/pi-coding-agent": "0.78.1",
-		"@earendil-works/pi-tui": "0.78.1",
-		"@mixmark-io/domino": "^2.2.0",
-		"@modelcontextprotocol/ext-apps": "^1.7.1",
-		"@modelcontextprotocol/sdk": "^1.29.0",
-		"@shikijs/cli": "^4.0.2",
-		"@types/diff": "^8.0.0",
-		"@types/proper-lockfile": "^4.1.4",
-		"@types/ssh2": "^1.15.5",
-		"@xterm/headless": "^6.0.0",
-		"diff": "^9.0.0",
-		"micromatch": "^4.0.8",
-		"open": "^10.2.0",
-		"proper-lockfile": "^4.1.2",
-		"shell-quote": "^1.8.3",
-		"shiki": "^4.0.2",
-		"ssh2": "^1.17.0",
-		"tar": "^7.5.15",
-		"turndown": "^7.2.4",
-		"undici": "^8.2.0",
-		"uuid": "^14.0.0",
-		"wcwidth": "^1.0.1",
-		"ws": "^8.20.1",
-		"yaml": "^2.8.4",
-		"zod": "^4.4.3"
-	},
-	"peerDependencies": {
-		"typebox": "*"
-	},
-	"optionalDependencies": {
-		"@mariozechner/clipboard-darwin-arm64": "0.3.6",
-		"@mariozechner/clipboard-darwin-universal": "0.3.6",
-		"@mariozechner/clipboard-darwin-x64": "0.3.6",
-		"@mariozechner/clipboard-linux-arm64-gnu": "0.3.6",
-		"@mariozechner/clipboard-linux-arm64-musl": "0.3.6",
-		"@mariozechner/clipboard-linux-x64-gnu": "0.3.6",
-		"@mariozechner/clipboard-linux-x64-musl": "0.3.6",
-		"@mariozechner/clipboard-win32-arm64-msvc": "0.3.6",
-		"@mariozechner/clipboard-win32-x64-msvc": "0.3.6"
-	},
-	"devDependencies": {
-		"@biomejs/biome": "^1.9.4",
-		"@microsoft/tui-test": "0.0.4",
-		"@types/micromatch": "^4.0.10",
-		"@types/node": "^22.19.18",
-		"@types/shell-quote": "^1.7.5",
-		"@types/tar": "^7.0.87",
-		"@types/turndown": "^5.0.6",
-		"@types/ws": "^8.18.1",
-		"husky": "^9.1.7",
-		"node-pty": "^1.1.0",
-		"playwright": "^1.59.1",
-		"supports-color": "^10.2.2",
-		"tsx": "^4.21.0",
-		"typescript": "^5.9.3",
-		"vitest": "^3.2.4"
-	},
-	"engines": {
-		"node": ">=22.0.0"
-	},
-	"packageManager": "pnpm@10.8.1",
-	"pnpm": {
-		"onlyBuiltDependencies": [
-			"@biomejs/biome",
-			"esbuild",
-			"koffi",
-			"node-pty",
-			"protobufjs"
-		],
-		"ignoredOptionalDependencies": [
-			"cpu-features",
-			"nan"
-		],
-		"patchedDependencies": {
-			"@earendil-works/pi-tui": "patches/@earendil-works__pi-tui.patch",
-			"playwright-core@1.59.1": "patches/playwright-core@1.59.1.patch",
-			"@earendil-works/pi-ai@0.78.1": "patches/@earendil-works__pi-ai@0.78.1.patch",
-			"@earendil-works/pi-coding-agent@0.78.1": "patches/@earendil-works__pi-coding-agent@0.78.1.patch"
-		}
-	}
-}
+  "name": "@ikie-dev/cli",
+  "version": "9.9.1",
+  "description": "ikie — a coding agent CLI powered by ikie AI",
+  "type": "module",
+  "license": "Apache-2.0",
+  "bin": {
+    "ikie-cli": "src/entry.ts"
+  },
+  "piConfig": {
+    "name": "ikie",
+    "configDir": ".config/ikie/harness"
+  },
+  "dependencies": {
+    "@agentclientprotocol/sdk": "0.19.2",
+    "@clack/prompts": "^1.3.0",
+    "@earendil-works/pi-ai": "0.78.1",
+    "@earendil-works/pi-coding-agent": "0.78.1",
+    "@earendil-works/pi-tui": "0.78.1",
+    "@mixmark-io/domino": "^2.2.0",
+    "@modelcontextprotocol/ext-apps": "^1.7.1",
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "@shikijs/cli": "^4.0.2",
+    "@types/diff": "^8.0.0",
+    "@types/proper-lockfile": "^4.1.4",
+    "@types/ssh2": "^1.15.5",
+    "@xterm/headless": "^6.0.0",
+    "diff": "^9.0.0",
+    "micromatch": "^4.0.8",
+    "open": "^10.2.0",
+    "proper-lockfile": "^4.1.2",
+    "shell-quote": "^1.8.3",
+    "shiki": "^4.0.2",
+    "ssh2": "^1.17.0",
+    "tar": "^7.5.15",
+    "turndown": "^7.2.4",
+    "undici": "^8.2.0",
+    "uuid": "^14.0.0",
+    "wcwidth": "^1.0.1",
+    "ws": "^8.20.1",
+    "yaml": "^2.8.4",
+    "zod": "^4.4.3"
+  },
+  "peerDependencies": {
+    "typebox": "*"
+  },
+  "optionalDependencies": {
+    "@mariozechner/clipboard-darwin-arm64": "0.3.6",
+    "@mariozechner/clipboard-darwin-universal": "0.3.6",
+    "@mariozechner/clipboard-darwin-x64": "0.3.6",
+    "@mariozechner/clipboard-linux-arm64-gnu": "0.3.6",
+    "@mariozechner/clipboard-linux-arm64-musl": "0.3.6",
+    "@mariozechner/clipboard-linux-x64-gnu": "0.3.6",
+    "@mariozechner/clipboard-linux-x64-musl": "0.3.6",
+    "@mariozechner/clipboard-win32-arm64-msvc": "0.3.6",
+    "@mariozechner/clipboard-win32-x64-msvc": "0.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^1.9.4",
+    "@microsoft/tui-test": "0.0.4",
+    "@types/micromatch": "^4.0.10",
+    "@types/node": "^22.19.18",
+    "@types/shell-quote": "^1.7.5",
+    "@types/tar": "^7.0.87",
+    "@types/turndown": "^5.0.6",
+    "@types/ws": "^8.18.1",
+    "husky": "^9.1.7",
+    "node-pty": "^1.1.0",
+    "playwright": "^1.59.1",
+    "supports-color": "^10.2.2",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "scripts": {
+    "clean": "rm -rf dist",
+    "build": "tsc --noEmit && node scripts/copy-resources.js --dev",
+    "build:proxy-helper": "node scripts/build-proxy-helper.js",
+    "build:binary": "node scripts/build-binary.js",
+    "install:local": "node scripts/install-local.js",
+    "build:binary-linux-arm64": "node scripts/build-binary.js --target linux-arm64",
+    "build:binary-linux-x64": "node scripts/build-binary.js --target linux-x64",
+    "build:binary-windows-x64": "node scripts/build-binary.js --target windows-x64",
+    "dev": "make -C tools/proxy-helper/ copy-for-dev && bun run --preload ./src/set-package-dir.ts src/entry.ts",
+    "dev:overlay": "scripts/dev-overlay.sh",
+    "dev:setup": "bun run --preload ./src/set-package-dir.ts src/entry.ts setup",
+    "lint": "biome check src/ scripts/",
+    "lint:fix": "biome check --write src/ scripts/",
+    "typecheck": "tsc --noEmit",
+    "check": "pnpm run lint && pnpm run typecheck",
+    "test": "vitest run --dir src",
+    "test:smoke": "vitest run --config tests/smoke/vitest.config.ts",
+    "test:e2e:tui": "pnpm run build:binary && node scripts/run-tui-e2e.js",
+    "test:e2e:tui:debug": "pnpm run build:binary && node scripts/run-tui-e2e.js --debug",
+    "test:e2e:tui:trace": "pnpm run build:binary && node scripts/run-tui-e2e.js --trace",
+    "test:e2e:tui:trace:replay": "node scripts/run-tui-e2e.js replay",
+    "test:e2e:acp": "pnpm run build:binary && vitest run --config tests/e2e/acp/vitest.config.ts",
+    "postinstall": "node scripts/patch-pi-ai-oauth.js",
+    "verify": "pnpm run check && pnpm run build:binary && pnpm run test && pnpm run test:smoke"
+  }
+}

package/scripts/prepublish-npm.js

@@ -6,7 +6,7 @@
 //   - src/core/export-html/<templates> (upstream pi-coding-agent looks there)
 //   - package.json at the package root
 
-import { cpSync, existsSync, mkdirSync, readdirSync, readFileSync, writeFileSync } from "node:fs"
+import { cpSync, existsSync, mkdirSync, readFileSync, readdirSync, writeFileSync } from "node:fs"
 import { dirname, join } from "node:path"
 import { fileURLToPath } from "node:url"
 

package/src/cli-auth/index.test.ts

@@ -7,14 +7,16 @@ const mockFetch = vi.fn()
 
 const DEFAULT_BASE = "https://ikie-cli.xyz"
 
-function deviceResponse(overrides: Partial<{
-	device_code: string
-	user_code: string
-	verification_uri: string
-	verification_uri_complete: string
-	expires_in: number
-	interval: number
-}> = {}) {
+function deviceResponse(
+	overrides: Partial<{
+		device_code: string
+		user_code: string
+		verification_uri: string
+		verification_uri_complete: string
+		expires_in: number
+		interval: number
+	}> = {},
+) {
 	return {
 		device_code: "dc-test-123",
 		user_code: "ABC-123",
@@ -91,8 +93,10 @@ describe("authenticateViaBrowser", () => {
 	})
 
 	it("throws when cancelled via signal", async () => {
-		mockFetch
-			.mockResolvedValueOnce({ ok: true, json: () => Promise.resolve(deviceResponse({ expires_in: 60000, interval: 0 })) })
+		mockFetch.mockResolvedValueOnce({
+			ok: true,
+			json: () => Promise.resolve(deviceResponse({ expires_in: 60000, interval: 0 })),
+		})
 
 		const ctrl = new AbortController()
 		const promise = authenticateViaBrowser({ quiet: true, signal: ctrl.signal })

package/src/extensions/agents/prompt/skill-loader.test.ts

@@ -38,4 +38,22 @@ describe("preloadSkills", () => {
 		expect(results[0].name).toBe("my-skill")
 		expect(results[0].content).toContain("This is the skill content.")
 	})
+
+	it("normalizes an invalid skill name before loading", () => {
+		const base = join(tmpdir(), `ikie-skill-test-${Date.now()}`)
+		const cwd = join(base, "project")
+
+		// Place skill at <cwd>/.pi/agent/skills (second entry in DEFAULT_SKILL_PATHS)
+		const skillDir = join(cwd, ".pi", "agent", "skills", "ckm:slides")
+		mkdirSync(skillDir, { recursive: true })
+		writeFileSync(
+			join(skillDir, "SKILL.md"),
+			"---\nname: ckm:slides\ndescription: slides skill\n---\nSlides skill body.",
+		)
+
+		const results = preloadSkills(["ckm-slides"], cwd)
+		expect(results).toHaveLength(1)
+		expect(results[0].name).toBe("ckm-slides")
+		expect(results[0].content).toContain("Slides skill body.")
+	})
 })

package/src/extensions/agents/prompt/skill-loader.ts

@@ -10,8 +10,11 @@ import { isAbsolute, join } from "node:path"
 import type { Skill } from "@earendil-works/pi-coding-agent"
 import { loadSkillsFromDir } from "@earendil-works/pi-coding-agent"
 import { DEFAULT_SKILL_PATHS } from "../../../config.js"
+import { createSkillSanitizer } from "../../skills-manager/skill-sanitizer.js"
 import { isUnsafeName } from "../memory/memory.js"
 
+const skillSanitizer = createSkillSanitizer()
+
 export interface PreloadedSkill {
 	name: string
 	content: string
@@ -44,7 +47,7 @@ export function preloadSkills(skillNames: string[], cwd: string): PreloadedSkill
 	const allSkills = new Map<string, Skill>()
 	for (const dir of resolvedPaths) {
 		try {
-			const { skills } = loadSkillsFromDir({ dir, source: dir })
+			const { skills } = loadSkillsFromDir({ dir: skillSanitizer.sanitizePath(dir), source: dir })
 			for (const skill of skills) {
 				// Later paths (higher priority) override earlier ones
 				allSkills.set(skill.name, skill)

package/src/extensions/ferment/index.ts

@@ -38,6 +38,7 @@ import { getActive, getActiveId, getContinuationPolicy } from "./state.js"
 import { createFermentTipProvider } from "./tips.js"
 import { registerFermentTodoSync } from "./todo-sync.js"
 import { applyFermentRuntimeToolProfile } from "./tool-scope.js"
+import { registerEscalateTool } from "./tools/escalate.js"
 import { registerKnowledgeTools } from "./tools/knowledge.js"
 import { buildFreeformScopingFeedbackMessage, registerLifecycleTools } from "./tools/lifecycle.js"
 import { registerPhaseTools } from "./tools/phases.js"
@@ -333,5 +334,6 @@ export default function fermentExtension(pi: ExtensionAPI, runtime: FermentRunti
 	registerPhaseTools(pi, runtime)
 	registerStepTools(pi, runtime)
 	registerKnowledgeTools(pi, runtime)
+	registerEscalateTool(pi, runtime)
 	registerAgentSpawnGuard(pi, runtime)
 }

package/src/extensions/ferment/tools/escalate.ts

@@ -0,0 +1,70 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent"
+import { findFirstPlannedPhase } from "../../../ferment/engine.js"
+import { captureGitHead } from "../phase-evidence.js"
+import type { FermentRuntime } from "../runtime.js"
+import { createApplyAndPersist, toolOk } from "../tool-helpers.js"
+import { applyFermentToolProfile, profileForFerment } from "../tool-scope.js"
+
+export function registerEscalateTool(pi: ExtensionAPI, runtime: FermentRuntime): void {
+	pi.registerTool({
+		name: "escalate_tools",
+		label: "Escalate Tools",
+		description:
+			"Upgrade your tool access when you need write/execute tools (bash, edit, write, start_ferment_step, etc.) that aren't currently available. " +
+			"If a ferment exists and is in planning phase, this activates the first planned phase and unlocks the full implementation toolset. " +
+			"If no ferment is active, it tells you how to start one.",
+		parameters: {
+			type: "object",
+			properties: {},
+			additionalProperties: false,
+		},
+		async execute() {
+			const ferment = runtime.getActive()
+
+			if (!ferment) {
+				return toolOk(
+					"No active ferment found. Use `/ferment new <your task>` to start one, then call escalate_tools again after scoping to begin implementation.",
+				)
+			}
+
+			const currentProfile = profileForFerment(ferment)
+			if (currentProfile === "implementation") {
+				return toolOk(
+					`Already in implementation phase (ferment: ${ferment.id}). All tools should be available. If something is still missing, check your permissions config.`,
+				)
+			}
+
+			const planned = findFirstPlannedPhase(ferment)
+			if (!planned) {
+				return toolOk(
+					`Ferment "${ferment.id}" has no planned phases to activate. Use scope_ferment to define phases, then call escalate_tools again.`,
+				)
+			}
+
+			const storage = runtime.getStorage()
+			const f = storage.get(ferment.id)
+			if (!f) {
+				return toolOk(`Ferment "${ferment.id}" not found in storage. Try /ferment list to see available ferments.`)
+			}
+
+			const applyAndPersist = createApplyAndPersist(runtime)
+			const outcome = applyAndPersist(ferment.id, { type: "activate_phase", phaseId: planned.id })
+			if (!outcome.ok) {
+				return toolOk(`Could not activate phase: ${outcome.error.message}`)
+			}
+
+			try {
+				applyFermentToolProfile(pi, profileForFerment(outcome.ferment))
+			} catch (err) {
+				console.error("[ferment] escalate_tools: applyFermentToolProfile failed", err)
+			}
+
+			const headRef = captureGitHead()
+			if (headRef) runtime.setPhaseStartRef(ferment.id, planned.id, headRef)
+
+			return toolOk(
+				`Phase "${planned.name}" activated. Tool access upgraded to implementation — you now have bash, edit, write, start_ferment_step, and all other execution tools.`,
+			)
+		},
+	})
+}

package/src/extensions/orchestration/continuation-nudge.test.ts

@@ -30,6 +30,9 @@ function makeAssistant(content: AssistantMessage["content"]): AssistantMessage {
 }
 
 const textOnlyMessage = makeAssistant([{ type: "text", text: "I will delegate this to Nemotron." }])
+const greetingMessage = makeAssistant([
+	{ type: "text", text: "Hi there! I'm ready to help. What would you like to work on?" },
+])
 
 const toolCallMessage = makeAssistant([
 	{
@@ -193,6 +196,12 @@ describe("ContinuationNudge.evaluateTurn", () => {
 		simulateSessionWithPriorToolCall(guard)
 		expect(guard.evaluateTurn(textOnlyMessage)).toBe(true)
 	})
+
+	it("does not nudge normal conversational replies after prior tool use", () => {
+		const guard = new ContinuationNudge()
+		simulateSessionWithPriorToolCall(guard)
+		expect(guard.evaluateTurn(greetingMessage)).toBe(false)
+	})
 })
 
 describe("ContinuationNudge session-level tool tracking", () => {

package/src/extensions/orchestration/continuation-nudge.ts

@@ -44,6 +44,13 @@ export const SECOND_NUDGE_TEXT =
 export const EMPTY_TURN_NUDGE_TEXT =
 	"If you have finished, please summarize the result for the user. Otherwise, continue with the next tool call."
 
+const TOOL_INTENT_RE =
+	/\b(?:i(?:'|’)ll|i\s+will|let\s+me|i(?:'|’)m\s+going\s+to|i\s+am\s+going\s+to|going\s+to)\s+(?:delegate|hand\s+off|ask\s+(?:an?\s+)?(?:agent|subagent)|use|call|run|execute|inspect|read|search|grep|find|edit|write|modify|update|create|open|check|test|verify|review|analy[sz]e|investigate)\b|\b(?:delegating|handing\s+off|calling|running|executing|reading|searching|editing|writing|checking|testing|verifying|reviewing|investigating)\b|\b(?:use|call)\s+(?:the\s+)?(?:agent|task|bash|read|grep|glob|webfetch|apply_patch|tool)\b/i
+
+function hasPendingToolIntent(message: AssistantMessage): boolean {
+	return message.content.some((c) => c.type === "text" && TOOL_INTENT_RE.test(c.text))
+}
+
 /** Post-turn state machine for the "text-only drift" nudge.
  *
  * Fires at most twice per user-input cycle, and only when no tool has been
@@ -140,6 +147,7 @@ export class ContinuationNudge {
 		const hasToolCalls = message.content.some((c) => c.type === "toolCall")
 		const hasText = message.content.some((c) => c.type === "text" && c.text.trim().length > 0)
 		if (hasToolCalls || !hasText) return false
+		if (!hasPendingToolIntent(message)) return false
 		this.nudgeCountThisCycle++
 		this.nudgeResponsePending = true
 		return true

package/src/extensions/orchestration/model-roles.test.ts

@@ -346,8 +346,13 @@ describe("validateModelRoles", () => {
 		expect(result.unavailable).toHaveLength(0)
 	})
 
-	it("handles empty available set", () => {
+	it("does not warn for unavailable defaults unless requested", () => {
 		const result = validateModelRoles(DEFAULT_MODEL_ROLES, new Set())
+		expect(result.unavailable).toHaveLength(0)
+	})
+
+	it("can include unavailable defaults for diagnostics", () => {
+		const result = validateModelRoles(DEFAULT_MODEL_ROLES, new Set(), { warnForDefaults: true })
 		expect(result.unavailable.length).toBeGreaterThanOrEqual(5)
 		const flaggedRoles = new Set(result.unavailable.map((u) => u.role))
 		expect(flaggedRoles).toEqual(

package/src/extensions/orchestration/model-roles.ts

@@ -237,15 +237,21 @@ export interface ModelRoleValidationResult {
 	unavailable: { role: keyof ModelRoles; configuredModel: string }[]
 }
 
+function roleValuesEqual(a: RoleModelAssignment, b: RoleModelAssignment): boolean {
+	return JSON.stringify(normalizeRoleModels(a)) === JSON.stringify(normalizeRoleModels(b))
+}
+
 /**
  * Validate that each role's model(s) exist in the set of available model IDs.
  */
 export function validateModelRoles(
 	roles: ModelRoles,
 	availableModelIds: ReadonlySet<string>,
+	options: { warnForDefaults?: boolean } = {},
 ): ModelRoleValidationResult {
 	const unavailable: ModelRoleValidationResult["unavailable"] = []
 	for (const key of ROLE_KEYS) {
+		if (!options.warnForDefaults && roleValuesEqual(roles[key], DEFAULT_MODEL_ROLES[key])) continue
 		const refs = normalizeRoleModels(roles[key])
 		for (const ref of refs) {
 			const id = modelIdFromRef(ref)