pi-subagents-lite 1.2.0 → 1.3.0

package/README.md

@@ -18,13 +18,13 @@ Every tool the LLM sees costs tokens — in the system prompt, and in every turn
 | `promptGuidelines` with rules | _(none)_ |
 | Parameters with `.description()` | Bare `Type.String()` |
 
-Tool names like `Agent` and `StopAgent`, and parameter names like `prompt`, `description`, `run_in_background` are self-documenting. The LLM infers usage from the schema — no verbose descriptions needed. Tool results reinforce correct usage with clear success/error messages.
+Tool names like `Agent`, `StopAgent`, and `AgentStatus`, and parameter names like `prompt`, `description`, `run_in_background` are self-documenting. The LLM infers usage from the schema — no verbose descriptions needed. Tool results reinforce correct usage with clear success/error messages.
 
-**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides — all with minimal token overhead.
+**Result:** foreground and background agents, custom agent types, per-model concurrency, cost tracking, steering, model overrides, agent status — all with minimal token overhead.
 
 ## Features
 
-- **Two tools** — `Agent` (spawn) and `StopAgent` (stop)
+- **Three tools** — `Agent` (spawn), `StopAgent` (stop), and `AgentStatus` (list agents)
 - **Manual spawn** — spawn agents from the `/agents` menu without asking the LLM. Full control over model, thinking, turns, and background mode.
 - **Foreground & background** — block or fire-and-forget with auto-delivered results
 - **Custom agent types** — define via `.md` files with YAML frontmatter (tools, model, thinking, turn limits)
@@ -98,7 +98,7 @@ Stop a running agent at any time via /agents command
 | Parameter | Required | Description |
 |---|---|---|
 | `prompt` | ✅ | The task for the sub-agent |
-| `description` | ✅ | Brief description for the LLM caller |
+| `description` | | Brief description for the LLM caller (optional — if omitted, derived from prompt) |
 | `agent` | | Type name — `general-purpose`, `Explore`, or any custom type you define (see [Custom Agent Types](#custom-agent-types)). The available values are **auto-populated** from `.md` files in your agent directories — drop a file, it appears in the enum. Set `hidden: true` in frontmatter to hide a type from this list (still callable by name). |
 | `run_in_background` | | Fire-and-forget; result delivered automatically when done |
 | `worktree_path` | | Absolute path to a git worktree. Agent runs in that worktree's context, discovers agents from its `.pi/agents/` directory, and displays a worktree label in the widget and menus. Path is validated against the parent repo's git common dir. |
@@ -389,6 +389,16 @@ Agent IDs can be discovered from:
 - The `StopAgent` error message, which lists all running agent IDs
 - The `/agents` menu's **Running agents** section
 
+## AgentStatus Tool
+
+List all agents with their type, short ID, and status. Returns a formatted list of all agents (running, queued, completed, stopped, error) and a nudge message reminding the LLM not to poll.
+
+**Usage:** The LLM calls `AgentStatus` to check on agents, but the extension nudges it to wait for automatic notifications instead of polling. This prevents wasteful repeated calls while still allowing the LLM to discover agents when needed.
+
+**Output format:** `type·short_id·status, type·short_id·status, ...`
+
+Example: `general-purpose·a1b2c3·running, Explore·d4e5f6·completed`
+
 ## Output Logs
 
 `/tmp/pi-agent-outputs/<agentId>.log` — append-only, human-readable, `tail -f` friendly. Every line is prefixed with an ISO 8601 timestamp:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-subagents-lite",
-  "version": "1.2.0",
+  "version": "1.3.0",
   "description": "Lightweight sub-agents for pi — spawn specialized agents with isolated sessions, tools, and models.",
   "keywords": [
     "pi-package",

package/src/agent-status.ts

@@ -0,0 +1,50 @@
+/**
+ * agent-status.ts — AgentStatus tool implementation.
+ *
+ * A lightweight informational tool that lists all agents (running, queued,
+ * completed, stopped, error) from the manager and returns a clear message
+ * about not polling for status.
+ */
+
+import type { ExtensionContext } from "@earendil-works/pi-coding-agent";
+import type { AgentRecord } from "./types.js";
+import { SHORT_ID_LENGTH } from "./types.js";
+import { getManager } from "./state.js";
+
+/**
+ * Format a single agent record as "type·short_id·status".
+ */
+function formatAgent(record: AgentRecord): string {
+  const shortId = record.id.slice(0, SHORT_ID_LENGTH);
+  return `${record.display.type}·${shortId}·${record.lifecycle.status}`;
+}
+
+/**
+ * Execute the AgentStatus tool.
+ *
+ * Returns a formatted list of all agents with their type, short ID, and status,
+ * followed by a nudge message telling the model not to poll.
+ */
+export async function executeAgentStatusTool(
+  _toolCallId: string,
+  _params: Record<string, unknown>,
+  _signal: AbortSignal | undefined,
+  _onUpdate: ((update: any) => void) | undefined,
+  _ctx: ExtensionContext,
+): Promise<any> {
+  const manager = getManager();
+  const agents = manager.listAgents();
+
+  const nudge = "Don't poll — you'll receive notifications when agents complete.";
+
+  if (agents.length === 0) {
+    return {
+      content: [{ type: "text", text: `No agents running or completed.\n\n${nudge}` }],
+    };
+  }
+
+  const formatted = agents.map(formatAgent).join(", ");
+  return {
+    content: [{ type: "text", text: `${formatted}\n\n${nudge}` }],
+  };
+}

package/src/index.ts

@@ -38,6 +38,7 @@ import { AgentWidget, type UICtx } from "./ui/agent-widget.js";
 import { showAgentsMainMenu } from "./menus.js";
 import { loadConfig } from "./config-io.js";
 import { executeAgentTool, executeStopAgentTool, toolCallListener, backgroundAgentIds, scheduleNudge } from "./tool-execution.js";
+import { executeAgentStatusTool } from "./agent-status.js";
 import { renderAgentToolCall, renderAgentToolResult, renderSubagentResult } from "./renderer.js";
 import {
   __config,
@@ -168,7 +169,7 @@ function registerAgentTool(pi: ExtensionAPI): void {
     label: "Agent",
     parameters: Type.Object({
       prompt: Type.String(),
-      description: Type.String(),
+      description: Type.Optional(Type.String()),
       agent: agentParam,
       run_in_background: Type.Optional(Type.Boolean()),
       worktree_path: Type.Optional(Type.String()),
@@ -211,6 +212,15 @@ export default function (pi: ExtensionAPI) {
     execute: executeStopAgentTool,
   });
 
+  // AgentStatus tool — stealth schema, list all agents and their statuses
+  // @ts-expect-error — description removed to save prompt tokens
+  pi.registerTool({
+    name: "AgentStatus",
+    label: "AgentStatus",
+    parameters: Type.Object({}),
+    execute: executeAgentStatusTool,
+  });
+
   // Message renderer — subagent-result (background agent completion)
   pi.registerMessageRenderer("subagent-result", (message, options, theme) =>
     renderSubagentResult(

package/src/tool-execution.ts

@@ -253,7 +253,7 @@ export async function executeAgentTool(
   }
 
   const prompt = params.prompt as string;
-  const description = params.description as string;
+  const description = (params.description as string | undefined) || prompt.split("\n")[0].slice(0, 80) || prompt.slice(0, 80);
   const runInBackground = params.run_in_background as boolean | undefined;
   const maxTurns = params.max_turns as number | undefined ?? getAgentConfig(resolvedType)?.maxTurns;