oira666_pi-subagent 0.3.6 → 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,15 +94,18 @@ 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
 ---
 name: writer
 description: Expert technical writer
-model: anthropic/claude-3-5-sonnet
 thinking: low
+first-layer: enabled
+last-layer: disabled
 tools: read,write
 ---
 
@@ -93,9 +118,11 @@ You are an expert technical writer focused on clarity and conciseness.
 | ------------- | -------- | -------------------- | -------------------------------------------------------- |
 | `name`        | Yes      | —                    | Agent identifier used in tool calls                      |
 | `description` | Yes      | —                    | What the agent does (shown to the main agent)            |
-| `model`       | No       | Pi default           | Override model, e.g. `anthropic/claude-3-5-sonnet`       |
+| `model`       | No       | Current parent model | Legacy fallback only when live parent model context is unavailable |
 | `thinking`    | No       | Pi default           | `off`, `minimal`, `low`, `medium`, `high`, `xhigh`       |
 | `tools`       | No       | `read,bash,edit,write` | Comma-separated built-in tools                         |
+| `first-layer` | No       | `enabled`            | Set to `disabled` to hide/block this agent at depth 1    |
+| `last-layer`  | No       | `enabled`            | Set to `disabled` to hide/block this agent at max depth  |
 
 Available tools: `read`, `bash`, `edit`, `write`.
 
@@ -103,7 +130,7 @@ The Markdown body becomes the agent's system prompt (appended to Pi's default, n
 
 ## Delegation Guards
 
-Depth and cycle guards prevent runaway recursive delegation.
+Depth and cycle guards prevent runaway recursive delegation. Layer availability is evaluated for the child being launched: depth 1 is the first layer, and `PI_SUBAGENT_MAX_DEPTH` is the last layer. The bundled `team-lead` agent sets `last-layer: disabled` so it cannot consume the final delegation layer.
 
 | Config                         | Default | Description                                      |
 | ------------------------------ | ------- | ------------------------------------------------ |
@@ -210,13 +237,13 @@ 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
 
 Flags passed to the parent `pi` process are forwarded to subagent child
-processes, so they inherit the same provider, API key, model, and other runtime settings. Flags the
-extension manages itself are blocked from being forwarded.
+processes, so they inherit the same provider, API key, and other runtime settings. At every new launch, the extension explicitly passes the parent's currently active model; changing `/model` mid-conversation therefore affects all subsequently started subagents. Flags the extension manages itself are blocked from being forwarded.
 
 **Always forwarded verbatim:**
 
@@ -237,7 +264,7 @@ extension manages itself are blocked from being forwarded.
 
 | Flag | Overridden by |
 | --- | --- |
-| `--model` | `model:` in agent frontmatter |
+| `--model` | Replaced at launch by the parent's currently active model (`model:` is only a no-context compatibility fallback) |
 | `--thinking` | `thinking:` in agent frontmatter |
 | `--tools` / `--no-tools` | `tools:` in agent frontmatter |
 

package/agents/team-lead.md

@@ -1,6 +1,7 @@
 ---
 name: team-lead
 description: "A team of agents with different specializations that can take any complex task, split it into parts, and implement architecture, generation, review, or any other kind of task."
+last-layer: disabled
 ---
 
 You are an experienced team lead, focused on tasks management. You don't do any work yourself. You delegate.

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,12 +18,18 @@ 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;
 	tools?: string[];
 	model?: string;
 	thinking?: string;
+	/** Whether this agent may be launched at delegation depth 1 (default: true). */
+	firstLayer?: boolean;
+	/** Whether this agent may be launched at the maximum delegation depth (default: true). */
+	lastLayer?: boolean;
 	systemPrompt: string;
 	source: AgentSource;
 	filePath: string;
@@ -63,8 +69,25 @@ function findNearestProjectAgentsDir(cwd: string): string | null {
 	}
 }
 
