oira666_pi-subagent 0.3.7 → 0.3.9

package/README.md

@@ -56,13 +56,35 @@ Multiple tasks run in parallel:
 
 Each task supports `agent` (the agent *type* to spawn) and `task`.
 
+## Tool Prompt Overrides
+
+The complete LLM-facing description of each extension tool can be replaced in
+`pi-subagents.json`. Supported locations, from lowest to highest priority:
+
+1. `~/.pi/pi-subagents.json`
+2. `$PI_CODING_AGENT_DIR/pi-subagents.json` (normally `~/.pi/agent/pi-subagents.json`)
+3. The nearest trusted project `.pi/pi-subagents.json`, walking up from the current directory
+
+Project values override global values per tool. Missing prompts keep their
+built-in defaults. Use a JSON object for `tool-prompts`:
+
+```json
+{
+  "tool-prompts": {
+    "subagents": "Your complete replacement prompt for the subagents tool.",
+    "resume_subagents": "Your complete replacement prompt for the resume tool."
+  }
+}
+```
+
 ## Bundled Agents
 
-Three fallback agents ship with the extension (used when no user/project agents are configured):
+Four built-in agents ship with the extension and remain available alongside custom agents by default:
 
 - `code-writer` — implementation and refactoring
 - `code-reviwer` — code review and risk finding
 - `code-architect` — technical design and approach selection
+- `team-lead` — decomposition and delegated multi-agent implementation
 
 ## Defining Agents
 
@@ -72,8 +94,10 @@ Create Markdown files with YAML frontmatter:
 - **Env agents:** `$PI_CODING_AGENT_DIR/agents/*.md` *(when `PI_CODING_AGENT_DIR` is set)*
 - **Project agents:** `.pi/agents/*.md` *(may prompt for confirmation — see `PI_SUBAGENT_CONFIRM_PROJECT_AGENTS`)*
 
-Agent discovery priority (highest wins on name collision): project > env > user.
-Built-in agents are only used as a fallback when **all three** locations are empty.
+Agent discovery priority (highest wins on name collision): project > env/user > built-in.
+Built-in agents remain available alongside custom agents unless
+`PI_SUBAGENT_HIDE_BUILTIN_AGENTS=true`. A custom definition with the same name
+as a built-in agent overrides that built-in definition.
 
 ```markdown
 ---
@@ -213,7 +237,8 @@ subagent *instance* by its unique name.
 
 | Env Var                 | Description                                                  |
 | ----------------------- | ------------------------------------------------------------ |
-| `PI_CODING_AGENT_DIR`   | Base path for an additional agents directory (`$PI_CODING_AGENT_DIR/agents/*.md`). Agents here override user agents but are overridden by project agents. Built-in agents are only used when user, env, and project locations all yield zero agents. |
+| `PI_CODING_AGENT_DIR`   | Override Pi's agent config directory. Agents are read from `$PI_CODING_AGENT_DIR/agents/*.md`, and tool prompts from `$PI_CODING_AGENT_DIR/pi-subagents.json`. |
+| `PI_SUBAGENT_HIDE_BUILTIN_AGENTS` | Set to `true`/`on`/`yes`/`1` to hide all bundled agents. By default they are available alongside custom agents. |
 
 ## CLI Argument Proxying
 

package/agents.ts

@@ -7,7 +7,7 @@
  * Lookup locations:
  *   - User agents:    ~/.pi/agent/agents/*.md  (or $PI_CODING_AGENT_DIR/agents/ when env var is set)
  *   - Project agents: .pi/agents/*.md  (walks up from cwd)
- *   - Bundled agents: ./agents/*.md    (fallback only when no user/project agents exist)
+ *   - Bundled agents: ./agents/*.md    (included unless PI_SUBAGENT_HIDE_BUILTIN_AGENTS is true)
  */
 
 import { getAgentDir, parseFrontmatter } from "@mariozechner/pi-coding-agent";
