@ferris1225/pi-subagents 4.2.13 → 4.3.0

package/src/config.ts

@@ -13,14 +13,27 @@ import { dirname, join } from "node:path";
 import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-agent";
 
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
-export const BUILTIN_AGENT_NAMES = ["explorer", "executor"] as const;
+export const BUILTIN_AGENT_NAMES = ["scout", "artisan", "steward"] as const;
+
+/** Every shipped role stays enabled. The setup wizard and load-time adopt both
+ * force the full team on so a stale allow-list cannot hide scout, artisan, or
+ * steward. */
+export const REQUIRED_ENABLED_AGENTS = [...BUILTIN_AGENT_NAMES] as const;
 
 /** Built-in agent names this package no longer ships. Loading an older config
  * prunes them from every record so the setup wizard, dispatch catalog, and
  * model-routing table never surface dead roles. Custom names stay untouched —
  * except one that reuses a removed built-in name, which this cleanup cannot
  * distinguish and deliberately treats as retired. */
-export const REMOVED_BUILTIN_AGENT_NAMES = ["worker", "cleaner", "documenter", "synthesizer", "reviewer"] as const;
+export const REMOVED_BUILTIN_AGENT_NAMES = [
+	"worker",
+	"cleaner",
+	"documenter",
+	"synthesizer",
+	"reviewer",
+	"explorer",
+	"executor",
+] as const;
 
 /** Agents enabled out of the box on a fresh install. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = [...BUILTIN_AGENT_NAMES];
@@ -31,7 +44,49 @@ export type AgentScope = (typeof AGENT_SCOPE_VALUES)[number];
 /** Thinking levels accepted by pi's `--thinking` option. */
 export const THINKING_LEVEL_VALUES = ["off", "minimal", "low", "medium", "high", "xhigh", "max"] as const;
 export type ThinkingLevel = (typeof THINKING_LEVEL_VALUES)[number];
-export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "high";
+export const DEFAULT_THINKING_LEVEL: ThinkingLevel = "medium";
+
+/** Role-owned default reasoning strength. A `/subagents-setup` override wins;
+ * there is no per-call or frontmatter thinking. */
+export function roleThinkingLevel(agentName: string): ThinkingLevel {
+	switch (agentName) {
+		case "scout":
+			return "low";
+		case "artisan":
+			return "high";
+		case "steward":
+			return "medium";
+		default:
+			return DEFAULT_THINKING_LEVEL;
+	}
+}
+
+/** Short responsibility line shown next to each built-in in setup lists. */
+export interface AgentProfile {
+	/** A few words for picker rows. */
+	summary: string;
+	/** What this role owns, for first-run copy and the configure step. */
+	remark: string;
+}
+
+export const AGENT_PROFILES: Record<(typeof BUILTIN_AGENT_NAMES)[number], AgentProfile> = {
+	scout: {
+		summary: "read-only recon",
+		remark: "Maps unfamiliar code. Returns exact paths and leads — never proof. Broad search, symbols, dependencies.",
+	},
+	artisan: {
+		summary: "implement / fix",
+		remark: "Writes the change. One deliverable: implement, fix, refactor, or test. Confirms a named defect before editing.",
+	},
+	steward: {
+		summary: "tidy when needed",
+		remark: "Use only when that work exists: evidence-first cleanup, docs/comment sync, or merging fan-out results.",
+	},
+};
+
+export function agentProfile(name: string): AgentProfile | undefined {
+	return (AGENT_PROFILES as Record<string, AgentProfile | undefined>)[name];
+}
 
 /** How many lines of a sub-agent result the completion message may carry.
  * Default: 40 — wide fan-outs multiply completion blocks, so deliveries stay
@@ -61,7 +116,8 @@ export interface SubagentsConfig {
 	knownAgents: string[];
 	/** Per-agent model override, keyed by agent name, as "provider/model-id". */
 	agentModels: Record<string, string>;
-	/** Optional per-agent thinking preference. Runtime clamps it to the effective model's supported levels. */
+	/** Optional per-agent thinking override from `/subagents-setup`. Missing =
+	 * the role default from `roleThinkingLevel`. */
 	agentThinkingLevels: Record<string, ThinkingLevel>;
 	/**
 	 * Max lines of a sub-agent result carried in the completion message. Longer
@@ -77,6 +133,8 @@ export interface SubagentsConfig {
 	 * off to the current main model. 0 disables the idle watchdog. Default: 90.
 	 */
 	idleTimeoutSec: number;
