oira666_pi-subagent 0.3.14 → 0.3.16

package/README.md

@@ -152,15 +152,33 @@ pi --no-subagent-prevent-cycles   # allow cycles (not recommended)
 | `PI_SUBAGENT_MAX_PARALLEL_TASKS` | `30`    | Max tasks per single call                |
 | `PI_SUBAGENT_MAX_CONCURRENCY`    | `8`     | Max subagents running simultaneously     |
 
+## Child Process Environment
+
+Children inherit all provider, authentication, proxy, home, temp, and Pi
+environment variables. The runner also repairs the executable search path for
+elevated Windows PowerShell and pnpm installations: it normalizes duplicate
+`Path`/`PATH` keys and adds the Node directory, `PNPM_HOME`, npm's user bin,
+`%LOCALAPPDATA%\\pnpm`, and `%SystemRoot%\\System32`. This also applies to every
+nested child, so tools and sub-subagents use the same working environment.
+
+Pi itself is relaunched with the current runtime and entrypoint
+(`process.execPath process.argv[1]`). The extension does not inspect npm/pnpm
+shims or assume package names, `node_modules` locations, or Pi `dist` layouts.
+This also supports Bun and other Node-compatible runtimes with the same process
+semantics. Embedded hosts without a script entrypoint can use
+`PI_SUBAGENT_PI_COMMAND` and `PI_SUBAGENT_PI_ARGS_PREFIX` explicitly.
+
 ## Subagent Liveness Timeouts
 
 A delegated process cannot block its parents forever. The runner applies a
-startup timeout before the first model turn and a semantic-inactivity timeout
-after startup. Tool/turn events and changed nested-agent state reset the idle
-timer; repeated unchanged progress heartbeats do not. On timeout or
-cancellation, the runner terminates the child process tree and bounds cleanup;
-even if a wedged OS process never reports `close`, the tool returns an error
-result so every waiting parent can settle.
+startup timeout before the first model turn and an agent-inactivity timeout
+after startup. The inactivity watchdog is paused while any tool call is in
+progress, so tool executions can run for unlimited time; a fresh full idle
+window starts after the last concurrent tool finishes. Agent/turn events and
+changed nested-agent state reset the idle timer; repeated unchanged progress
+heartbeats do not. On timeout or cancellation, the runner terminates the child
+process tree and bounds cleanup; even if a wedged OS process never reports
+`close`, the tool returns an error result so every waiting parent can settle.
 
 RPC completion is based on Pi's `agent_settled` event—not `agent_end`.
 `agent_end` is only a low-level run boundary and may be followed by Pi's normal
@@ -172,15 +190,16 @@ reported immediately as failures.
 | --- | --- | --- |
 | `PI_SUBAGENT_STARTUP_TIMEOUT` | `120000` | Milliseconds allowed to reach the first model turn; `0` disables |
 | `PI_SUBAGENT_STARTUP_RETRIES` | `2` | Fresh retries after a startup timeout |
-| `PI_SUBAGENT_IDLE_TIMEOUT` | `1200000` | Milliseconds without new semantic RPC activity after startup; `0` disables |
+| `PI_SUBAGENT_IDLE_TIMEOUT` | `1200000` | Milliseconds without agent activity after startup, excluding time spent in ongoing tool calls; `0` disables |
 
 ## Timestamps & Status Footer
 
-Subagent tool calls and live activity lines render a dim `hh:mm:ss` timestamp
-(call start, per-subagent run start, and each live log entry). The collapsed tool
-row keeps the normal compact progress text. Press `Ctrl+O` to expand it into the
-subagent tree immediately; every running node shows its latest six activity
-lines (thinking, tool starts/completions, and completed turns).
+Subagent tool calls and live activity lines render a dim `hh:mm:ss` timestamp.
+The collapsed view shows every direct child as `Name (agent-type)`, two prompt
+lines, its current status, and `last action`. That timestamp is the newest
+activity anywhere in the child's recursive subtree, so active grandchildren
+keep their ancestor visibly alive. Press `Ctrl+O` to expand the full recursive
+tree, including every agent's complete prompt and latest activity lines.
 
 In the interactive TUI the extension publishes the combined `total` usage line
 (parent + all subagents, recursively) via Pi's normal `ctx.ui.setStatus()`
@@ -188,7 +207,7 @@ status line. Pi renders all extension statuses on the same footer status line.
 
 ## Steering Running Subagents
 