+function parseLayerSetting(
+	value: unknown,
+	field: "first-layer" | "last-layer",
+	filePath: string,
+): boolean {
+	if (value === undefined) return true;
+	if (typeof value === "string") {
+		const normalized = value.trim().toLowerCase();
+		if (normalized === "enabled") return true;
+		if (normalized === "disabled") return false;
+	}
+	console.warn(
+		`[pi-subagent] Ignoring invalid ${field} field in "${filePath}". Expected enabled or disabled.`,
+	);
+	return true;
+}
+
 /** Parse a single agent markdown file into an AgentConfig. Returns null on skip. */
-function parseAgentFile(filePath: string, source: AgentSource): AgentConfig | null {
+export function parseAgentFile(filePath: string, source: AgentSource): AgentConfig | null {
 	let content: string;
 	try {
 		content = fs.readFileSync(filePath, "utf-8");
@@ -113,6 +136,8 @@ function parseAgentFile(filePath: string, source: AgentSource): AgentConfig | nu
 		tools,
 		model: typeof frontmatter.model === "string" ? frontmatter.model : undefined,
 		thinking: typeof frontmatter.thinking === "string" ? frontmatter.thinking : undefined,
+		firstLayer: parseLayerSetting(frontmatter["first-layer"], "first-layer", filePath),
+		lastLayer: parseLayerSetting(frontmatter["last-layer"], "last-layer", filePath),
 		systemPrompt: body,
 		source,
 		filePath,
@@ -144,45 +169,53 @@ 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
 // ---------------------------------------------------------------------------
 
+/** Whether an agent is available to be launched at the requested child depth. */
+export function isAgentEnabledAtLayer(
+	agent: AgentConfig,
+	targetDepth: number,
+	maxDepth: number,
+): boolean {
+	if (targetDepth === 1 && agent.firstLayer === false) return false;
+	if (targetDepth === maxDepth && agent.lastLayer === false) return false;
+	return true;
+}
+
 /**
  * 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

@@ -18,7 +18,8 @@ import {
   lazyStream,
 } from "@mariozechner/pi-ai";
 import { Type } from "@sinclair/typebox";
-import { type AgentConfig, discoverAgents } from "./agents.js";
+import { type AgentConfig, discoverAgents, isAgentEnabledAtLayer } from "./agents.js";
+import { loadPiSubagentsConfig } from "./config.js";
 import {
   allocateSubagentNames,
   clearResumeActive,
@@ -100,6 +101,37 @@ const SUBAGENT_STACK_ENV = "PI_SUBAGENT_STACK";
 const SUBAGENT_PREVENT_CYCLES_ENV = "PI_SUBAGENT_PREVENT_CYCLES";
 const SUBAGENT_CONFIRM_PROJECT_AGENTS_ENV = "PI_SUBAGENT_CONFIRM_PROJECT_AGENTS";
 
+const BASE_SUBAGENTS_TOOL_DESCRIPTION = [
+  "Delegate work to specialized subagents running as isolated pi processes.",
+  "",
+  "Pass a `tasks` array. Every task in the same call runs IN PARALLEL.",
+  "  - 1 task  -> single delegation",
+  "  - N tasks -> all N run concurrently in one call",
+  "",
+  "For sequential work (task B depends on task A's output), make separate",
+  "tool calls one after another. Do NOT put dependent tasks in the same array.",
+  "",
+  'Single:   { tasks: [{ agent: "writer", task: "Rewrite README.md" }] }',
+  'Parallel: { tasks: [{ agent: "writer", task: "..." }, { agent: "tester", task: "..." }] }',
+].join("\n");
+
+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 getSubagentsToolDescription(): string {
+  return `${BASE_SUBAGENTS_TOOL_DESCRIPTION}\n\n${SUBAGENT_USAGE_GUIDANCE}`;
+}
+
+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";
 type ProjectAgentApproval = "once" | "session" | "no";
 
@@ -387,6 +419,15 @@ function makeDetailsFactory(
   };
 }
 
+function filterAgentsForCurrentLayer(
+  agents: AgentConfig[],
+  currentDepth: number,
+  maxDepth: number,
+): AgentConfig[] {
+  const targetDepth = currentDepth + 1;
+  return agents.filter((agent) => isAgentEnabledAtLayer(agent, targetDepth, maxDepth));
+}
+
 function formatAgentNames(agents: AgentConfig[]): string {
   return agents.map((a) => `${a.name} (${a.source})`).join(", ") || "none";
 }
@@ -640,11 +681,32 @@ function getRestorableModel(ctx: any): any | undefined {
   return findLastNonResumeModel(ctx) ?? getEnvFallbackModel(ctx);
 }
 
+/**
+ * Pick the parent model inherited by a subagent launch.
+ *
+ * A normal tool call was emitted by the current model, so that model is the
+ * authoritative choice. Looking backward in the session is only appropriate
+ * while our own synthetic resume model is active (or no current model exists).
+ */
+export function selectParentModelForSubagent(
+  currentModel: any | undefined,
+  modelBeforeSynthetic: any | undefined,
+  historicalRealModel: any | undefined,
+  lastRestorableModel: any | undefined,
+): any | undefined {
+  if (currentModel?.provider && currentModel.provider !== RESUME_PROVIDER) {
+    return currentModel;
+  }
+  return modelBeforeSynthetic ?? historicalRealModel ?? lastRestorableModel;
+}
+
 // ---------------------------------------------------------------------------
 // Extension entry point
 // ---------------------------------------------------------------------------
 
 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;
@@ -664,6 +726,21 @@ export default function (pi: ExtensionAPI) {
     resumeState.trigger = "resumePrompt";
   }
 
+  function getParentModelForSubagent(ctx: any): any | undefined {
+    const currentModel = ctx?.model;
+    // Avoid historical lookup during normal calls: the current assistant
+    // response is the one that emitted the subagents tool call.
+    if (currentModel?.provider && currentModel.provider !== RESUME_PROVIDER) {
+      return currentModel;
+    }
+    return selectParentModelForSubagent(
+      currentModel,
+      modelToRestoreAfterResume,
+      findLastNonResumeModel(ctx) ?? getEnvFallbackModel(ctx),
+      lastRestorableModel,
+    );
+  }
+
   function scheduleSessionTask(callback: () => void, delayMs: number): void {
     const expectedGeneration = lifecycleGeneration;
     const timer = setTimeout(() => {
@@ -1320,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 = [];
@@ -1342,7 +1422,7 @@ export default function (pi: ExtensionAPI) {
       if (!canDelegate) return;
 
       const discovery = discoverAgents(ctx.cwd, "both");
-      discoveredAgents = discovery.agents;
+      discoveredAgents = filterAgentsForCurrentLayer(discovery.agents, currentDepth, maxDepth);
       currentSessionId = ctx.sessionManager.getSessionId?.() ?? "ephemeral";
       currentSubagentSessionRoot = getDefaultSubagentSessionRoot(ctx);
       if (resumableSubagentsDisabled()) {
@@ -1632,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**.
 
@@ -1663,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
@@ -1681,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);
@@ -1691,22 +1768,11 @@ keeping their full previous context:
 
   // Register the subagents tool
   if (canDelegate) {
-    pi.registerTool({
+    const registerSubagentsTool = () => {
+      pi.registerTool({
       name: SUBAGENT_TOOL_NAME,
       label: "Subagents",
-      description: [
-        "Delegate work to specialized subagents running as isolated pi processes.",
-        "",
-        "Pass a `tasks` array. Every task in the same call runs IN PARALLEL.",
-        "  - 1 task  -> single delegation",
-        "  - N tasks -> all N run concurrently in one call",
-        "",
-        "For sequential work (task B depends on task A's output), make separate",
-        "tool calls one after another. Do NOT put dependent tasks in the same array.",
-        "",
-        'Single:   { tasks: [{ agent: "writer", task: "Rewrite README.md" }] }',
-        'Parallel: { tasks: [{ agent: "writer", task: "..." }, { agent: "tester", task: "..." }] }',
-      ].join("\n"),
+      description: configuredToolPrompts[SUBAGENT_TOOL_NAME] ?? getSubagentsToolDescription(),
       parameters: SubagentParams,
 
       async execute(toolCallId, params, signal, onUpdate, ctx) {
@@ -1714,7 +1780,7 @@ keeping their full previous context:
           recordToolCallStart(toolCallId);
           updateLatestBroadcastTargets(undefined);
           const discovery = discoverAgents(ctx.cwd, "both");
-          const { agents } = discovery;
+          const agents = filterAgentsForCurrentLayer(discovery.agents, currentDepth, maxDepth);
 
           const makeDetails = makeDetailsFactory(
             discovery.projectAgentsDir,
@@ -1852,7 +1918,8 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
                     return {
                       agent: task.agent,
                       task: task.task,
-                      model: agentConfig?.model,
+                      model:
+                        formatModelFlag(getParentModelForSubagent(ctx)) ?? agentConfig?.model,
                       tools: agentConfig?.tools,
                       sessionDir:
                         resumePlan?.details?.results[index]?.sessionDir ??
@@ -1882,11 +1949,9 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
               resumePlan?.details?.results[0],
               getSessionDirForTask(resumePlan?.previousToolCallId ?? toolCallId, 0),
               !!resumePlan,
-              // Prefer the pre-resume model (during resume) or the current
-              // active model (normal runs). This prevents children from
-              // defaulting to whatever settings.json says at spawn time, which
-              // can change while the parent session is long-running.
-              formatModelFlag(modelToRestoreAfterResume ?? ctx.model ?? lastRestorableModel),
+              // Normal calls inherit the model that emitted this tool call;
+              // synthetic resume calls recover the preceding real model.
+              formatModelFlag(getParentModelForSubagent(ctx)),
               topLevelBaseId,
               names[0],
             );
@@ -1902,7 +1967,7 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
             resumePlan?.details?.results,
             (index) => getSessionDirForTask(resumePlan?.previousToolCallId ?? toolCallId, index),
             !!resumePlan,
-            formatModelFlag(modelToRestoreAfterResume ?? ctx.model ?? lastRestorableModel),
+            formatModelFlag(getParentModelForSubagent(ctx)),
             topLevelBaseId,
             { names },
           );
@@ -1921,12 +1986,15 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
       renderCall: (args, theme, context) => renderCall(args, theme, context),
       renderResult: (result, { expanded }, theme) =>
         renderResult(result, expanded, theme),
-    });
+      });
+    };
 
-    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",
@@ -2102,7 +2170,7 @@ This guard prevents self-recursion and cyclic handoffs (for example A -> B -> A)
               undefined,
               (index) => targets[index].sessionDir,
               true,
-              formatModelFlag(modelToRestoreAfterResume ?? ctx.model ?? lastRestorableModel),
+              formatModelFlag(getParentModelForSubagent(ctx)),
               topLevelBaseId,
               { names: targets.map((target) => target.name), rawPrompts: true },
             );
@@ -2129,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.6",
+  "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",

package/runner.ts

@@ -542,6 +542,12 @@ export function processJsonLine(line: string, result: SingleResult): boolean {
 // Build pi CLI arguments
 // ---------------------------------------------------------------------------
 
+export function resolveSubagentModel(agentModel?: string, currentParentModel?: string): string | undefined {
+  // The active parent model is authoritative. Agent frontmatter is retained as
+  // a compatibility fallback only for callers that cannot supply live context.
+  return currentParentModel ?? agentModel ?? process.env[SUBAGENT_FALLBACK_MODEL_ENV] ?? _inheritedCliArgs.fallbackModel;
+}
+
 function buildPiArgs(
   agent: AgentConfig,
   systemPromptPath: string | null,
@@ -561,8 +567,9 @@ function buildPiArgs(
   if (sessionDir) args.push("--session-dir", sessionDir);
   if (resumeSession) args.push("--continue");
 
-  // Agent config takes priority; fall back to parent CLI value
-  const model = agent.model ?? fallbackModelOverride ?? process.env[SUBAGENT_FALLBACK_MODEL_ENV] ?? _inheritedCliArgs.fallbackModel;
+  // Always use the model active in the parent at launch time. This matters
+  // when /model changed after the parent process originally started.
+  const model = resolveSubagentModel(agent.model, fallbackModelOverride);
   if (model) args.push("--model", model);
 
   const thinking = agent.thinking ?? _inheritedCliArgs.fallbackThinking;