+	/** One-shot session notice after a catalog migration; announcements clears it. */
+	pendingSetupNotice?: string;
 }
 
 export const DEFAULT_CONFIG: SubagentsConfig = {
@@ -89,6 +147,15 @@ export const DEFAULT_CONFIG: SubagentsConfig = {
 	idleTimeoutSec: DEFAULT_IDLE_TIMEOUT_SEC,
 };
 
+export const FIRST_RUN_SETUP_HINT =
+	"Run /subagents-setup: pick a model for scout, artisan, and steward. " +
+	"scout maps code (leads, not proof). artisan implements, fixes, refactors, or tests. " +
+	"steward tidies or merges only when that work exists. All three stay on. " +
+	"Each role has a thinking default you can change in setup.";
+
+export const TEAM_SETUP_NOTICE =
+	"The team is now scout, artisan, and steward. Run /subagents-setup to pick a model for each; thinking has a role default you can change there.";
+
 export function getConfigPath(agentDir: string = getAgentDir()): string {
 	return join(agentDir, CONFIG_FILE_NAME);
 }
@@ -178,6 +245,10 @@ export function normalizeConfig(raw: unknown): SubagentsConfig {
 		config.idleTimeoutSec = Math.max(0, Math.min(IDLE_TIMEOUT_SEC_LIMIT, Math.round(raw.idleTimeoutSec)));
 	}
 
+	if (typeof raw.pendingSetupNotice === "string" && raw.pendingSetupNotice.trim()) {
+		config.pendingSetupNotice = raw.pendingSetupNotice.trim();
+	}
+
 	return config;
 }
 
@@ -190,6 +261,23 @@ function defaultConfig(): SubagentsConfig {
 	};
 }
 
+export function withRequiredAgents(enabled: readonly string[]): string[] {
+	const next = [...enabled];
+	for (const name of REQUIRED_ENABLED_AGENTS) {
+		if (!next.includes(name)) next.push(name);
+	}
+	return next;
+}
+
+function forceRequiredAgents(config: SubagentsConfig): SubagentsConfig {
+	const enabledAgents = withRequiredAgents(config.enabledAgents);
+	const knownAgents = [...config.knownAgents];
+	for (const name of REQUIRED_ENABLED_AGENTS) {
+		if (!knownAgents.includes(name)) knownAgents.push(name);
+	}
+	return { ...config, enabledAgents, knownAgents };
+}
+
 /**
  * Drop every removed built-in role from an already-normalized config: enabled
  * and known lists, plus per-agent model and thinking routes. The schema-upgrade
@@ -215,38 +303,82 @@ function pruneRemovedBuiltins(config: SubagentsConfig): SubagentsConfig {
 
 /**
  * A shipped agent the config has never recorded is new in this release; the
- * stale allow-list must not keep it dark. Enable it and adopt explorer's
- * configured model and thinking level, so an upgrade surfaces the new role on
- * the fast light-task lane instead of silently spending the main model.
+ * stale allow-list must not keep it dark. Enable it. Model and thinking stay
+ * unset so the role default and current main model apply until setup.
  */