-While a `subagents` tool call is running, mid-stream steering input can be broadcast to one or more child agents. The extension uses Pi's `InputEvent.streamingBehavior` metadata when available, so idle prompts and queued follow-ups continue to the parent normally; only true `steer` inputs open the broadcast routing prompt.
+While a `subagents` tool call is running, mid-stream steering input can be broadcast to one or more child agents. Targets are selected by human name; nested targets use paths such as `John > Maria > Elena`. The extension uses Pi's `InputEvent.streamingBehavior` metadata when available, so idle prompts and queued follow-ups continue to the parent normally; only true `steer` inputs open the broadcast routing prompt.
 
 ## Subagent Session Resume
 
@@ -215,16 +234,16 @@ Note: crash-resume covers `subagents` calls only. An interrupted `resume_subagen
 
 ## Resumable Subagents by Name (`resume_subagents`)
 
-Every subagent run is assigned a unique, durable name derived from its agent
-type plus a per-type counter — `code-writer-01`, `code-writer-02`,
-`code-reviewer-01`, ... The name is returned together with the subagent's
-results and shown in the TUI tree.
+Every subagent run is assigned a random, durable human first name from a bundled
+list of 500 popular American names — for example `John`, `Maria`, or `Elena`.
+Names are never reused anywhere in the same delegation tree. The name is
+returned together with the agent type and shown in every TUI view.
 
 The `resume_subagents` tool continues named subagents with a new task while
 preserving their full previous context:
 
 ```json
