@ferris1225/pi-subagents 4.2.0 → 4.2.2

package/README.md

@@ -53,7 +53,7 @@ directly when you want exact control.
 
 | Agent         | Access    | Best for                                                                                                                                                                                                   |
 | ------------- | --------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `explorer`    | Read-only | Broad search, unfamiliar-area mapping, symbol and dependency tracing. Returns a retrieval index — never proof.                                                                                              |
+| `explorer`    | Read-only | Broad search, unfamiliar-area mapping, symbol and dependency tracing. Returns a retrieval index — never proof. A single artifact the main agent must fully absorb (one issue, one spec) stays an inline read. |
 | `executor`    | Full      | The default route for any non-trivial, self-contained task: implementation, fixes, refactors, tests, evidence-first cleanup, docs/comment sync, or merging a fan-out's results into one brief — carried through verification and a result-only handoff. |
 
 Custom roles join them with a Markdown file (see [Custom agents](#custom-agents)).
@@ -262,7 +262,11 @@ strength per agent. Everything else is config-file only, stored at
 The delegation directive is always injected; there is no toggle. Invalid values
 fall back safely, and stale keys — including the former `proactiveInjection`,
 `maxConcurrency`, `maxFixRounds`, and `notifyOnReviewPass` knobs — are dropped
-automatically. At session
+automatically. Built-in roles a newer package no longer ships (such as the
+retired `worker`/`cleaner`/`documenter`/`synthesizer`/`reviewer` set) are pruned
+from `enabledAgents`, `knownAgents`, and the model/thinking tables at first
+load, so the setup wizard never mixes old and new roles; custom agents are
+untouched. At session
 start, model overrides pi no longer reports are removed with a one-time notice. If
 pi's own session compaction fails mid-thread, a notice surfaces the error and the
 automatic retry instead of failing quietly.

package/agents/explorer.md

@@ -12,7 +12,7 @@ You are an explorer agent: a fast, read-only reconnaissance specialist. You inve
 ## Hard constraints
 
 - You are READ-ONLY. Never create, edit, or delete files; never run mutating commands. Reach for your `read`/`grep`/`find`/`ls` tools before the shell — they behave the same on every platform, while the shell you were given may be POSIX or PowerShell. Keep shell use to read-only inspection (`git log/show/diff/status` and that shell's own read-only commands); no installs, builds, or state changes. Permissions are not perfectly enforceable — keep every command strictly read-only by intent.
-- Every finding is a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions. The caller must re-read load-bearing files before acting on your results.
+- Every finding is a retrieval lead, never sufficient proof for deletion, security claims, public/API compatibility, persistence, or other load-bearing decisions. The caller must re-read the cited line ranges before acting on your results.
 
 ## Workflow
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ferris1225/pi-subagents",
-  "version": "4.2.0",
+  "version": "4.2.2",
   "description": "A managed sub-agent team for pi: specialized roles, pre-commit documentation sync, retained threads, auto-fix chains, model fallback, and Git worktree isolation.",
   "type": "module",
   "license": "MIT",

package/src/config.ts

@@ -15,6 +15,13 @@ import { getAgentDir, withFileMutationQueue } from "@earendil-works/pi-coding-ag
 /** Full catalog of agents shipped with the package (selectable in /subagents-setup). */
 export const BUILTIN_AGENT_NAMES = ["explorer", "executor"] 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;
+
 /** Agents enabled out of the box on a fresh install. */
 export const DEFAULT_ENABLED_AGENTS: readonly string[] = [...BUILTIN_AGENT_NAMES];
 
@@ -183,6 +190,29 @@ function defaultConfig(): SubagentsConfig {
 	};
 }
 
+/**
+ * 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
+ * persistence in loadConfig writes the pruned shape back to disk.
+ */
+function pruneRemovedBuiltins(config: SubagentsConfig): SubagentsConfig {
+	const removed = new Set<string>(REMOVED_BUILTIN_AGENT_NAMES);
+	const filter = (names: readonly string[]): string[] => names.filter((name) => !removed.has(name));
+	const agentModels = { ...config.agentModels };
+	const agentThinkingLevels = { ...config.agentThinkingLevels };
+	for (const name of REMOVED_BUILTIN_AGENT_NAMES) {
+		delete agentModels[name];
+		delete agentThinkingLevels[name];
+	}
+	return {
+		...config,
+		enabledAgents: filter(config.enabledAgents),
+		knownAgents: filter(config.knownAgents),
+		agentModels,
+		agentThinkingLevels,
+	};
+}
+
 /**
  * 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
@@ -216,6 +246,7 @@ function adoptNewBuiltins(config: SubagentsConfig): SubagentsConfig {
  * 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.
  */
 export async function loadConfig(configPath: string = getConfigPath()): Promise<SubagentsConfig> {
 	let text: string;
@@ -233,7 +264,10 @@ export async function loadConfig(configPath: string = getConfigPath()): Promise<
 		return defaultConfig();
 	}
 
-	const config = adoptNewBuiltins(normalizeConfig(parsed));
+	// 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)));
 
 	// Schema upgrade: persist the normalized shape when the file gained fields
 	// (new version) or dropped invalid ones.

package/src/prompt.ts

@@ -24,9 +24,10 @@ export function buildDelegationDirective(
 
 	const dispatchRules = [
 		`Delegate aggressively: child contexts are cheap, yours is scarce. Inline only trivial work — a lookup, a single focused edit, an answer already in context${hasExecutor ? "; default every non-trivial delegated task (implementation, fix, refactor, test, cleanup, docs sync, result merging) to `executor`" : ""}.`,
+		"A single artifact you must fully absorb yourself (one issue, one spec) is inline work — delegation saves search, not that read.",
 		...(hasExplorer
 			? [
-				"`explorer`: split a broad question into parallel explorers with disjoint scopes. Its findings are leads, never proof — re-read load-bearing files before acting yourself (a child you brief re-verifies).",
+				"`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).",
 			]
 			: []),
 		...(hasExecutor
@@ -45,7 +46,7 @@ export function buildDelegationDirective(
 	];
 
 	const verificationRules = [
-		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures, and inspect actual changes before reporting completion.",
+		"Never report an unrun check as passed; surface unavailable checks and pre-existing failures, and inspect the actual diff before reporting completion.",
 		"Commit or push only when explicitly requested and applicable checks pass.",
 	];