-function adoptNewBuiltins(config: SubagentsConfig): SubagentsConfig {
+function adoptNewBuiltins(config: SubagentsConfig): { config: SubagentsConfig; fresh: string[] } {
 	const known = new Set(config.knownAgents);
 	const fresh = BUILTIN_AGENT_NAMES.filter((name) => !known.has(name));
-	if (fresh.length === 0) return config;
-	const agentModels = { ...config.agentModels };
-	const agentThinkingLevels = { ...config.agentThinkingLevels };
-	for (const name of fresh) {
-		if (!agentModels[name] && config.agentModels.explorer) agentModels[name] = config.agentModels.explorer;
-		if (!agentThinkingLevels[name] && config.agentThinkingLevels.explorer) {
-			agentThinkingLevels[name] = config.agentThinkingLevels.explorer;
-		}
+	if (fresh.length === 0) return { config, fresh };
+	return {
+		config: {
+			...config,
+			enabledAgents: [...config.enabledAgents, ...fresh],
+			knownAgents: [...known, ...fresh],
+		},
+		fresh,
+	};
+}
+
+// --- v4 → current catalog migration. Delete this block in the next major. ---
+
+const RENAMED_BUILTIN_AGENTS: Record<string, string> = {
+	explorer: "scout",
+	executor: "artisan",
+};
+
+function renameNameList(names: readonly string[]): { names: string[]; changed: boolean } {
+	let changed = false;
+	const out: string[] = [];
+	for (const name of names) {
+		const mapped = RENAMED_BUILTIN_AGENTS[name] ?? name;
+		if (mapped !== name) changed = true;
+		if (!out.includes(mapped)) out.push(mapped);
 	}
+	return { names: out, changed };
+}
+
+function renameKeyedRecord<T>(record: Record<string, T>): { record: Record<string, T>; changed: boolean } {
+	let changed = false;
+	const out: Record<string, T> = {};
+	for (const [key, value] of Object.entries(record)) {
+		const mapped = RENAMED_BUILTIN_AGENTS[key] ?? key;
+		if (mapped !== key) changed = true;
+		if (!(mapped in out)) out[mapped] = value;
+	}
+	return { record: out, changed };
+}
+
+/** Map retired built-in names onto the current catalog and keep their models
+ * and thinking overrides. Isolated so the next major can delete it. */
+function migrateRetiredBuiltinNames(config: SubagentsConfig): { config: SubagentsConfig; changed: boolean } {
+	const enabled = renameNameList(config.enabledAgents);
+	const known = renameNameList(config.knownAgents);
+	const models = renameKeyedRecord(config.agentModels);
+	const thinking = renameKeyedRecord(config.agentThinkingLevels);
+	const changed = enabled.changed || known.changed || models.changed || thinking.changed;
+	if (!changed) return { config, changed: false };
 	return {
-		...config,
-		enabledAgents: [...config.enabledAgents, ...fresh],
-		knownAgents: [...known, ...fresh],
-		agentModels,
-		agentThinkingLevels,
+		changed: true,
+		config: {
+			...config,
+			enabledAgents: enabled.names,
+			knownAgents: known.names,
+			agentModels: models.record,
+			agentThinkingLevels: thinking.record,
+		},
 	};
 }
 
+// --- end v4 catalog migration ---
+
 /**
  * Load config. A missing file is a normal state and yields the defaults (not an error).
  * A corrupt file also falls back to defaults rather than throwing, so startup never breaks.
  * A file from an older version (missing newer keys or holding extra keys) is
  * normalized and persisted back, so the on-disk config stays current. Built-in
- * agents the file has never seen are adopted: enabled with explorer's route.
- * Built-in roles this package retired are pruned from every record.
+ * agents the file has never seen are adopted. Retired built-in names are
+ * renamed or pruned. Artisan and steward stay enabled.
  */
 export async function loadConfig(configPath: string = getConfigPath()): Promise<SubagentsConfig> {
 	let text: string;
@@ -264,10 +396,12 @@ export async function loadConfig(configPath: string = getConfigPath()): Promise<
 		return defaultConfig();
 	}
 
-	// Adopt newly shipped roles first so the prune below works on the final
-	// catalog, then drop roles this package stopped shipping and persist the
-	// cleaned shape back to disk.
-	const config = pruneRemovedBuiltins(adoptNewBuiltins(normalizeConfig(parsed)));
+	const renamed = migrateRetiredBuiltinNames(normalizeConfig(parsed));
+	const adopted = adoptNewBuiltins(renamed.config);
+	let config = forceRequiredAgents(pruneRemovedBuiltins(adopted.config));
+	if ((renamed.changed || adopted.fresh.length > 0) && !config.pendingSetupNotice) {
+		config = { ...config, pendingSetupNotice: TEAM_SETUP_NOTICE };
+	}
 
 	// Schema upgrade: persist the normalized shape when the file gained fields
 	// (new version) or dropped invalid ones.

package/src/dispatch.ts

@@ -1,5 +1,5 @@
 /**
- * The `subagent` tool: dispatches the enabled agents (explorer, executor,
+ * The `subagent` tool: dispatches the enabled agents (scout, artisan, steward,
  * plus custom roles) as isolated pi
  * child processes, single or parallel. Owns the public dispatch contract and
  * per-run status tracking. Stable thread generations, final integration, and
@@ -12,7 +12,7 @@ import { Text } from "@earendil-works/pi-tui";
 import { join, resolve } from "node:path";
 import { Type } from "typebox";
 import { discoverAgents, isWriteCapableAgent, resolveAgentTools, type AgentConfig } from "./agents.ts";
-import { loadConfig, THINKING_LEVEL_VALUES, type ThinkingLevel } from "./config.ts";
+import { loadConfig } from "./config.ts";
 import { formatCompletionBlock, formatUsage, queuedResult } from "./format.ts";
 import {
 	formatTaskSummary,
@@ -51,19 +51,12 @@ export { isWorktreeCapableAgent, runInManagedRepositoryLane } from "./thread-lif
 const NON_BLANK_TASK_OPTIONS = { minLength: 1, pattern: "\\S" } as const;
 
 const ISOLATION_DESCRIPTION =
-	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents, including executor, only)";
+	"Filesystem isolation: shared uses the caller's working tree; worktree creates a detached temporary Git worktree (write-capable agents, including artisan and steward, only)";
 
 const IsolationSchema = Type.Optional(
 	StringEnum(["shared", "worktree"] as const, { description: ISOLATION_DESCRIPTION }),
 );
 
-const ThinkingSchema = Type.Optional(
-	StringEnum(THINKING_LEVEL_VALUES, {
-		description:
-			"Optional reasoning strength for this task; omit to keep the agent's own level",
-	}),
-);
-
 const WaitSchema = Type.Optional(
 	Type.Boolean({
 		description:
@@ -79,7 +72,6 @@ const TaskItem = Type.Object({
 	}),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process" })),
 	isolation: IsolationSchema,
-	thinking: ThinkingSchema,
 });
 
 const SubagentParams = Type.Object({
@@ -90,14 +82,13 @@ const SubagentParams = Type.Object({
 	tasks: Type.Optional(Type.Array(TaskItem, { description: "Array of {agent, task} for parallel execution" })),
 	cwd: Type.Optional(Type.String({ description: "Working directory for the agent process (single mode)" })),
 	isolation: IsolationSchema,
-	thinking: ThinkingSchema,
 	wait: WaitSchema,
 });
 
 /** Roles that default to worktree isolation in parallel dispatches even when
  * the live catalog cannot be consulted (render-only call sites). Custom
  * write-capable agents join them via isWriteCapableAgent on the execute path. */
-const WORKTREE_DEFAULT_AGENTS = new Set(["executor"]);
+const WORKTREE_DEFAULT_AGENTS = new Set(["artisan", "steward"]);
 
 /** Resolve the default isolation for a dispatch. Precedence: an explicit
  * per-call request, then the role's own frontmatter declaration (`worktree`
@@ -390,7 +381,7 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 			"A configured child-model failure continues the retained session on the current main model.",
 		].join(" "),
 		promptSnippet:
-			"Dispatch isolated background agents for recon, implementation, cleanup, docs sync, or result merging; never blocks your turn, and completions wake you automatically.",
+			"Dispatch isolated background agents for recon or implementation, and for cleanup, docs sync, or result merging only when that work exists; never blocks your turn, and completions wake you automatically.",
 		parameters: SubagentParams,
 
 		async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -481,7 +472,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 							catalogAgent ? isWriteCapableAgent(catalogAgent) : undefined,
 							catalogAgent?.isolation,
 						),
-						{ thinking: item.thinking as ThinkingLevel | undefined },
 					));
 				}
 				const startedRuns = results.filter((result) => result.exitCode === -1);
@@ -544,7 +534,6 @@ export function registerSubagentTool(pi: ExtensionAPI, runtime: SubagentRuntime)
 					singleCatalogAgent ? isWriteCapableAgent(singleCatalogAgent) : undefined,
 					singleCatalogAgent?.isolation,
 				),
-				{ thinking: params.thinking as ThinkingLevel | undefined },
 			);
 			if (result.exitCode !== -1) {
 				throw new Error(getResultOutput(result));

package/src/index.ts

@@ -72,7 +72,7 @@ export default function (pi: ExtensionAPI): void {
 	registerLookupTools(pi, runtime);
 
 	pi.registerCommand("subagents-setup", {
-		description: "Configure pi-subagents: agents, selected models, capability-aware thinking, and runtime settings",
+		description: "Configure pi-subagents: agents, models, and per-role thinking",
 		handler: async (_args, ctx) => {
 			await runSetup(ctx, configPath);
 		},

package/src/monitor.ts

@@ -52,7 +52,7 @@ export interface RunView {
 	model?: string;
 	/** Selected model ref when the run handed off to current main. */
 	modelFallbackFrom?: string;
-	/** Effective thinking strength this run was launched with (frontmatter/config/global). */
+	/** Effective thinking strength this run was launched with (setup override or role default). */
 	thinking?: string;
 	isolation?: IsolationMode;
 	integrationStatus?: RunIntegrationStatus;
@@ -187,7 +187,7 @@ function tailGraphemes(segments: string[], maxWidth: number): string {
  * One-line task preview, capped by `maxWidth` display columns (default 80).
  * `keysOnly` (default): extracted key fragments (paths, quoted phrases,
  * symbols) are shown bare — the agent name is already displayed next to the
- * task line, so templated prose ("explorer: trace how ...") adds nothing.
+ * task line, so templated prose ("scout: trace how ...") adds nothing.
  * `keysOnly: false` keeps the prose as `head…tail` (used for completion
  * messages, where the Task line is the reader's only context).
  * Grapheme-safe — CJK, ZWJ emoji and combining sequences are never split.

package/src/prompt.ts

@@ -19,20 +19,26 @@ export function buildDelegationDirective(
 	if (agents.length === 0) return "";
 
 	const catalog = agents.map(formatCatalogEntry).join("\n");
-	const hasExplorer = agents.some((agent) => agent.name === "explorer");
-	const hasExecutor = agents.some((agent) => agent.name === "executor");
+	const hasScout = agents.some((agent) => agent.name === "scout");
+	const hasArtisan = agents.some((agent) => agent.name === "artisan");
+	const hasSteward = agents.some((agent) => agent.name === "steward");
 
 	const dispatchRules = [
-		`Delegate aggressively: child contexts are cheap, yours is scarce. A unit is delegable when it can proceed independently and return a compact result${hasExecutor ? "; when both hold, default it to `executor`" : ""}.`,
+		`Delegate aggressively: child contexts are cheap, yours is scarce. A unit is delegable when it can proceed independently and return a compact result${hasArtisan ? "; when the unit is a code change, default it to \`artisan\`" : ""}.`,
 		"Keep inline what fails either test — a lookup, a single focused edit, an answer already in context, or a single artifact you must absorb yourself (one issue, one spec), where delegation saves search, not that read. Cluster related questions into one brief instead of firing many small dispatches; a child loses context between runs.",
-		...(hasExplorer
+		...(hasScout
 			? [
-				"`explorer`: split a broad question into parallel explorers with disjoint scopes. Its findings are leads, never proof — re-read the cited line ranges before acting on them (a child you brief re-verifies).",
+				"`scout`: split a broad question into parallel scouts with disjoint scopes. Its findings are leads, never proof — re-read the cited line ranges before acting on them (a child you brief re-verifies).",
 			]
 			: []),
-		...(hasExecutor
+		...(hasArtisan
 			? [
-				"`executor`: brief it as the edit authorization. For cleanup, name the scope (uncommitted diff, Git range, directory) — every safe proven cut applies without per-item approval; finding no safe cut is a valid result. After a wide fan-out, pass the result-artifact paths to one executor and read its merged brief instead of every result yourself.",
+				"`artisan`: brief it as the edit authorization for implement, fix, refactor, or test. Not cleanup, docs sync, or merging results.",
+			]
+			: []),
+		...(hasSteward
+			? [
+				"`steward`: dispatch only when the work is cleanup, documentation sync, or merging named result artifacts — do not invent a tidy pass. For cleanup, name the scope (uncommitted diff, Git range, directory). After a wide fan-out, pass the result-artifact paths to one steward and read its brief instead of every result yourself.",
 			]
 			: []),
 		"A discovered defect is not a change: re-read the current code and confirm it is not a false positive before you edit or brief a writer to edit.",