-{ "resumes": [{ "subagent": "code-writer-01", "task": "Now also update the tests." }] }
+{ "resumes": [{ "subagent": "John", "task": "Now also update the tests." }] }
 ```
 
 Naming is deliberately unambiguous: `agent` (in `subagents`) selects an agent

package/american-names.ts

@@ -0,0 +1,56 @@
+/** 500 common American first names used for human-friendly subagent identities. */
+export const AMERICAN_NAMES = [
+  // Common masculine names
+  "James", "John", "Robert", "Michael", "William", "David", "Richard", "Joseph", "Thomas", "Christopher",
+  "Charles", "Daniel", "Matthew", "Anthony", "Mark", "Donald", "Steven", "Andrew", "Paul", "Joshua",
+  "Kenneth", "Kevin", "Brian", "George", "Timothy", "Ronald", "Edward", "Jason", "Jeffrey", "Ryan",
+  "Jacob", "Gary", "Nicholas", "Eric", "Jonathan", "Stephen", "Larry", "Justin", "Scott", "Brandon",
+  "Benjamin", "Samuel", "Gregory", "Alexander", "Patrick", "Frank", "Raymond", "Jack", "Dennis", "Jerry",
+  "Tyler", "Aaron", "Jose", "Adam", "Nathan", "Henry", "Douglas", "Zachary", "Peter", "Kyle",
+  "Walter", "Ethan", "Jeremy", "Harold", "Keith", "Christian", "Roger", "Noah", "Gerald", "Carl",
+  "Terry", "Sean", "Austin", "Arthur", "Lawrence", "Jesse", "Dylan", "Bryan", "Joe", "Jordan",
+  "Billy", "Bruce", "Albert", "Willie", "Gabriel", "Logan", "Alan", "Juan", "Wayne", "Roy",
+  "Ralph", "Randy", "Eugene", "Vincent", "Russell", "Elijah", "Louis", "Bobby", "Philip", "Johnny",
+  "Howard", "Isaac", "Harry", "Victor", "Martin", "Ernest", "Phillip", "Todd", "Craig", "Shawn",
+  "Clarence", "Carlos", "Caleb", "Blake", "Mason", "Luke", "Liam", "Owen", "Nathaniel", "Cameron",
+  "Hunter", "Connor", "Adrian", "Julian", "Jeremiah", "Angel", "Isaiah", "Evan", "Colton", "Gavin",
+  "Dominic", "Cooper", "Ian", "Carson", "Jaxon", "Theodore", "Hudson", "Lincoln", "Asher", "Wyatt",
+  "Leo", "Ezra", "Miles", "Micah", "Silas", "Roman", "Wesley", "Brooks", "Bennett", "Parker",
+  "Beau", "Weston", "Damian", "Sawyer", "Emmett", "Harrison", "Cole", "Maxwell", "Holden", "Antonio",
+  "Miguel", "Oscar", "Diego", "Alejandro", "Marco", "Luis", "Javier", "Sergio", "Ricardo", "Manuel",
+  "Roberto", "Francisco", "Eduardo", "Fernando", "Ruben", "Raul", "Andres", "Hector", "Edgar", "Mario",
+  "Derek", "Trevor", "Travis", "Cody", "Dustin", "Corey", "Brett", "Chad", "Bradley", "Spencer",
+  "Grant", "Joel", "Dean", "Dale", "Glenn", "Stanley", "Leonard", "Francis", "Herbert", "Frederick",
+  "Norman", "Melvin", "Marvin", "Gordon", "Allen", "Bernard", "Clifford", "Warren", "Curtis", "Darren",
+  "Troy", "Marcus", "Derrick", "Andre", "Terrence", "Maurice", "Darius", "Malcolm", "Xavier", "Preston",
+  "Grayson", "Easton", "Nolan", "Everett", "Axel", "Emmanuel", "Kingston", "Elliot", "Tim", "Simon",
+  "Riley", "Finn", "Jasper", "Milo", "Rowan", "Declan", "Graham", "Max", "Nash", "Reid",
+  "Lane", "Tucker", "Carter", "Chase", "Coleman", "Bryce", "Hayden", "Aidan", "Jonah", "Jonas",
+
+  // Common feminine names
+  "Mary", "Patricia", "Jennifer", "Linda", "Elizabeth", "Barbara", "Susan", "Jessica", "Sarah", "Karen",
+  "Lisa", "Nancy", "Betty", "Margaret", "Sandra", "Ashley", "Kimberly", "Emily", "Donna", "Michelle",
+  "Carol", "Amanda", "Melissa", "Deborah", "Stephanie", "Dorothy", "Rebecca", "Sharon", "Laura", "Cynthia",
+  "Amy", "Kathleen", "Angela", "Shirley", "Brenda", "Emma", "Anna", "Pamela", "Nicole", "Samantha",
+  "Katherine", "Christine", "Debra", "Rachel", "Carolyn", "Janet", "Maria", "Heather", "Diane", "Julie",
+  "Joyce", "Victoria", "Kelly", "Christina", "Lauren", "Joan", "Evelyn", "Olivia", "Judith", "Megan",
+  "Cheryl", "Martha", "Andrea", "Frances", "Hannah", "Jacqueline", "Ann", "Gloria", "Jean", "Kathryn",
+  "Alice", "Teresa", "Sara", "Janice", "Doris", "Madison", "Julia", "Grace", "Judy", "Abigail",
+  "Marie", "Denise", "Beverly", "Amber", "Theresa", "Marilyn", "Danielle", "Diana", "Brittany", "Natalie",
+  "Sophia", "Rose", "Isabella", "Alexis", "Kayla", "Charlotte", "Lori", "Alexandra", "Savannah", "Brooklyn",
+  "Bella", "Claire", "Skylar", "Lucy", "Paisley", "Everly", "Caroline", "Nova", "Genesis", "Emilia",
+  "Kennedy", "Maya", "Willow", "Kinsley", "Naomi", "Aaliyah", "Elena", "Mckenna", "Ariana", "Allison",
+  "Gabriella", "Margot", "Madelyn", "Cora", "Ruby", "Eva", "Serenity", "Autumn", "Adeline", "Hailey",
+  "Gianna", "Valentina", "Isla", "Eliana", "Quinn", "Nevaeh", "Ivy", "Sadie", "Piper", "Lydia",
+  "Alexa", "Josephine", "Emery", "Phoebe", "Delilah", "Arianna", "Vivian", "Kaylee", "Sophie", "Brielle",
+  "Madeline", "Peyton", "Rylee", "Clara", "Hadley", "Melanie", "Mackenzie", "Reagan", "Adalynn", "Liliana",
+  "Aubree", "Jade", "Miranda", "Isabelle", "Natalia", "Raelynn", "Dakota", "Athena", "Ximena", "Arya",
+  "Leilani", "Taylor", "Faith", "Lena", "Kylie", "Miriam", "Kate", "Summer", "Lyla", "Brooke",
+  "Amaya", "Eliza", "Brianna", "Bailey", "Nina", "Khloe", "Jasmine", "Melody", "Isabel", "Norah",
+  "Annabelle", "Valeria", "Emerson", "Cecilia", "Valerie", "Molly", "Reese", "Aliyah", "Lilly", "Blair",
+  "Finley", "Morgan", "Sydney", "Jordyn", "Eloise", "Trinity", "Daisy", "Catherine", "Lola", "Genevieve",
+  "Marley", "Arabella", "Harmony", "Elise", "Remi", "Teagan", "Evie", "London", "Sloane", "Laila",
+  "Lucia", "Willa", "Juliana", "Gracie", "June", "Tessa", "Ada", "Camille", "Hope", "Samara",
+  "Rosalie", "Ruth", "Fiona", "Georgia", "Noelle", "Vanessa", "Daniela", "Paige", "Violet", "Presley",
+  "Adriana", "Joanna", "Giselle", "Harper", "Avery", "Scarlett", "Aria", "Ellie", "Chloe", "Layla",
+] as const;

package/index.ts

@@ -45,7 +45,6 @@ import {
   renderCall,
   renderResult,
   renderResumeCall,
-  setBroadcastNumberingActive,
 } from "./render.js";
 import { runAgentSubprocess, executeParallelSubprocess, type RunningSubagentHandle } from "./runner.js";
 import {
@@ -166,7 +165,7 @@ const SubagentParams = Type.Object({
 
 const ResumeItem = Type.Object({
   subagent: Type.String({
-    description: "Unique subagent name returned by a previous subagents run (e.g. code-writer-01)",
+    description: "Unique human name returned by a previous subagents run (e.g. John)",
   }),
   task: Type.String({
     description: "New task for the resumed subagent. It keeps its previous context.",
@@ -1001,7 +1000,7 @@ export default function (pi: ExtensionAPI) {
   let pendingResumePlans: ResumableSubagentCall[] = [];
   let modelToRestoreAfterResume: any | undefined;
   const approvedProjectAgentDirsForSession = new Set<string>();
-  const activeSubagents = new Map<number, { agent: string; task: string; taskIndex: number; handle: RunningSubagentHandle; name?: string }>();
+  const activeSubagents = new Map<number, { agent: string; task: string; handle: RunningSubagentHandle; name?: string }>();
   /** Names with a resume in flight in this process (same-process race guard). */
   const activeResumeNames = new Set<string>();
   /** Tool calls whose execute result requested an actual Pi error result. */
@@ -1083,9 +1082,10 @@ export default function (pi: ExtensionAPI) {
   const BROADCAST_STEER_PREFIX = "__PI_SUBAGENT_BROADCAST_STEER__";
 
   interface BroadcastTarget {
+    /** Human-name path, e.g. "John > Maria > Elena". */
     display: string;
     topLevelId: number;
-    restPath: number[];
+    restPath: string[];
   }
 
   interface ParsedBroadcastSelection {
@@ -1093,83 +1093,40 @@ export default function (pi: ExtensionAPI) {
     errors: string[];
   }
 
-  function parseBroadcastPath(raw: string): number[] | null {
-    const parts = raw.trim().split(".");
-    if (parts.length === 0) return null;
-    const path: number[] = [];
-    for (const part of parts) {
-      if (!/^\d+$/.test(part)) return null;
-      const value = Number(part);
-      if (!Number.isSafeInteger(value) || value < 1) return null;
-      path.push(value);
+  function parseBroadcastSelection(input: string, available: BroadcastTarget[]): ParsedBroadcastSelection {
+    if (input.trim().toUpperCase() === "ALL") return { targets: [...available], errors: [] };
+    const byName = new Map<string, BroadcastTarget>();
+    for (const target of available) {
+      byName.set(target.display.toLowerCase(), target);
+      // Names are globally unique across the delegation tree, so a nested leaf
+      // can be addressed as "Maria" without spelling "John > Maria".
+      const leafName = target.display.split(" > ").at(-1);
+      if (leafName) byName.set(leafName.toLowerCase(), target);
     }
-    return path;
-  }
-
-  function parseBroadcastSelection(input: string, available: number[]): ParsedBroadcastSelection {
-    const normalized = input.trim().toUpperCase();
-    if (normalized === "ALL") {
-      return {
-        targets: available.map((id) => ({ display: String(id), topLevelId: id, restPath: [] })),
-        errors: [],
-      };
-    }
-
+    const targets: BroadcastTarget[] = [];
     const errors: string[] = [];
-    const targetMap = new Map<string, BroadcastTarget>();
     for (const rawPart of input.split(",")) {
-      const part = rawPart.trim();
-      if (!part) continue;
-
-      if (part.includes("-")) {
-        const [startRaw, endRaw, extra] = part.split("-").map((p) => p.trim());
-        const startPath = parseBroadcastPath(startRaw);
-        const endPath = parseBroadcastPath(endRaw);
-        if (extra !== undefined || !startPath || !endPath || startPath.length !== 1 || endPath.length !== 1) {
-          errors.push(`Invalid range "${part}". Use top-level ranges like 1-3.`);
-          continue;
-        }
-        const start = startPath[0];
-        const end = endPath[0];
-        for (let id = Math.min(start, end); id <= Math.max(start, end); id++) {
-          if (!available.includes(id)) {
-            errors.push(`Subagent ${id} is not running.`);
-            continue;
-          }
-          targetMap.set(String(id), { display: String(id), topLevelId: id, restPath: [] });
-        }
-        continue;
-      }
-
-      const path = parseBroadcastPath(part);
-      if (!path) {
-        errors.push(`Invalid target "${part}". Use ALL, numbers, paths, or top-level ranges (e.g. 1, 2, 4.1, 1-3).`);
-        continue;
-      }
-      const [topLevelId, ...restPath] = path;
-      if (!available.includes(topLevelId)) {
-        errors.push(`Subagent ${topLevelId} is not running.`);
-        continue;
-      }
-      const display = path.join(".");
-      targetMap.set(display, { display, topLevelId, restPath });
+      const requested = rawPart.trim();
+      if (!requested) continue;
+      const target = byName.get(requested.toLowerCase());
+      if (target) targets.push(target);
+      else errors.push(`Subagent "${requested}" is not running. Use its human name.`);
     }
-
     return {
-      targets: Array.from(targetMap.values()).sort((a, b) => a.display.localeCompare(b.display, undefined, { numeric: true })),
+      targets: Array.from(new Map(targets.map((target) => [target.display, target])).values()),
       errors,
     };
   }
 
-  function encodeNestedBroadcast(message: string, path: number[]): string {
+  function encodeNestedBroadcast(message: string, path: string[]): string {
     return `${BROADCAST_STEER_PREFIX}${JSON.stringify({ path, message })}`;
   }
 
-  function decodeNestedBroadcast(text: string): { path: number[]; message: string } | null {
+  function decodeNestedBroadcast(text: string): { path: string[]; message: string } | null {
     if (!text.startsWith(BROADCAST_STEER_PREFIX)) return null;
     try {
       const parsed = JSON.parse(text.slice(BROADCAST_STEER_PREFIX.length));
-      if (!Array.isArray(parsed?.path) || !parsed.path.every((n: unknown) => Number.isSafeInteger(n) && (n as number) >= 1)) return null;
+      if (!Array.isArray(parsed?.path) || !parsed.path.every((name: unknown) => typeof name === "string" && name.length > 0)) return null;
       if (typeof parsed?.message !== "string") return null;
       return { path: parsed.path, message: parsed.message };
     } catch {
@@ -1177,66 +1134,37 @@ export default function (pi: ExtensionAPI) {
     }
   }
 
-  function extractPendingSubagentTaskCounts(result: SingleResult): number[] {
-    const messages = Array.isArray((result as any).messages) ? (result as any).messages : [];
-    const completedToolCallIds = new Set(getNestedSubagentResults(messages).map((nested) => nested.toolCallId));
-    const counts: number[] = [];
-    for (const message of messages) {
-      if (message?.role !== "assistant" || !Array.isArray(message.content)) continue;
-      for (const part of message.content) {
-        if (part?.type !== "toolCall" || !isSubagentToolName(part?.name)) continue;
-        const toolCallId = typeof part.toolCallId === "string" ? part.toolCallId : typeof part.id === "string" ? part.id : undefined;
-        if (toolCallId && completedToolCallIds.has(toolCallId)) continue;
-        const rawResumes = part.arguments?.resumes;
-        const tasks = Array.isArray(part.arguments?.tasks)
-          ? part.arguments.tasks
-          : Array.isArray(rawResumes)
-            ? rawResumes
-            : rawResumes && typeof rawResumes === "object"
-              ? [rawResumes]
-              : [];
-        if (tasks.length > 0) counts.push(tasks.length);
-      }
-    }
-    return counts;
-  }
-
   function collectRunningBroadcastTargetsFromResult(
     result: SingleResult,
-    path: number[],
+    namePath: string[],
+    topLevelId: number,
     targets: { all: BroadcastTarget[]; youngest: BroadcastTarget[] },
   ): boolean {
-    const nestedRunningPaths: number[][] = [];
-
+    let hasRunningDescendant = false;
+    const completedIds = new Set<string>();
+    const nestedDetails: SubagentDetails[] = [];
     for (const nested of getNestedSubagentResults(result.messages)) {
       if (!isSubagentDetails(nested.details)) continue;
-      nested.details.results.forEach((child, index) => {
-        const childPath = [...path, index + 1];
-        if (collectRunningBroadcastTargetsFromResult(child, childPath, targets)) {
-          nestedRunningPaths.push(childPath);
-        }
-      });
+      if (nested.toolCallId) completedIds.add(nested.toolCallId);
+      nestedDetails.push(nested.details);
     }
-
-    if (result.exitCode === -1) {
-      for (const taskCount of extractPendingSubagentTaskCounts(result)) {
-        for (let i = 1; i <= taskCount; i++) {
-          const childPath = [...path, i];
-          const [topLevelId, ...restPath] = childPath;
-          targets.all.push({ display: childPath.join("."), topLevelId, restPath });
-          targets.youngest.push({ display: childPath.join("."), topLevelId, restPath });
-          nestedRunningPaths.push(childPath);
+    for (const [toolCallId, live] of Object.entries(result.liveNestedSubagents ?? {})) {
+      if (!completedIds.has(toolCallId) && isSubagentDetails(live)) nestedDetails.push(live);
+    }
+    for (const details of nestedDetails) {
+      for (const child of details.results) {
+        const childName = child.name || child.agent;
+        if (collectRunningBroadcastTargetsFromResult(child, [...namePath, childName], topLevelId, targets)) {
+          hasRunningDescendant = true;
         }
       }
     }
 
-    const isRunning = result.exitCode === -1;
-    if (!isRunning) return nestedRunningPaths.length > 0;
-
-    const [topLevelId, ...restPath] = path;
-    const self = { display: path.join("."), topLevelId, restPath };
+    if (result.exitCode !== -1) return hasRunningDescendant;
+    const restPath = namePath.slice(1);
+    const self = { display: namePath.join(" > "), topLevelId, restPath };
     targets.all.push(self);
-    if (nestedRunningPaths.length === 0) targets.youngest.push(self);
+    if (!hasRunningDescendant) targets.youngest.push(self);
     return true;
   }
 
@@ -1244,28 +1172,34 @@ export default function (pi: ExtensionAPI) {
     latestBroadcastTargets.all = [];
     latestBroadcastTargets.youngest = [];
     if (!details) {
-      for (const id of activeSubagents.keys()) {
-        const target = { display: String(id), topLevelId: id, restPath: [] };
+      for (const [id, active] of activeSubagents) {
+        const display = active.name || active.agent;
+        const target = { display, topLevelId: id, restPath: [] };
         latestBroadcastTargets.all.push(target);
         latestBroadcastTargets.youngest.push(target);
       }
       return;
     }
     details.results.forEach((result, index) => {
-      collectRunningBroadcastTargetsFromResult(result, [topLevelBaseId + index], latestBroadcastTargets);
+      collectRunningBroadcastTargetsFromResult(
+        result,
+        [result.name || result.agent],
+        topLevelBaseId + index,
+        latestBroadcastTargets,
+      );
     });
     const dedupe = (targets: BroadcastTarget[]) =>
       Array.from(new Map(targets.map((target) => [target.display, target])).values())
         .filter((target) => activeSubagents.has(target.topLevelId))
-        .sort((a, b) => a.display.localeCompare(b.display, undefined, { numeric: true }));
+        .sort((a, b) => a.display.localeCompare(b.display));
     latestBroadcastTargets.all = dedupe(latestBroadcastTargets.all);
     latestBroadcastTargets.youngest = dedupe(latestBroadcastTargets.youngest);
   }
 
   function getFallbackTopLevelTargets(): BroadcastTarget[] {
-    return Array.from(activeSubagents.keys())
-      .sort((a, b) => a - b)
-      .map((id) => ({ display: String(id), topLevelId: id, restPath: [] }));
+    return Array.from(activeSubagents.entries())
+      .sort(([a], [b]) => a - b)
+      .map(([id, active]) => ({ display: active.name || active.agent, topLevelId: id, restPath: [] }));
   }
 
   function sendBroadcastToTargets(message: string, targets: BroadcastTarget[], ctx: any): void {
@@ -1297,30 +1231,24 @@ export default function (pi: ExtensionAPI) {
     if (nested) {
       if (activeSubagents.size === 0) return "handled";
       const [rawTarget, ...restPath] = nested.path;
-      // Path components below the top level are 1-based task indexes within the
-      // subagent tool call running in THIS process. Internal active ids keep
-      // growing across sequential tool calls (and process restarts), so resolve
-      // by task index first; fall back to a direct id match for compatibility.
       let resolvedId: number | undefined;
       for (const [id, item] of activeSubagents) {
-        if (item.taskIndex === rawTarget - 1 && (resolvedId === undefined || id > resolvedId)) {
+        if ((item.name || item.agent).toLowerCase() === rawTarget.toLowerCase()) {
           resolvedId = id;
+          break;
         }
       }
-      if (resolvedId === undefined && activeSubagents.has(rawTarget)) resolvedId = rawTarget;
       if (resolvedId === undefined) return "handled";
-      sendBroadcastToTargets(nested.message, [{ display: nested.path.join("."), topLevelId: resolvedId, restPath }], ctx);
+      sendBroadcastToTargets(nested.message, [{ display: nested.path.join(" > "), topLevelId: resolvedId, restPath }], ctx);
       return "handled";
     }
 
     if (!ctx.hasUI || activeSubagents.size === 0) return "continue";
 
-    setBroadcastNumberingActive(true);
     try {
-      const available = Array.from(activeSubagents.keys()).sort((a, b) => a - b);
       const choice = await ctx.ui.select(
         "Broadcast this steering message to subagents?",
-        ["No", "All (+nested)", "Youngest", "Numbers (e.g. 1, 2, 4.1)"],
+        ["No", "All (+nested)", "Youngest", "Names (e.g. John, Maria)"],
       );
       if (choice === "All (+nested)" || choice === "Youngest") {
         const fallback = getFallbackTopLevelTargets();
@@ -1335,29 +1263,19 @@ export default function (pi: ExtensionAPI) {
         sendBroadcastToTargets(message, current, ctx);
         return "handled";
       }
-      if (choice !== "Numbers (e.g. 1, 2, 4.1)") return "continue";
+      if (choice !== "Names (e.g. John, Maria)") return "continue";
 
       const answer = await ctx.ui.input(
-        "Subagent numbers/ranges to broadcast to (e.g. 1, 2, 4.1)",
+        "Subagent names to broadcast to (comma-separated)",
         "",
       );
       if (!answer) return "continue";
-      const current = Array.from(new Set([
-        ...available,
-        ...latestBroadcastTargets.all.map((target) => target.topLevelId),
-      ])).sort((a, b) => a - b);
+      const current = latestBroadcastTargets.all.length > 0
+        ? latestBroadcastTargets.all
+        : getFallbackTopLevelTargets();
       const parsed = parseBroadcastSelection(answer, current);
-      const knownDisplays = new Set(latestBroadcastTargets.all.map((target) => target.display));
-      const validatedTargets = knownDisplays.size > 0
-        ? parsed.targets.filter((target) => knownDisplays.has(target.display))
-        : parsed.targets;
-      const unknownNested = knownDisplays.size > 0
-        ? parsed.targets.filter((target) => !knownDisplays.has(target.display)).map((target) => target.display)
-        : [];
-      const errors = [
-        ...parsed.errors,
-        ...unknownNested.map((display) => `Subagent ${display} is not running.`),
-      ];
+      const validatedTargets = parsed.targets;
+      const errors = parsed.errors;
       if (errors.length > 0) {
         ctx.ui.notify(errors.slice(0, 4).join("\n"), "warning");
       }
@@ -1368,7 +1286,7 @@ export default function (pi: ExtensionAPI) {
       sendBroadcastToTargets(message, validatedTargets, ctx);
       return "handled";
     } finally {
-      setBroadcastNumberingActive(false);
+      // No persistent steering UI state.
     }
   }
 
@@ -1790,13 +1708,13 @@ ${preventCycles
         ? ""
         : 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
+Every subagent run is assigned a unique, durable human name (e.g. \`John\`,
+\`Maria\`) which is returned together with its results. Use the
 \`resume_subagents\` tool to continue named subagents with a new task while
 keeping their full previous context:
 
 \`\`\`json
-{ "resumes": [{ "subagent": "code-writer-01", "task": "Now also update the tests." }] }
+{ "resumes": [{ "subagent": "John", "task": "Now also update the tests." }] }
 \`\`\`
 
 - \`agent\` (in \`subagents\`) is an agent TYPE; \`subagent\` (in \`resume_subagents\`)
@@ -1937,7 +1855,7 @@ ${agentList}\n\n${subagentsGuidance}\n\n${delegationGuardGuidance}${resumeGuidan
             pendingResumePlans.splice(resumePlanIndex, 1);
           }
 
-          // Assign durable, tree-unique names (code-writer-01, ...). Resumed
+          // Assign random durable human names unique across the whole tree. Resumed
           // runs keep the names already recorded in the previous results.
           const names: Array<string | undefined> = tasks.map(
             (_task, index) => resumePlan?.details?.results[index]?.name,
@@ -1969,7 +1887,7 @@ ${agentList}\n\n${subagentsGuidance}\n\n${delegationGuardGuidance}${resumeGuidan
                   names[index] = allocated[allocIndex];
                 });
               } catch (err) {
-                console.warn("[pi-subagent] Failed to allocate subagent names (continuing without):", err);
+                throw new Error(`Failed to allocate unique subagent names: ${err instanceof Error ? err.message : String(err)}`);
               }
             }
           }
@@ -2037,10 +1955,10 @@ ${agentList}\n\n${subagentsGuidance}\n\n${delegationGuardGuidance}${resumeGuidan
       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",
+        "Every subagent run returns a unique human name (e.g. John). Pass those names",
         "as `subagent` to continue them. All resumes in one call run IN PARALLEL.",
         "",
-        'Example: { resumes: [{ subagent: "code-writer-01", task: "Also update the tests." }] }',
+        'Example: { resumes: [{ subagent: "John", task: "Also update the tests." }] }',
       ].join("\n"),
       parameters: ResumeSubagentsParams,
       prepareArguments: prepareResumeArguments,
@@ -2274,7 +2192,9 @@ ${agentList}\n\n${subagentsGuidance}\n\n${delegationGuardGuidance}${resumeGuidan
   // -----------------------------------------------------------------------
 
   function formatNameSuffix(result: SingleResult | undefined): string {
-    return result?.name ? `\n\n(subagent name: ${result.name} — resumable via resume_subagents)` : "";
+    return result?.name
+      ? `\n\n(subagent: ${result.name} (${result.agent}) — resume with the name ${result.name})`
+      : "";
   }
 
   async function executeSingle(
@@ -2326,7 +2246,7 @@ ${agentList}\n\n${subagentsGuidance}\n\n${delegationGuardGuidance}${resumeGuidan
       fallbackModel,
       onHandle: (handle) => {
         activeId = topLevelBaseId;
-        activeSubagents.set(activeId, { agent: agentName, task, taskIndex: 0, handle, name: subagentName });
+        activeSubagents.set(activeId, { agent: agentName, task, handle, name: subagentName });
         updateLatestBroadcastTargets(undefined);
       },
     });
@@ -2345,7 +2265,7 @@ ${agentList}\n\n${subagentsGuidance}\n\n${delegationGuardGuidance}${resumeGuidan
         content: [
           {
             type: "text" as const,
-            text: `Agent ${result.stopReason || "failed"}: ${errorMsg}`,
+            text: `${result.name ? `${result.name} (${result.agent})` : `Agent ${result.agent}`} ${result.stopReason || "failed"}: ${errorMsg}`,
           },
         ],
         details: makeDetails("single")([result]),
@@ -2398,7 +2318,7 @@ ${agentList}\n\n${subagentsGuidance}\n\n${delegationGuardGuidance}${resumeGuidan
         (index, task, handle) => {
           const id = topLevelBaseId + index;
           taskIds.set(index, id);
-          activeSubagents.set(id, { agent: task.agent, task: task.task, taskIndex: index, handle, name: extras?.names?.[index] });
+          activeSubagents.set(id, { agent: task.agent, task: task.task, handle, name: extras?.names?.[index] });
           updateLatestBroadcastTargets(undefined);
         },
         (index) => {