oira666_pi-subagent 0.3.6 → 0.3.7

package/README.md

@@ -79,8 +79,9 @@ Built-in agents are only used as a fallback when **all three** locations are emp
 ---
 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 +94,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 +106,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                                      |
 | ------------------------------ | ------- | ------------------------------------------------ |
@@ -215,8 +218,7 @@ subagent *instance* by its unique name.
 ## 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 +239,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

@@ -24,6 +24,10 @@ export interface AgentConfig {
 	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 +67,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 +134,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,
@@ -161,6 +184,17 @@ function dedupeAgents(
 // 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.
  *

package/index.ts

@@ -18,7 +18,7 @@ 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 {
   allocateSubagentNames,
   clearResumeActive,
@@ -100,6 +100,38 @@ 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 GPT_56_SUBAGENT_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(model?: unknown): string {
+  return isGpt56Model(model)
+    ? `${BASE_SUBAGENTS_TOOL_DESCRIPTION}\n\n${GPT_56_SUBAGENT_GUIDANCE}`
+    : BASE_SUBAGENTS_TOOL_DESCRIPTION;
+}
+
 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,6 +681,25 @@ 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
 // ---------------------------------------------------------------------------
@@ -664,6 +724,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(() => {
@@ -1342,7 +1417,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()) {
@@ -1691,22 +1766,13 @@ keeping their full previous context:
 
   // Register the subagents tool
   if (canDelegate) {
-    pi.registerTool({
+    let registeredForGpt56 = false;
+    const registerSubagentsTool = (model?: unknown) => {
+      registeredForGpt56 = isGpt56Model(model);
+      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: getSubagentsToolDescription(model),
       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,6 +1986,19 @@ 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),
+      });
+    };
+
+    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({
@@ -2102,7 +2180,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 },
             );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oira666_pi-subagent",
-  "version": "0.3.6",
+  "version": "0.3.7",
   "description": "Subagent extension for Pi coding agent. Delegate tasks to specialized agents.",
   "type": "module",
   "main": "index.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;