gentle-pi 0.10.1 → 0.10.3

package/README.md

@@ -68,7 +68,7 @@ pi install npm:gentle-pi
 Recommended companion packages:
 
 ```bash
-pi install npm:pi-subagents
+pi install npm:pi-subagents-j0k3r
 pi install npm:pi-intercom
 pi install npm:gentle-engram
 pi install npm:pi-web-access
@@ -115,19 +115,19 @@ Typical flow:
 | Unknown codebase area or context-heavy investigation                        | Focused subagent delegation. |
 | Large, ambiguous, architectural, product-facing, or high-review-risk change | SDD/OpenSpec flow.           |
 
-The goal is not ceremony. The goal is to avoid accidental chaos. Once a task stops being small, delegation is expected rather than optional.
+The goal is not ceremony. The goal is to avoid accidental chaos. Once a task stops being small, delegation is mandatory.
 
 ### Delegation triggers
 
-`gentle-pi` keeps the parent session thin and uses subagents at the narrowest useful point:
+`gentle-pi` keeps the parent session thin and delegates at the narrowest useful point. When the Pi Subagents extension is installed, the preferred runtime is the `subagent_*` tool family because it runs the user's configured project/global subagent definitions and preserves history/background behavior. If those tools are unavailable, the parent should fall back to Pi's native `Agent` tool or another available delegation mechanism. The requirement is delegation; the runtime is capability-dependent.
 
-| Trigger                                                                                                                     | Expected behavior                                                    |
-| --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
-| Reading 4+ files to understand a flow                                                                                       | Launch `scout` or `context-builder` and synthesize its handoff.      |
-| Touching 2+ non-trivial code files                                                                                          | Use one `worker`, or require fresh review before completion.         |
-| Commit, push, or PR after code changes                                                                                      | Run a fresh-context `reviewer` unless the diff is trivial docs/text. |
-| Wrong cwd, worktree/git accident, merge recovery, confusing test/env issue                                                  | Stop and run a fresh audit reviewer before continuing.               |
-| Long monolithic session with accumulating complexity, roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits | Pause and delegate or explain why not.                               |
+| Trigger                                                                                                                     | Required behavior                                                             |
+| --------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
+| Reading 4+ files to understand a flow                                                                                       | Launch `scout`, `context-builder`, or the closest read-only mapping subagent. |
+| Touching 2+ non-trivial code files                                                                                          | Delegate one writer; do not continue inline unless delegation is unavailable. |
+| Commit, push, or PR after code changes                                                                                      | Run a fresh-context `reviewer` unless the diff is trivial docs/text.          |
+| Wrong cwd, worktree/git accident, merge recovery, confusing test/env issue                                                  | Stop and run a fresh audit reviewer before continuing.                        |
+| Long monolithic session with accumulating complexity, roughly 20 tool calls, 5 exploratory reads, or 2 non-mechanical edits | Pause and delegate the remaining work, or stop and explain the exact blocker. |
 
 The intended balanced loop for a bounded bugfix is:
 
@@ -346,7 +346,7 @@ The modal discovers:
 
 - project agents in `.pi/agents/` and `.agents/`;
 - user agents in `~/.pi/agent/agents/` and `~/.agents/`;
-- built-in agents from `pi-subagents`.
+- built-in agents from `pi-subagents-j0k3r` when present.
 
 Recommended model/effort shape:
 

package/assets/orchestrator.md

@@ -82,7 +82,17 @@ Examples:
 - run tests/builds and summarize results;
 - fresh-context review.
 
-Use `pi-subagents` when available. Prefer background/async for long exploration, implementation, tests, or review when the parent has independent work.
+Use the configured subagent runtime when available. Prefer the `subagent_*` tools (`subagent_run`, status/result helpers) when the Pi Subagents extension is installed, because they run the user's configured project/global subagent definitions and preserve history/background behavior. Prefer `subagent_run` with `mode: "background"` for long independent exploration, implementation, tests, or review, and `mode: "task"` when the parent needs the result before continuing.
+
+If `subagent_*` tools are unavailable, fall back to Pi's native `Agent` tool or another available delegation mechanism. The delegation trigger remains mandatory; the fallback changes the runtime, not the requirement to delegate. If no delegation mechanism is available, stop the complex work and explain the blocker instead of silently continuing inline.
+
+### Pi Subagent Model Routing
+
+For generic Pi subagents (`delegate`, `worker`, `scout`, `reviewer`, `context-builder`, `oracle`, `planner`, `researcher`, or other non-SDD agents), do not pass the `model` parameter by default. Let `pi-subagents` resolve model and thinking from `.pi/settings.json`, `.pi/subagents.json`, global subagent config, and runtime defaults.
+
+SDD model assignment tables apply only to SDD/Judgment-Day phase agents. They must not be used for generic Pi delegation.
+
+Only pass `model` for generic subagents when the user explicitly requests a model override for that launch.
 
 Default balanced pattern for bounded implementation:
 
@@ -125,14 +135,14 @@ Core question: does this inflate parent context without need?
 
 ### Mandatory Delegation Triggers
 
-These are parent-orchestrator stop rules. Once any trigger fires, the parent must either delegate or explicitly tell the user why delegation would be unsafe or wasteful for this exact case. Do not inject these as child-agent permission to spawn subagents; children receive concrete role work and must not orchestrate.
+These are parent-orchestrator stop rules. Once any trigger fires, the parent MUST delegate through the best available subagent runtime. Prefer `subagent_run` when present; otherwise use Pi's native `Agent` or another available delegation mechanism. Do not replace a required delegation with inline execution. Do not inject these as child-agent permission to spawn subagents; children receive concrete role work and must not orchestrate.
 
-1. **4-file rule**: if understanding requires reading 4+ files, launch `scout` or `context-builder` with fresh context and a narrow mapping task.
-2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, use one `worker` or keep writing inline only if a fresh reviewer will audit before completion.
-3. **PR rule**: before commit/push/PR for code changes, run a fresh-context `reviewer` unless the diff is a trivial docs/text-only change.
-4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, failed merge recovery, confusing test command, or environment workaround, stop and run a fresh audit reviewer.
-5. **Long-session rule**: if accumulating work is no longer clearly local — roughly 20 tool calls, 5 exploratory file reads, or 2 non-mechanical edits without delegation — pause and choose `scout`, `worker`, or `reviewer` instead of silently continuing monolithically.
-6. **Fresh review rule**: use `context: "fresh"` for adversarial review of diffs, conflicts, PR readiness, and incident audits. Use forked context for continuity-oriented `worker`/`oracle` tasks.
+1. **4-file rule**: if understanding requires reading 4+ files, launch `scout`, `context-builder`, or the closest read-only mapping subagent with fresh context and a narrow mapping task. State the fallback agent/runtime if the preferred one is unavailable.
+2. **Multi-file write rule**: if implementation will touch 2+ non-trivial files, delegate one writer; inline writing is allowed only for trivial/mechanical edits or when the parent explicitly records why no delegation runtime is available. A fresh review still follows delegated implementation.
+3. **PR rule**: before commit/push/PR for code changes, run a fresh-context reviewer unless the diff is trivial docs/text-only.
+4. **Incident rule**: after wrong `cwd`, accidental repo/worktree mutation, failed merge recovery, confusing test command, or environment workaround, stop and run a fresh audit reviewer before continuing.
+5. **Long-session rule**: if accumulating work is no longer clearly local — roughly 20 tool calls, 5 exploratory file reads, or 2 non-mechanical edits without delegation — pause and delegate the remaining work instead of silently continuing monolithically.
+6. **Fresh review rule**: use fresh-context reviewer/audit subagents for adversarial review of diffs, conflicts, PR readiness, and incidents. Use continuity-oriented workers only for implementation work that needs inherited state.
 
 ### Cost and Context Balance
 

package/extensions/gentle-ai.ts

@@ -734,7 +734,9 @@ function normalizeRoutingEntry(value: unknown): AgentRoutingEntry | undefined {
 	if (!isRecord(value)) return undefined;
 	const model = normalizeModelId(value.model);
 	const thinking = isThinkingLevel(value.thinking) ? value.thinking : undefined;
-	if (!model && !thinking) return undefined;
+	if (!model && !thinking) {
+		return Object.keys(value).length === 0 ? {} : undefined;
+	}
 	return { model, thinking };
 }
 
@@ -987,13 +989,38 @@ async function listAgentsFromDirAsync(
 	return entries;
 }
 
-function listDiscoverableAgents(cwd: string): AgentEntry[] {
-	const globalAgentDir = join(gentlePiAgentHome(), "agents");
-	const builtinDirs = [
+function builtinAgentDirs(cwd: string): string[] {
+	return [
+		join(PACKAGE_ROOT, "..", "pi-subagents-j0k3r", "agents"),
+		join(cwd, ".pi", "npm", "node_modules", "pi-subagents-j0k3r", "agents"),
+		join(homedir(), ".local", "lib", "node_modules", "pi-subagents-j0k3r", "agents"),
 		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
 		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
 		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
 	];
+}
+
+function listBuiltinAgentNames(cwd: string): Set<string> {
+	return new Set(
+		builtinAgentDirs(cwd).flatMap((dir) =>
+			listAgentsFromDir(dir, "builtin").map((agent) => agent.name),
+		),
+	);
+}
+
+async function listBuiltinAgentNamesAsync(cwd: string): Promise<Set<string>> {
+	const names = new Set<string>();
+	for (const dir of builtinAgentDirs(cwd)) {
+		for (const agent of await listAgentsFromDirAsync(dir, "builtin")) {
+			names.add(agent.name);
+		}
+	}
+	return names;
+}
+
+function listDiscoverableAgents(cwd: string): AgentEntry[] {
+	const globalAgentDir = join(gentlePiAgentHome(), "agents");
+	const builtinDirs = builtinAgentDirs(cwd);
 	const agents = [
 		...builtinDirs.flatMap((dir) => listAgentsFromDir(dir, "builtin")),
 		...listAgentsFromDir(globalAgentDir, "user"),
@@ -1008,11 +1035,7 @@ function listDiscoverableAgents(cwd: string): AgentEntry[] {
 
 async function listDiscoverableAgentsAsync(cwd: string): Promise<AgentEntry[]> {
 	const globalAgentDir = join(gentlePiAgentHome(), "agents");
-	const builtinDirs = [
-		join(PACKAGE_ROOT, "..", "pi-subagents", "agents"),
-		join(cwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
-		join(homedir(), ".local", "lib", "node_modules", "pi-subagents", "agents"),
-	];
+	const builtinDirs = builtinAgentDirs(cwd);
 	const agents: AgentEntry[] = [];
 	for (const dir of builtinDirs) {
 		agents.push(...(await listAgentsFromDirAsync(dir, "builtin")));
@@ -1045,6 +1068,10 @@ function projectSettingsPath(cwd: string): string {
 	return join(cwd, ".pi", "settings.json");
 }
 
+function isClearRoutingEntry(entry: AgentRoutingEntry): boolean {
+	return entry.model === undefined && entry.thinking === undefined;
+}
+
 function updateBuiltinModelOverride(
 	cwd: string,
 	name: string,
@@ -1131,13 +1158,28 @@ export function applyModelConfig(
 ): { updated: number; skipped: number } {
 	let updated = 0;
 	let skipped = 0;
+	const builtinNames = listBuiltinAgentNames(cwd);
+	const seenAgents = new Set<string>();
 	for (const agent of listDiscoverableAgents(cwd)) {
+		seenAgents.add(agent.name);
 		const entry = config[agent.name];
 		if (agent.source === "builtin") {
+			if (entry === undefined) {
+				skipped += 1;
+				continue;
+			}
 			if (updateBuiltinModelOverride(cwd, agent.name, entry)) updated += 1;
 			else skipped += 1;
 			continue;
 		}
+		if (entry === undefined) {
+			skipped += 1;
+			continue;
+		}
+		if (builtinNames.has(agent.name) || isClearRoutingEntry(entry)) {
+			if (updateBuiltinModelOverride(cwd, agent.name, entry)) updated += 1;
+			else skipped += 1;
+		}
 		if (!agent.filePath || !existsSync(agent.filePath)) {
 			skipped += 1;
 			continue;
@@ -1151,6 +1193,12 @@ export function applyModelConfig(
 		writeFileSync(agent.filePath, next);
 		updated += 1;
 	}
+	for (const [name, entry] of Object.entries(config)) {
+		if (!seenAgents.has(name) && isClearRoutingEntry(entry)) {
+			if (updateBuiltinModelOverride(cwd, name, entry)) updated += 1;
+			else skipped += 1;
+		}
+	}
 	return { updated, skipped };
 }
 
@@ -1160,14 +1208,30 @@ export async function applyModelConfigAsync(
 ): Promise<{ updated: number; skipped: number }> {
 	let updated = 0;
 	let skipped = 0;
+	const builtinNames = await listBuiltinAgentNamesAsync(cwd);
+	const seenAgents = new Set<string>();
 	for (const agent of await listDiscoverableAgentsAsync(cwd)) {
+		seenAgents.add(agent.name);
 		const entry = config[agent.name];
 		if (agent.source === "builtin") {
+			if (entry === undefined) {
+				skipped += 1;
+				continue;
+			}
 			if (await updateBuiltinModelOverrideAsync(cwd, agent.name, entry))
 				updated += 1;
 			else skipped += 1;
 			continue;
 		}
+		if (entry === undefined) {
+			skipped += 1;
+			continue;
+		}
+		if (builtinNames.has(agent.name) || isClearRoutingEntry(entry)) {
+			if (await updateBuiltinModelOverrideAsync(cwd, agent.name, entry))
+				updated += 1;
+			else skipped += 1;
+		}
 		if (!agent.filePath || !(await pathExists(agent.filePath))) {
 			skipped += 1;
 			continue;
@@ -1181,6 +1245,13 @@ export async function applyModelConfigAsync(
 		await writeFile(agent.filePath, next);
 		updated += 1;
 	}
+	for (const [name, entry] of Object.entries(config)) {
+		if (!seenAgents.has(name) && isClearRoutingEntry(entry)) {
+			if (await updateBuiltinModelOverrideAsync(cwd, name, entry))
+				updated += 1;
+			else skipped += 1;
+		}
+	}
 	return { updated, skipped };
 }
 
@@ -1500,7 +1571,7 @@ class SddModelPanel implements OverlayComponent {
 		const current = this.draft[name] ?? {};
 		if (model === undefined) delete current.model;
 		else current.model = model;
-		if (!current.model && !current.thinking) delete this.draft[name];
+		if (!current.model && !current.thinking) this.draft[name] = {};
 		else this.draft[name] = current;
 	}
 
@@ -1508,12 +1579,12 @@ class SddModelPanel implements OverlayComponent {
 		const current = this.draft[name] ?? {};
 		if (thinking === undefined) delete current.thinking;
 		else current.thinking = thinking;
-		if (!current.model && !current.thinking) delete this.draft[name];
+		if (!current.model && !current.thinking) this.draft[name] = {};
 		else this.draft[name] = current;
 	}
 
 	private clearEntry(name: string): void {
-		delete this.draft[name];
+		this.draft[name] = {};
 	}
 
 	private filteredModelOptions(): string[] {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "gentle-pi",
-  "version": "0.10.1",
+  "version": "0.10.3",
   "description": "Turn Pi into el Gentleman: a senior-architect development harness with SDD/OpenSpec, subagents, strict TDD evidence, review guardrails, and skill discovery.",
   "license": "MIT",
   "type": "module",

package/tests/runtime-harness.mjs

@@ -197,6 +197,10 @@ async function run() {
 		const promptResult = await promptHook({ systemPrompt: "base" }, createCtx(promptCwd));
 		assert.match(promptResult.systemPrompt, /base/);
 		assert.match(promptResult.systemPrompt, /el Gentleman/);
+		assert.match(promptResult.systemPrompt, /do not pass the `model` parameter by default/);
+		assert.match(promptResult.systemPrompt, /SDD model assignment tables apply only to SDD\/Judgment-Day phase agents/);
+		assert.doesNotMatch(promptResult.systemPrompt, /Every Agent tool call MUST include `model`/);
+		assert.doesNotMatch(promptResult.systemPrompt, /default\s*\|\s*sonnet\s*\|\s*Non-SDD general delegation/);
 		assert.match(promptResult.systemPrompt, /openspec\/config\.yaml.*not session preflight/s);
 		assert.match(promptResult.systemPrompt, /Do not mark SDD preflight complete/);
 		await writeFile(
@@ -765,21 +769,102 @@ async function run() {
 		assert.equal(await readFile(globalModelsPath, "utf8"), "{ invalid json");
 		assert.equal(legacyCtx.ui.notifications.at(-1).level, "warning");
 		assert.match(legacyCtx.ui.notifications.at(-1).message, /cannot open model config/);
+		await writeFile(
+			join(legacyModelsCwd, ".pi", "settings.json"),
+			JSON.stringify(
+				{
+					subagents: {
+						agentOverrides: {
+							"sdd-apply": { model: "settings/provider-model", thinking: "high" },
+						},
+					},
+				},
+				null,
+				2,
+			),
+		);
 		await writeFile(globalModelsPath, JSON.stringify({}, null, 2));
 		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
-		const emptyGlobalSuppressesLegacyAgent = await readFile(
+		const emptyGlobalPreservesAgent = await readFile(
+			join(legacyModelsCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.match(emptyGlobalPreservesAgent, /model: global\/provider-model/);
+		const emptyGlobalPreservesSettings = JSON.parse(
+			await readFile(join(legacyModelsCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(
+			emptyGlobalPreservesSettings.subagents.agentOverrides["sdd-apply"].model,
+			"settings/provider-model",
+		);
+		await writeFile(
+			globalModelsPath,
+			JSON.stringify({ "sdd-apply": { model: "bad\nmodel: injected" } }, null, 2),
+		);
+		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
+		const invalidEntryPreservesAgent = await readFile(
 			join(legacyModelsCwd, ".pi", "agents", "sdd-apply.md"),
 			"utf8",
 		);
-		assert.doesNotMatch(emptyGlobalSuppressesLegacyAgent, /model:/);
+		assert.match(invalidEntryPreservesAgent, /model: global\/provider-model/);
+		const invalidEntryPreservesSettings = JSON.parse(
+			await readFile(join(legacyModelsCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(
+			invalidEntryPreservesSettings.subagents.agentOverrides["sdd-apply"].model,
+			"settings/provider-model",
+		);
+		await writeFile(globalModelsPath, JSON.stringify({ "sdd-apply": {} }, null, 2));
+		await hooks.get("session_start")[0]({ reason: "startup" }, legacyCtx);
+		const explicitInheritClearsAgent = await readFile(
+			join(legacyModelsCwd, ".pi", "agents", "sdd-apply.md"),
+			"utf8",
+		);
+		assert.doesNotMatch(explicitInheritClearsAgent, /model:/);
+		const explicitInheritClearsSettings = JSON.parse(
+			await readFile(join(legacyModelsCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(explicitInheritClearsSettings.subagents, undefined);
 	} finally {
 		await rm(legacyModelsCwd, { recursive: true, force: true });
 		await rm(globalModelsPath, { force: true });
 	}
 
+	const staleSettingsOnlyCwd = await tempWorkspace();
+	try {
+		await mkdir(join(staleSettingsOnlyCwd, ".pi"), { recursive: true });
+		await writeFile(
+			join(staleSettingsOnlyCwd, ".pi", "settings.json"),
+			JSON.stringify(
+				{
+					subagents: {
+						agentOverrides: {
+							worker: { model: "stale/model", thinking: "high" },
+						},
+					},
+				},
+				null,
+				2,
+			),
+		);
+		await writeFile(globalModelsPath, JSON.stringify({ worker: {} }, null, 2));
+		await hooks.get("session_start")[0]({ reason: "startup" }, createCtx(staleSettingsOnlyCwd, true));
+		const staleOnlyClearedSettings = JSON.parse(
+			await readFile(join(staleSettingsOnlyCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(staleOnlyClearedSettings.subagents, undefined);
+	} finally {
+		await rm(staleSettingsOnlyCwd, { recursive: true, force: true });
+		await rm(globalModelsPath, { force: true });
+	}
+
 	const modelsCwd = await tempWorkspace();
 	try {
 		await mkdir(join(modelsCwd, ".pi", "agents"), { recursive: true });
+		await mkdir(
+			join(modelsCwd, ".pi", "npm", "node_modules", "pi-subagents-j0k3r", "agents"),
+			{ recursive: true },
+		);
 		await mkdir(
 			join(modelsCwd, ".pi", "npm", "node_modules", "pi-subagents", "agents"),
 			{ recursive: true },
@@ -790,12 +875,28 @@ async function run() {
 				".pi",
 				"npm",
 				"node_modules",
-				"pi-subagents",
+				"pi-subagents-j0k3r",
 				"agents",
 				"worker.md",
 			),
 			`---\nname: worker\ndescription: Builtin worker\n---\n`,
 		);
+		await writeFile(
+			join(modelsCwd, ".pi", "agents", "worker.md"),
+			`---\nname: worker\ndescription: Project worker\nmodel: existing/project-worker\nthinking: high\n---\n`,
+		);
+		await writeFile(
+			join(
+				modelsCwd,
+				".pi",
+				"npm",
+				"node_modules",
+				"pi-subagents",
+				"agents",
+				"researcher.md",
+			),
+			`---\nname: researcher\ndescription: Legacy builtin researcher\n---\n`,
+		);
 		await writeFile(
 			join(modelsCwd, ".pi", "agents", "sdd-apply.md"),
 			`---\nname: sdd-apply\ndescription: Apply phase\n---\n\nbody\n`,
@@ -811,6 +912,52 @@ async function run() {
 			join(modelsCwd, ".pi", "agents", "escape-agent.md"),
 			`---\nname: evil\u001b]52;c;Zm9v\u0007-agent\ndescription: Escape fixture\n---\n`,
 		);
+		await writeFile(
+			join(modelsCwd, ".pi", "settings.json"),
+			JSON.stringify(
+				{
+					subagents: {
+						agentOverrides: {
+							worker: { model: "existing/model", thinking: "high" },
+						},
+					},
+				},
+				null,
+				2,
+			),
+		);
+		await writeFile(globalModelsPath, JSON.stringify({}, null, 2));
+		await hooks.get("session_start")[0]({ reason: "startup" }, createCtx(modelsCwd, true));
+		const preservedSettings = JSON.parse(
+			await readFile(join(modelsCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(
+			preservedSettings.subagents.agentOverrides.worker.model,
+			"existing/model",
+		);
+		assert.equal(
+			preservedSettings.subagents.agentOverrides.worker.thinking,
+			"high",
+		);
+		const preservedProjectWorker = await readFile(
+			join(modelsCwd, ".pi", "agents", "worker.md"),
+			"utf8",
+		);
+		assert.match(preservedProjectWorker, /model: existing\/project-worker/);
+		assert.match(preservedProjectWorker, /thinking: high/);
+		await writeFile(globalModelsPath, JSON.stringify({ worker: {} }, null, 2));
+		await hooks.get("session_start")[0]({ reason: "startup" }, createCtx(modelsCwd, true));
+		const clearedSettings = JSON.parse(
+			await readFile(join(modelsCwd, ".pi", "settings.json"), "utf8"),
+		);
+		assert.equal(clearedSettings.subagents, undefined);
+		const clearedProjectWorker = await readFile(
+			join(modelsCwd, ".pi", "agents", "worker.md"),
+			"utf8",
+		);
+		assert.doesNotMatch(clearedProjectWorker, /model:/);
+		assert.doesNotMatch(clearedProjectWorker, /thinking:/);
+
 		await writeFile(
 			globalModelsPath,
 			JSON.stringify({ "sdd-apply": "openai/gpt-5" }, null, 2),
@@ -891,6 +1038,7 @@ async function run() {
 				config: {
 					"sdd-apply": { model: "openai/gpt-5", thinking: "high" },
 					worker: { model: "openai/gpt-5-mini", thinking: "low" },
+					researcher: { model: "openai/gpt-5-mini", thinking: "low" },
 				},
 			});
 		await commands.get("gentle:models").handler("", ctx);
@@ -928,6 +1076,11 @@ async function run() {
 			"openai/gpt-5-mini",
 		);
 		assert.equal(settings.subagents.agentOverrides.worker.thinking, "low");
+		assert.equal(
+			settings.subagents.agentOverrides.researcher.model,
+			"openai/gpt-5-mini",
+		);
+		assert.equal(settings.subagents.agentOverrides.researcher.thinking, "low");
 
 		const kittyE = "\x1b[101u";
 		assert.notEqual(kittyE, "e");