gentle-pi 0.10.1 → 0.10.2

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
@@ -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,15 @@ 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 `pi-subagents-j0k3r` when available. Prefer background/async for long exploration, implementation, tests, or review when the parent has independent work.
+
+### 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:
 

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.2",
   "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");