@@ -18,6 +18,8 @@ import { fileURLToPath } from "node:url";
 export type AgentScope = "user" | "project" | "both";
 export type AgentSource = "user" | "project" | "builtin";
 
+export const SUBAGENT_HIDE_BUILTIN_AGENTS_ENV = "PI_SUBAGENT_HIDE_BUILTIN_AGENTS";
+
 export interface AgentConfig {
 	name: string;
 	description: string;
@@ -167,19 +169,22 @@ function loadAgentsFromDir(dir: string, source: AgentSource): AgentConfig[] {
 }
 
 /**
- * Merge agents with last-write-wins deduplication by name.
- * Priority (lowest → highest): user < project.
+ * Merge agent layers with last-write-wins deduplication by name.
+ * Layers must be passed from lowest to highest priority.
  */
-function dedupeAgents(
-	userAgents: AgentConfig[],
-	projectAgents: AgentConfig[],
-): AgentConfig[] {
+function dedupeAgents(...layers: AgentConfig[][]): AgentConfig[] {
 	const agentMap = new Map<string, AgentConfig>();
-	for (const agent of userAgents) agentMap.set(agent.name, agent);
-	for (const agent of projectAgents) agentMap.set(agent.name, agent);
+	for (const agents of layers) {
+		for (const agent of agents) agentMap.set(agent.name, agent);
+	}
 	return Array.from(agentMap.values());
 }
 
+function hideBuiltinAgents(): boolean {
+	const value = process.env[SUBAGENT_HIDE_BUILTIN_AGENTS_ENV]?.trim().toLowerCase();
+	return value === "1" || value === "true" || value === "yes" || value === "on";
+}
+
 // ---------------------------------------------------------------------------
 // Public API
 // ---------------------------------------------------------------------------
@@ -198,25 +203,19 @@ export function isAgentEnabledAtLayer(
 /**
  * Discover all available agents according to the requested scope.
  *
- * When scope is "both", project agents override user agents with the same name.
- * If no user or project agents exist at all, bundled fallback agents are returned.
+ * Built-in agents are included at the lowest priority unless
+ * PI_SUBAGENT_HIDE_BUILTIN_AGENTS is true. Custom agents with the same name
+ * override their built-in counterpart.
  */
 export function discoverAgents(cwd: string, scope: AgentScope): AgentDiscoveryResult {
 	const userDir = path.join(getAgentDir(), "agents");
 	const projectAgentsDir = findNearestProjectAgentsDir(cwd);
 
+	const builtinAgents = hideBuiltinAgents() ? [] : loadAgentsFromDir(BUNDLED_AGENTS_DIR, "builtin");
 	const userAgents = loadAgentsFromDir(userDir, "user");
 	const projectAgents = projectAgentsDir ? loadAgentsFromDir(projectAgentsDir, "project") : [];
 
-	const hasConfiguredAgents = userAgents.length > 0 || projectAgents.length > 0;
-	if (!hasConfiguredAgents) {
-		return {
-			agents: loadAgentsFromDir(BUNDLED_AGENTS_DIR, "builtin"),
-			projectAgentsDir,
-		};
-	}
-
-	if (scope === "user") return { agents: userAgents, projectAgentsDir };
-	if (scope === "project") return { agents: projectAgents, projectAgentsDir };
-	return { agents: dedupeAgents(userAgents, projectAgents), projectAgentsDir };
+	if (scope === "user") return { agents: dedupeAgents(builtinAgents, userAgents), projectAgentsDir };
+	if (scope === "project") return { agents: dedupeAgents(builtinAgents, projectAgents), projectAgentsDir };
+	return { agents: dedupeAgents(builtinAgents, userAgents, projectAgents), projectAgentsDir };
 }

package/config.ts

@@ -0,0 +1,81 @@
+import { getAgentDir } from "@mariozechner/pi-coding-agent";
+import * as fs from "node:fs";
+import * as os from "node:os";
+import * as path from "node:path";
+
+export const PI_SUBAGENTS_CONFIG_FILE = "pi-subagents.json";
+
+export interface PiSubagentsConfig {
+  toolPrompts: Record<string, string>;
+}
+
+function readToolPrompts(filePath: string): Record<string, string> {
+  if (!fs.existsSync(filePath)) return {};
+
+  try {
+    const parsed = JSON.parse(fs.readFileSync(filePath, "utf8")) as unknown;
+    if (!parsed || typeof parsed !== "object" || Array.isArray(parsed)) {
+      console.warn(`[pi-subagent] Ignoring invalid config "${filePath}". Expected a JSON object.`);
+      return {};
+    }
+
+    const toolPrompts = (parsed as Record<string, unknown>)["tool-prompts"];
+    if (toolPrompts === undefined) return {};
+    if (!toolPrompts || typeof toolPrompts !== "object" || Array.isArray(toolPrompts)) {
+      console.warn(`[pi-subagent] Ignoring invalid tool-prompts in "${filePath}". Expected an object of tool-name to prompt strings.`);
+      return {};
+    }
+
+    const result: Record<string, string> = {};
+    for (const [toolName, prompt] of Object.entries(toolPrompts)) {
+      if (typeof prompt === "string" && prompt.trim().length > 0) {
+        result[toolName] = prompt;
+      } else {
+        console.warn(`[pi-subagent] Ignoring invalid prompt for tool "${toolName}" in "${filePath}". Expected a non-empty string.`);
+      }
+    }
+    return result;
+  } catch (err) {
+    const message = err instanceof Error ? err.message : String(err);
+    console.warn(`[pi-subagent] Failed to read config "${filePath}": ${message}`);
+    return {};
+  }
+}
+
+/** Find the nearest project-local .pi/pi-subagents.json while walking up from cwd. */
+export function findProjectConfig(cwd: string): string | null {
+  let dir = path.resolve(cwd);
+  while (true) {
+    const candidate = path.join(dir, ".pi", PI_SUBAGENTS_CONFIG_FILE);
+    if (fs.existsSync(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) return null;
+    dir = parent;
+  }
+}
+
+/**
+ * Load tool prompt overrides from lowest to highest priority:
+ *   ~/.pi/pi-subagents.json
+ *   $PI_CODING_AGENT_DIR/pi-subagents.json (normally ~/.pi/agent/pi-subagents.json)
+ *   nearest project .pi/pi-subagents.json (trusted projects only)
+ */
+export function loadPiSubagentsConfig(
+  cwd?: string,
+  includeProject = false,
+): PiSubagentsConfig {
+  const paths = [
+    path.join(os.homedir(), ".pi", PI_SUBAGENTS_CONFIG_FILE),
+    path.join(getAgentDir(), PI_SUBAGENTS_CONFIG_FILE),
+  ];
+  if (cwd && includeProject) {
+    const projectConfig = findProjectConfig(cwd);
+    if (projectConfig) paths.push(projectConfig);
+  }
+
+  const toolPrompts: Record<string, string> = {};
+  for (const filePath of new Set(paths)) {
+    Object.assign(toolPrompts, readToolPrompts(filePath));
+  }
+  return { toolPrompts };
+}

package/index.ts

@@ -19,6 +19,7 @@ import {
 } from "@mariozechner/pi-ai";
 import { Type } from "@sinclair/typebox";
 import { type AgentConfig, discoverAgents, isAgentEnabledAtLayer } from "./agents.js";
+import { loadPiSubagentsConfig } from "./config.js";
 import {
   allocateSubagentNames,
   clearResumeActive,
@@ -114,22 +115,21 @@ const BASE_SUBAGENTS_TOOL_DESCRIPTION = [
   'Parallel: { tasks: [{ agent: "writer", task: "..." }, { agent: "tester", task: "..." }] }',
 ].join("\n");
 
-const GPT_56_SUBAGENT_GUIDANCE =
+const SUBAGENT_USAGE_GUIDANCE =
   "Be careful with subagents: use them when the user explicitly asks or when they are truly necessary, because they are expensive. Good cases: running several exploration tasks in parallel, solving several tasks in parallel, or delegating several large tasks to separate subagents. Bad cases (don't do this): creating many nested subagents with similar tasks, using sequential subagents for simple short tasks, running a subagent just to read a file or execute a bash command, or delegating work that does not need a team or parallel execution (unless the user asked you to).";
 
-export function isGpt56Model(model: unknown): boolean {
-  if (typeof model === "string") return model.toLowerCase().includes("gpt-5.6");
-  if (!model || typeof model !== "object") return false;
-  const candidate = model as { id?: unknown; name?: unknown };
-  return [candidate.id, candidate.name].some(
-    (value) => typeof value === "string" && value.toLowerCase().includes("gpt-5.6"),
-  );
+export function getSubagentsToolDescription(): string {
+  return `${BASE_SUBAGENTS_TOOL_DESCRIPTION}\n\n${SUBAGENT_USAGE_GUIDANCE}`;
 }
 
-export function getSubagentsToolDescription(model?: unknown): string {
-  return isGpt56Model(model)
-    ? `${BASE_SUBAGENTS_TOOL_DESCRIPTION}\n\n${GPT_56_SUBAGENT_GUIDANCE}`
-    : BASE_SUBAGENTS_TOOL_DESCRIPTION;
+function sameToolPrompts(
+  left: Record<string, string>,
+  right: Record<string, string>,
+): boolean {
+  const leftKeys = Object.keys(left);
+  const rightKeys = Object.keys(right);
+  return leftKeys.length === rightKeys.length &&
+    leftKeys.every((key) => left[key] === right[key]);
 }
 
 type ProjectAgentConfirmationSetting = "ask" | "never" | "session";
@@ -705,6 +705,8 @@ export function selectParentModelForSubagent(
 // ---------------------------------------------------------------------------
 
 export default function (pi: ExtensionAPI) {
+  let configuredToolPrompts = loadPiSubagentsConfig().toolPrompts;
+  let refreshRegisteredToolPrompts: ((cwd: string, includeProject: boolean) => void) | undefined;
   let resumeModelRegistry: any | undefined;
   let lastRestorableModel: any | undefined;
   let latestSessionCtx: any | undefined;
@@ -1395,6 +1397,9 @@ export default function (pi: ExtensionAPI) {
     lifecycleGeneration += 1;
     sessionActive = true;
     latestSessionCtx = ctx;
+    const includeProjectConfig =
+      typeof ctx.isProjectTrusted === "function" && ctx.isProjectTrusted() === true;
+    refreshRegisteredToolPrompts?.(ctx.cwd, includeProjectConfig);
     resumeModelRegistry = ctx.modelRegistry;
     clearSyntheticResumeState();
     pendingResumePlans = [];
@@ -1707,16 +1712,7 @@ export default function (pi: ExtensionAPI) {
       const agentList = discoveredAgents
         .map((a) => `- **${a.name}**: ${a.description}`)
         .join("\n");
-      return {
-        systemPrompt:
-          event.systemPrompt +
-          `\n\n## Available Subagents
-
-The following subagents are available via the \`subagents\` tool:
-
-${agentList}
-
-### How to call the subagents tool
+      const subagentsGuidance = configuredToolPrompts[SUBAGENT_TOOL_NAME] ?? `### How to call the subagents tool
 
 Each subagent runs in an **isolated process**.
 
@@ -1738,9 +1734,10 @@ calls one after another. Do NOT put dependent tasks in the same array.
 \`\`\`
 
 - Max depth: current depth ${currentDepth}, max depth ${maxDepth}
-- Max subagents per tool call: ${maxParallelTasks}
-${resumableSubagentsDisabled() ? "" : `
-### Resumable subagents
+- Max subagents per tool call: ${maxParallelTasks}`;
+      const resumeGuidance = resumableSubagentsDisabled()
+        ? ""
+        : configuredToolPrompts[RESUME_SUBAGENTS_TOOL_NAME] ?? `### Resumable subagents
 
 Every subagent run is assigned a unique, durable name (e.g. \`code-writer-01\`,
 \`code-reviewer-02\`) which is returned together with its results. Use the
@@ -1756,8 +1753,13 @@ keeping their full previous context:
 - All resumes in one call run in parallel.
 - You may include subagent names in the task text you give YOUR OWN subagents,
   so they can resume those subagents themselves.
-- Names survive restarts; you can resume them in a later session of this conversation.
-`}`,
+- Names survive restarts; you can resume them in a later session of this conversation.`;
+      return {
+        systemPrompt: `${event.systemPrompt}\n\n## Available Subagents
+
+The following subagents are available via the \`subagents\` tool:
+
+${agentList}\n\n${subagentsGuidance}${resumeGuidance ? `\n\n${resumeGuidance}` : ""}`,
       };
     } catch (err) {
       console.error("[pi-subagent] Error in before_agent_start:", err);
@@ -1766,13 +1768,11 @@ keeping their full previous context:
 
   // Register the subagents tool
   if (canDelegate) {
-    let registeredForGpt56 = false;
-    const registerSubagentsTool = (model?: unknown) => {
-      registeredForGpt56 = isGpt56Model(model);
+    const registerSubagentsTool = () => {
       pi.registerTool({
       name: SUBAGENT_TOOL_NAME,
       label: "Subagents",
-      description: getSubagentsToolDescription(model),
+      description: configuredToolPrompts[SUBAGENT_TOOL_NAME] ?? getSubagentsToolDescription(),
       parameters: SubagentParams,
 
       async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -1989,22 +1989,12 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
       });
     };
 
-    registerSubagentsTool(latestSessionCtx?.model);
-    pi.on("model_select", (event) => {
-      if (registeredForGpt56 !== isGpt56Model(event.model)) {
-        registerSubagentsTool(event.model);
-      }
-    });
-    pi.on("before_agent_start", (_event, ctx) => {
-      if (registeredForGpt56 !== isGpt56Model(ctx.model)) {
-        registerSubagentsTool(ctx.model);
-      }
-    });
-
-    if (!resumableSubagentsDisabled()) pi.registerTool({
+    const registerResumeSubagentsTool = () => {
+      if (resumableSubagentsDisabled()) return;
+      pi.registerTool({
       name: RESUME_SUBAGENTS_TOOL_NAME,
       label: "Resume subagents",
-      description: [
+      description: configuredToolPrompts[RESUME_SUBAGENTS_TOOL_NAME] ?? [
         "Resume previously run subagents by name with a new task, keeping their full context.",
         "",
         "Every subagent run returns a unique name (e.g. code-writer-01). Pass those names",
@@ -2207,7 +2197,24 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
       renderCall: (args, theme, context) => renderResumeCall(args, theme, context),
       renderResult: (result, { expanded }, theme) =>
         renderResult(result, expanded, theme),
-    });
+      });
+    };
+
+    const registerToolsWithConfig = (
+      cwd?: string,
+      includeProject = false,
+      force = false,
+    ) => {
+      const nextToolPrompts = loadPiSubagentsConfig(cwd, includeProject).toolPrompts;
+      if (!force && sameToolPrompts(configuredToolPrompts, nextToolPrompts)) return;
+      configuredToolPrompts = nextToolPrompts;
+      registerSubagentsTool();
+      registerResumeSubagentsTool();
+    };
+    refreshRegisteredToolPrompts = (cwd, includeProject) => {
+      registerToolsWithConfig(cwd, includeProject);
+    };
+    registerToolsWithConfig(undefined, false, true);
   }
 
   function getSessionDirForTask(toolCallId: string, index: number): string {

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "oira666_pi-subagent",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Subagent extension for Pi coding agent. Delegate tasks to specialized agents.",
   "type": "module",
   "main": "index.ts",
   "files": [
     "index.ts",
     "agents.ts",
+    "config.ts",
     "runner.ts",
     "resume.ts",
     "names.ts",