@dreki-gg/pi-subagent 0.8.3 → 0.9.0

package/CHANGELOG.md

@@ -1,5 +1,27 @@
 # @dreki-gg/pi-subagent
 
+## 0.9.0
+
+### Minor Changes
+
+- [`99bc4e7`](https://github.com/dreki-gg/pi-extensions/commit/99bc4e7abb9f468ebd6705a56ed1c2a801dd466e) Thanks [@jalbarrang](https://github.com/jalbarrang)! - Add `list_agents` tool and `/create-agent` command to help the LLM discover available agents before spawning and scaffold new project-local agent prompts.
+
+## 0.8.4
+
+### Patch Changes
+
+- [`376864c`](https://github.com/dreki-gg/pi-extensions/commit/376864c37cefa47530363b47055311269c1724a8) Thanks [@jalbarrang](https://github.com/jalbarrang)! - feat(subagent): show live tool-aware status in working message during /run-agent
+
+  Previously `/run-agent` only showed a transient notification, leaving users with no visibility into what the background agent was doing (especially after a fork-at session switch that visually looks like a reload). Now the working message updates in real-time as the agent works:
+
+  - `scout · starting...`
+  - `scout · reading …/src/utils.ts`
+  - `scout · $ bun test --filter...`
+  - `scout · editing …/config.json`
+  - `scout · thinking...`
+
+  Added `onToolExecutionStart` callback to `spawnPiAgent` and `runAgent` to surface `tool_execution_start` events from the JSON stream.
+
 ## 0.8.3
 
 ### Patch Changes

package/extensions/subagent/agent-runner.ts

@@ -1,7 +1,7 @@
 import type { ResolvedPaths } from '@earendil-works/pi-coding-agent';
 import { discoverAgents, type AgentScope } from './agents.js';
 import type { AgentResult } from './agent-runner-types.js';
-import { emptyUsage, spawnPiAgent } from './spawn-utils.js';
+import { emptyUsage, spawnPiAgent, type ToolExecutionStartEvent } from './spawn-utils.js';
 
 export type OnPhaseUpdate = (phaseName: string, agentName: string, result: AgentResult) => void;
 
@@ -11,6 +11,7 @@ export interface RunAgentOptions {
   model?: string;
   thinking?: string;
   onUpdate?: OnPhaseUpdate;
+  onToolExecutionStart?: (event: ToolExecutionStartEvent) => void;
   phaseName?: string;
   signal?: AbortSignal;
   resolvedPaths?: ResolvedPaths;
@@ -76,6 +77,7 @@ export async function runAgent(
         options.onUpdate(options.phaseName ?? 'unknown', agentName, { ...result });
       }
     },
+    onToolExecutionStart: options.onToolExecutionStart,
   });
 
   result.exitCode = spawnResult.exitCode;

package/extensions/subagent/create-agent.ts

@@ -0,0 +1,98 @@
+/**
+ * /create-agent command — scaffolds a new project-local agent prompt in .pi/prompts/.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import type { ExtensionAPI } from '@earendil-works/pi-coding-agent';
+
+const TEMPLATE = `---
+name: {{name}}
+description: {{description}}
+---
+
+You are the **{{name}}** agent.
+
+## Role
+
+{{description}}
+
+## Guidelines
+
+- Be concise and focused on your assigned task.
+- Use available tools to gather context before acting.
+- Report your findings or output clearly.
+`;
+
+function slugify(name: string): string {
+  return name
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, '-')
+    .replace(/^-|-$/g, '');
+}
+
+export function registerCreateAgentCommand(pi: ExtensionAPI) {
+  pi.registerCommand('create-agent', {
+    description:
+      'Create a new project-local agent prompt in .pi/prompts/. Usage: /create-agent <name> [description]',
+
+    handler: async (args, ctx) => {
+      if (!args?.trim()) {
+        ctx.ui.notify(
+          'Usage: /create-agent <name> [description]\n\nCreates a new agent prompt file in .pi/prompts/',
+          'warning',
+        );
+        return;
+      }
+
+      const tokens = args.trim().split(/\s+/);
+      const name = slugify(tokens[0]);
+      const description = tokens.slice(1).join(' ') || `A project-local ${name} agent.`;
+
+      if (!name) {
+        ctx.ui.notify('Invalid agent name.', 'error');
+        return;
+      }
+
+      const promptsDir = path.join(ctx.cwd, '.pi', 'prompts');
+      const filePath = path.join(promptsDir, `${name}.md`);
+
+      if (fs.existsSync(filePath)) {
+        ctx.ui.notify(
+          `Agent "${name}" already exists at ${filePath}`,
+          'warning',
+        );
+        return;
+      }
+
+      // Create directory if needed
+      fs.mkdirSync(promptsDir, { recursive: true });
+
+      // Write the template
+      const content = TEMPLATE
+        .replace(/\{\{name\}\}/g, name)
+        .replace(/\{\{description\}\}/g, description);
+
+      fs.writeFileSync(filePath, content, 'utf-8');
+
+      ctx.ui.notify(
+        `Created agent "${name}" at ${path.relative(ctx.cwd, filePath)}`,
+        'info',
+      );
+
+      // Send a follow-up so the LLM can help refine the prompt
+      pi.sendUserMessage(
+        [
+          `I just created a new project-local agent prompt at \`${path.relative(ctx.cwd, filePath)}\`.`,
+          '',
+          `Agent name: **${name}**`,
+          `Description: ${description}`,
+          '',
+          'The file has a basic template. You can now read and refine the agent prompt to fit your needs.',
+          'Remember to use `agentScope: "both"` or `agentScope: "project"` when spawning this agent.',
+        ].join('\n'),
+        { deliverAs: 'followUp' },
+      );
+    },
+  });
+}

package/extensions/subagent/index.ts

@@ -43,12 +43,63 @@ import { extractRecentConversation } from './synthesis.js';
 import type { AgentResult } from './agent-runner-types.js';
 import { getFinalText } from './agent-result-utils.js';
 import { buildHandoffFromResult, renderHandoffForPrompt } from './handoffs.js';
-import { emptyUsage, spawnPiAgent } from './spawn-utils.js';
+import { emptyUsage, spawnPiAgent, type ToolExecutionStartEvent } from './spawn-utils.js';
+import { registerListAgentsTool } from './list-agents.js';
+import { registerCreateAgentCommand } from './create-agent.js';
 
 const MAX_PARALLEL_TASKS = 8;
 const MAX_CONCURRENCY = 4;
 const COLLAPSED_ITEM_COUNT = 10;
 
+function describeToolExecution(event: ToolExecutionStartEvent): string {
+  const shortenPath = (p: string) => {
+    const home = os.homedir();
+    const shortened = p.startsWith(home) ? `~${p.slice(home.length)}` : p;
+    // Show only the last 2 path segments for brevity
+    const parts = shortened.split('/');
+    return parts.length > 3 ? `…/${parts.slice(-2).join('/')}` : shortened;
+  };
+
+  const args = event.args;
+  switch (event.toolName) {
+    case 'bash': {
+      const cmd = (args.command as string) || '';
+      const preview = cmd.length > 50 ? `${cmd.slice(0, 50)}…` : cmd;
+      return `$ ${preview}`;
+    }
+    case 'read': {
+      const p = ((args.file_path || args.path) as string) || '';
+      return `reading ${shortenPath(p)}`;
+    }
+    case 'write': {
+      const p = ((args.file_path || args.path) as string) || '';
+      return `writing ${shortenPath(p)}`;
+    }
+    case 'edit': {
+      const p = ((args.file_path || args.path) as string) || '';
+      return `editing ${shortenPath(p)}`;
+    }
+    case 'grep': {
+      const pattern = (args.pattern as string) || '';
+      return `grep /${pattern}/`;
+    }
+    case 'find': {
+      const pattern = (args.pattern as string) || '*';
+      return `find ${pattern}`;
+    }
+    case 'ls':
+      return `ls ${shortenPath((args.path as string) || '.')}`;
+    case 'web_search':
+      return `searching: ${(args.query as string)?.slice(0, 40) || '…'}`;
+    case 'web_visit':
+      return 'visiting page';
+    case 'subagent':
+      return `spawning ${(args.agent as string) || 'subagent'}`;
+    default:
+      return event.toolName;
+  }
+}
+
 function formatTokens(count: number): string {
   if (count < 1000) return count.toString();
   if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
@@ -505,6 +556,9 @@ export default function (pi: ExtensionAPI) {
     return [...items.values()];
   }
 
+  registerListAgentsTool(pi, resolvePackagePaths);
+  registerCreateAgentCommand(pi);
+
   pi.registerTool({
     name: 'subagent',
     label: 'Subagent',
@@ -515,6 +569,10 @@ export default function (pi: ExtensionAPI) {
       'Default agent scope is "user" (from ~/.pi/agent/prompts).',
       'To enable project-local agents in .pi/prompts, set agentScope: "both" (or "project").',
     ].join(' '),
+    promptGuidelines: [
+      'If you are unsure which agents are available, call list_agents first before using the subagent tool.',
+      'Use /create-agent to scaffold new project-local agent prompts when the user needs a custom agent.',
+    ],
     parameters: SubagentParams,
 
     async execute(_toolCallId, params, signal, onUpdate, ctx) {
@@ -1439,13 +1497,29 @@ export default function (pi: ExtensionAPI) {
           `Running agent: ${agent.name} [${agent.source}${forked ? ', forked' : ', inline'}${selectedModel ? `, model=${selectedModel}` : ''}${selectedThinking ? `, thinking=${selectedThinking}` : ''}]`,
           'info',
         );
+        let lastToolDescription = '';
+        const updateWorkingStatus = (toolDesc?: string) => {
+          if (toolDesc) lastToolDescription = toolDesc;
+          const parts = [agent.name];
+          if (lastToolDescription) parts.push(lastToolDescription);
+          commandUi.setWorkingMessage(parts.join(' · '));
+        };
+        updateWorkingStatus('starting...');
 
         const result = await runAgent(commandCwd, agent.name, task, {
           agentScope,
           resolvedPaths,
           model,
           thinking,
+          onUpdate: () => {
+            // When a turn completes and the agent is thinking about next steps
+            updateWorkingStatus('thinking...');
+          },
+          onToolExecutionStart: (event) => {
+            updateWorkingStatus(describeToolExecution(event));
+          },
         });
+        commandUi.setWorkingMessage();
         const failed = result.exitCode !== 0 || result.stopReason === 'error';
         const output = getFinalText(result).trim();
 

package/extensions/subagent/list-agents.ts

@@ -0,0 +1,92 @@
+/**
+ * list_agents tool — lets the LLM discover available agents before spawning.
+ */
+
+import type { ExtensionAPI, ResolvedPaths } from '@earendil-works/pi-coding-agent';
+import { Type } from 'typebox';
+import { type AgentScope, discoverAgents } from './agents.js';
+import { StringEnum } from '@earendil-works/pi-ai';
+
+export function registerListAgentsTool(
+  pi: ExtensionAPI,
+  resolvePackagePaths: (cwd: string) => Promise<ResolvedPaths | undefined>,
+) {
+  const AgentScopeSchema = StringEnum(['user', 'project', 'both'] as const, {
+    description:
+      'Which agent directories to search. Default: "user". Use "both" to include project-local agents.',
+    default: 'user',
+  });
+
+  pi.registerTool({
+    name: 'list_agents',
+    label: 'List Agents',
+    description:
+      'List available subagent prompts. Call this before spawning agents if you are unsure which agents exist.',
+    promptSnippet: 'List available subagent prompts to discover what agents can be spawned',
+    promptGuidelines: [
+      'Call list_agents before using the subagent tool when you are not certain which agents are available.',
+      'list_agents returns agent names, descriptions, sources, and capabilities.',
+    ],
+    parameters: Type.Object({
+      agentScope: Type.Optional(AgentScopeSchema),
+    }),
+
+    async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
+      const agentScope: AgentScope = params.agentScope ?? 'user';
+      const resolvedPaths = await resolvePackagePaths(ctx.cwd);
+      const discovery = discoverAgents(ctx.cwd, agentScope, resolvedPaths);
+
+      if (discovery.agents.length === 0) {
+        const dirs = agentScope === 'user'
+          ? '~/.pi/agent/prompts'
+          : agentScope === 'project'
+            ? '.pi/prompts'
+            : '~/.pi/agent/prompts and .pi/prompts';
+        return {
+          content: [
+            {
+              type: 'text',
+              text: `No agents found in scope "${agentScope}". Check ${dirs} for agent prompt files.`,
+            },
+          ],
+          details: { agents: [], scope: agentScope },
+        };
+      }
+
+      const lines: string[] = [
+        `Available agents (scope: ${agentScope}):`,
+        '',
+      ];
+
+      for (const agent of discovery.agents) {
+        lines.push(`### ${agent.name}`);
+        lines.push(`- **Source**: ${agent.source}`);
+        lines.push(`- **Description**: ${agent.description}`);
+        if (agent.model) lines.push(`- **Default model**: ${agent.model}`);
+        if (agent.thinking) lines.push(`- **Default thinking**: ${agent.thinking}`);
+        if (agent.tools) lines.push(`- **Tools**: ${agent.tools.join(', ')}`);
+        if (agent.sessionStrategy) lines.push(`- **Session strategy**: ${agent.sessionStrategy}`);
+        lines.push('');
+      }
+
+      if (discovery.projectPromptsDir) {
+        lines.push(`Project prompts directory: ${discovery.projectPromptsDir}`);
+      }
+
+      return {
+        content: [{ type: 'text', text: lines.join('\n') }],
+        details: {
+          agents: discovery.agents.map((a) => ({
+            name: a.name,
+            description: a.description,
+            source: a.source,
+            model: a.model,
+            tools: a.tools,
+          })),
+          scope: agentScope,
+          projectPromptsDir: discovery.projectPromptsDir,
+        },
+      };
+    },
+  });
+}

package/extensions/subagent/spawn-utils.ts

@@ -57,6 +57,12 @@ function cleanupTempFiles(
   if (tmpPromptDir) try { fs.rmdirSync(tmpPromptDir); } catch { /* ignore */ }
 }
 
+export interface ToolExecutionStartEvent {
+  toolCallId: string;
+  toolName: string;
+  args: Record<string, unknown>;
+}
+
 export interface SpawnPiAgentOptions {
   cwd: string;
   agentName: string;
@@ -68,6 +74,7 @@ export interface SpawnPiAgentOptions {
   signal?: AbortSignal;
   onMessage?: (msg: Message) => void;
   onToolResult?: (msg: Message) => void;
+  onToolExecutionStart?: (event: ToolExecutionStartEvent) => void;
 }
 
 export interface SpawnPiAgentResult {
@@ -158,6 +165,14 @@ export async function spawnPiAgent(options: SpawnPiAgentOptions): Promise<SpawnP
           result.messages.push(event.message as Message);
           options.onToolResult?.(event.message as Message);
         }
+
+        if (event.type === 'tool_execution_start' && event.toolName) {
+          options.onToolExecutionStart?.({
+            toolCallId: event.toolCallId ?? '',
+            toolName: event.toolName,
+            args: event.args ?? {},
+          });
+        }
       };
 
       proc.stdout.on('data', (data: Buffer) => {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dreki-gg/pi-subagent",
-  "version": "0.8.3",
+  "version": "0.9.0",
   "description": "Subagent tool and direct agent runs for pi — isolated agents, parallel scouts, manager workflows, and bundled prompts",
   "keywords": [
     "pi-package"

package/skills/spawn-subagents/SKILL.md

@@ -114,6 +114,12 @@ Avoid:
 - calling `advisor` when `planner` or `reviewer` already has enough signal to proceed alone
 - sending speculative review findings back for fixes before they are validated when evidence is needed
 
+## 8. Agent discovery and creation
+Use `list_agents` before spawning when you're unsure which agents exist.
+Use `/create-agent <name> [description]` to scaffold a new project-local agent in `.pi/prompts/` when the user needs a custom agent that doesn't exist yet.
+- After creating, read and refine the prompt file to fit the use case.
+- Remember to use `agentScope: "both"` or `"project"` to include project-local agents.
+
 Execution rules:
 - Use `manager` when the task is too large for one prompt but still needs coherent decisions.
 - Use `advisor` for targeted second opinions on tricky or high-risk cases.