@poncho-ai/harness 0.16.1 → 0.18.0

package/src/harness.ts

@@ -29,6 +29,8 @@ import { addPromptCacheBreakpoints } from "./prompt-cache.js";
 import { jsonSchemaToZod } from "./schema-converter.js";
 import type { SkillMetadata } from "./skill-context.js";
 import { createSkillTools, normalizeScriptPolicyPath } from "./skill-tools.js";
+import { createSubagentTools } from "./subagent-tools.js";
+import type { SubagentManager } from "./subagent-manager.js";
 import { LatitudeTelemetry } from "@latitude-data/telemetry";
 import { diag, DiagLogLevel } from "@opentelemetry/api";
 import {
@@ -502,6 +504,7 @@ export class AgentHarness {
 
   private parsedAgent?: ParsedAgent;
   private mcpBridge?: LocalMcpBridge;
+  private subagentManager?: SubagentManager;
 
   private resolveToolAccess(toolName: string): ToolAccess {
     const tools = this.loadedConfig?.tools;
@@ -547,6 +550,21 @@ export class AgentHarness {
     }
   }
 
+  unregisterTools(names: string[]): void {
+    this.dispatcher.unregisterMany(names);
+  }
+
+  setSubagentManager(manager: SubagentManager): void {
+    this.subagentManager = manager;
+    this.dispatcher.registerMany(
+      createSubagentTools(
+        manager,
+        () => this._currentRunConversationId,
+        () => this._currentRunOwnerId ?? "anonymous",
+      ),
+    );
+  }
+
   private registerConfiguredBuiltInTools(config: PonchoConfig | undefined): void {
     for (const tool of createDefaultTools(this.workingDir)) {
       if (this.isToolEnabled(tool.name)) {
@@ -1060,6 +1078,8 @@ export class AgentHarness {
 
   /** Conversation ID of the currently executing run (set during run, cleared after). */
   private _currentRunConversationId?: string;
+  /** Owner ID of the currently executing run (used by subagent tools). */
+  private _currentRunOwnerId?: string;
 
   get browserSession(): unknown {
     return this._browserSession;
@@ -1180,8 +1200,12 @@ export class AgentHarness {
     }
     await this.refreshSkillsIfChanged();
 
-    // Track which conversation this run belongs to so browser tools resolve the right session
+    // Track which conversation/owner this run belongs to so browser & subagent tools resolve correctly
     this._currentRunConversationId = input.conversationId;
+    const ownerParam = input.parameters?.__ownerId;
+    if (typeof ownerParam === "string") {
+      this._currentRunOwnerId = ownerParam;
+    }
 
     const agent = this.parsedAgent as ParsedAgent;
     const runId = `run_${randomUUID()}`;
@@ -1658,15 +1682,14 @@ ${boundedMainMemory.trim()}`
             isEnabled: telemetryEnabled && !!this.latitudeTelemetry,
           },
         });
-        // Stream text chunks — enforce overall run timeout per chunk.
-        // The top-of-step timeout check cannot fire while we are
-        // blocked inside the textStream async iterator, so we race
-        // each next() call against the remaining time budget.
+        // Stream full response — use fullStream to get visibility into
+        // tool-call generation (tool-input-start) in addition to text deltas.
+        // Enforce overall run timeout per part.
         let fullText = "";
         let chunkCount = 0;
         const hasRunTimeout = timeoutMs > 0;
         const streamDeadline = hasRunTimeout ? start + timeoutMs : 0;
-        const textIterator = result.textStream[Symbol.asyncIterator]();
+        const fullStreamIterator = result.fullStream[Symbol.asyncIterator]();
         try {
           while (true) {
             if (isCancelled()) {
@@ -1690,21 +1713,17 @@ ${boundedMainMemory.trim()}`
                 return;
               }
             }
-            // Use a shorter timeout for the first chunk to detect
-            // non-responsive models quickly instead of waiting minutes.
-            // When no run timeout is set, only the first chunk is time-bounded.
             const remaining = hasRunTimeout ? streamDeadline - now() : Infinity;
             const timeout = chunkCount === 0
               ? Math.min(remaining, FIRST_CHUNK_TIMEOUT_MS)
               : hasRunTimeout ? remaining : 0;
-            let nextChunk: IteratorResult<string> | null;
+            let nextPart: IteratorResult<(typeof result.fullStream) extends AsyncIterable<infer T> ? T : never> | null;
             if (timeout <= 0 && chunkCount > 0) {
-              // No time budget — await the stream directly (development mode, no run timeout)
-              nextChunk = await textIterator.next();
+              nextPart = await fullStreamIterator.next();
             } else {
               let timer: ReturnType<typeof setTimeout> | undefined;
-              nextChunk = await Promise.race([
-                textIterator.next(),
+              nextPart = await Promise.race([
+                fullStreamIterator.next(),
                 new Promise<null>((resolve) => {
                   timer = setTimeout(() => resolve(null), timeout);
                 }),
@@ -1712,16 +1731,14 @@ ${boundedMainMemory.trim()}`
               clearTimeout(timer);
             }
 
-            if (nextChunk === null) {
+            if (nextPart === null) {
               const isFirstChunk = chunkCount === 0;
               console.error(
                 `[poncho][harness] Stream timeout waiting for ${isFirstChunk ? "first" : "next"} chunk: model="${modelName}", step=${step}, chunks=${chunkCount}, elapsed=${now() - start}ms`,
               );
               if (isFirstChunk) {
-                // Throw so the step-level retry logic can handle it.
                 throw new FirstChunkTimeoutError(modelName, FIRST_CHUNK_TIMEOUT_MS);
               }
-              // Mid-stream timeout: not retryable (partial response would be lost)
               yield pushEvent({
                 type: "run:error",
                 runId,
@@ -1733,14 +1750,20 @@ ${boundedMainMemory.trim()}`
               return;
             }
 
-            if (nextChunk.done) break;
-            chunkCount += 1;
-            fullText += nextChunk.value;
-            yield pushEvent({ type: "model:chunk", content: nextChunk.value });
+            if (nextPart.done) break;
+            const part = nextPart.value;
+
+            if (part.type === "text-delta") {
+              chunkCount += 1;
+              fullText += part.text;
+              yield pushEvent({ type: "model:chunk", content: part.text });
+            } else if (part.type === "tool-input-start") {
+              chunkCount += 1;
+              yield pushEvent({ type: "tool:generating", tool: part.toolName, toolCallId: part.id });
+            }
           }
         } finally {
-          // Best-effort cleanup of the underlying stream/connection.
-          textIterator.return?.(undefined)?.catch?.(() => {});
+          fullStreamIterator.return?.(undefined)?.catch?.(() => {});
         }
 
         if (isCancelled()) {
@@ -1749,8 +1772,6 @@ ${boundedMainMemory.trim()}`
         }
 
       // Check finish reason for error / abnormal completions.
-      // textStream silently swallows model-level errors – they only
-      // surface through finishReason (or fullStream, which we don't use).
       const finishReason = await result.finishReason;
 
       if (finishReason === "error") {
@@ -1859,6 +1880,7 @@ ${boundedMainMemory.trim()}`
         workingDir: this.workingDir,
         parameters: input.parameters ?? {},
         abortSignal: input.abortSignal,
+        conversationId: input.conversationId,
       };
 
       const toolResultsForModel: Array<{
@@ -1995,11 +2017,14 @@ ${boundedMainMemory.trim()}`
           });
         } else {
           span?.end({ result: { value: result.output ?? null, isError: false } });
+          const serialized = JSON.stringify(result.output ?? null);
+          const outputTokenEstimate = Math.ceil(serialized.length / 4);
           yield pushEvent({
             type: "tool:completed",
             tool: result.tool,
             output: result.output,
             duration: now() - batchStart,
+            outputTokenEstimate,
           });
 
           const { mediaItems, strippedOutput } = extractMediaFromToolOutput(result.output);

package/src/index.ts

@@ -14,5 +14,7 @@ export * from "./state.js";
 export * from "./upload-store.js";
 export * from "./telemetry.js";
 export * from "./tool-dispatcher.js";
+export * from "./subagent-manager.js";
+export * from "./subagent-tools.js";
 export { defineTool } from "@poncho-ai/sdk";
 export type { ToolDefinition } from "@poncho-ai/sdk";

package/src/latitude-capture.ts

@@ -1,14 +1,3 @@
-/**
- * Latitude telemetry integration for Vercel AI SDK
- *
- * TODO: Implement proper Vercel AI SDK telemetry integration using:
- * - LatitudeTelemetry.capture() wrapper around streamText()
- * - experimental_telemetry: { isEnabled: true } in streamText() options
- *
- * This requires @latitude-data/telemetry package which has official
- * Vercel AI SDK support.
- */
-
 export interface LatitudeCaptureConfig {
   apiKeyEnv?: string;
   projectIdEnv?: string;
@@ -17,8 +6,9 @@ export interface LatitudeCaptureConfig {
 }
 
 /**
- * Placeholder for Latitude telemetry integration
- * This will be properly implemented once Vercel AI SDK migration is complete
+ * Reads and validates Latitude telemetry configuration from environment
+ * variables. The actual telemetry capture is handled by LatitudeTelemetry
+ * from @latitude-data/telemetry in harness.ts (via runWithTelemetry).
  */
 export class LatitudeCapture {
   private readonly apiKey?: string;

package/src/mcp.ts

@@ -12,6 +12,7 @@ export interface RemoteMcpServerConfig {
     type: "bearer";
     tokenEnv?: string;
   };
+  headers?: Record<string, string>;
   timeoutMs?: number;
   reconnectAttempts?: number;
   reconnectDelayMs?: number;
@@ -46,18 +47,26 @@ class StreamableHttpMcpRpcClient implements McpRpcClient {
   private readonly endpoint: string;
   private readonly timeoutMs: number;
   private readonly bearerToken?: string;
+  private readonly customHeaders: Record<string, string>;
   private idCounter = 1;
   private initialized = false;
   private sessionId?: string;
 
-  constructor(endpoint: string, timeoutMs = 10_000, bearerToken?: string) {
+  constructor(
+    endpoint: string,
+    timeoutMs = 10_000,
+    bearerToken?: string,
+    customHeaders?: Record<string, string>,
+  ) {
     this.endpoint = endpoint;
     this.timeoutMs = timeoutMs;
     this.bearerToken = bearerToken;
+    this.customHeaders = customHeaders ?? {};
   }
 
   private buildHeaders(accept: string): Record<string, string> {
     const headers: Record<string, string> = {
+      ...this.customHeaders,
       "Content-Type": "application/json",
       Accept: accept,
     };
@@ -367,6 +376,7 @@ export class LocalMcpBridge {
           server.url,
           server.timeoutMs ?? 10_000,
           server.auth?.tokenEnv ? process.env[server.auth.tokenEnv] : undefined,
+          server.headers,
         ),
       );
     }

package/src/state.ts

@@ -38,12 +38,22 @@ export interface Conversation {
   }>;
   ownerId: string;
   tenantId: string | null;
+  contextTokens?: number;
+  contextWindow?: number;
+  parentConversationId?: string;
+  subagentMeta?: {
+    task: string;
+    status: "running" | "completed" | "error" | "stopped";
+    result?: import("@poncho-ai/sdk").RunResult;
+    error?: import("@poncho-ai/sdk").AgentFailure;
+  };
   createdAt: number;
   updatedAt: number;
 }
 
 export interface ConversationStore {
   list(ownerId?: string): Promise<Conversation[]>;
+  listSummaries(ownerId?: string): Promise<ConversationSummary[]>;
   get(conversationId: string): Promise<Conversation | undefined>;
   create(ownerId?: string, title?: string): Promise<Conversation>;
   update(conversation: Conversation): Promise<void>;
@@ -213,13 +223,30 @@ export class InMemoryConversationStore implements ConversationStore {
     }
   }
 
-  async list(ownerId = DEFAULT_OWNER): Promise<Conversation[]> {
+  async list(ownerId?: string): Promise<Conversation[]> {
     this.purgeExpired();
     return Array.from(this.conversations.values())
-      .filter((conversation) => conversation.ownerId === ownerId)
+      .filter((conversation) => !ownerId || conversation.ownerId === ownerId)
       .sort((a, b) => b.updatedAt - a.updatedAt);
   }
 
+  async listSummaries(ownerId?: string): Promise<ConversationSummary[]> {
+    this.purgeExpired();
+    return Array.from(this.conversations.values())
+      .filter((c) => !ownerId || c.ownerId === ownerId)
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .map((c) => ({
+        conversationId: c.conversationId,
+        title: c.title,
+        updatedAt: c.updatedAt,
+        createdAt: c.createdAt,
+        ownerId: c.ownerId,
+        parentConversationId: c.parentConversationId,
+        messageCount: c.messages.length,
+        hasPendingApprovals: Array.isArray(c.pendingApprovals) && c.pendingApprovals.length > 0,
+      }));
+  }
+
   async get(conversationId: string): Promise<Conversation | undefined> {
     this.purgeExpired();
     return this.conversations.get(conversationId);
@@ -266,14 +293,29 @@ export class InMemoryConversationStore implements ConversationStore {
   }
 }
 
+export type ConversationSummary = {
+  conversationId: string;
+  title: string;
+  updatedAt: number;
+  createdAt?: number;
+  ownerId: string;
+  parentConversationId?: string;
+  messageCount?: number;
+  hasPendingApprovals?: boolean;
+};
+
 type ConversationStoreFile = {
   schemaVersion: string;
   conversations: Array<{
     conversationId: string;
     title: string;
     updatedAt: number;
+    createdAt?: number;
     ownerId: string;
     fileName: string;
+    parentConversationId?: string;
+    messageCount?: number;
+    hasPendingApprovals?: boolean;
   }>;
 };
 
@@ -342,8 +384,12 @@ class FileConversationStore implements ConversationStore {
           conversationId: conversation.conversationId,
           title: conversation.title,
           updatedAt: conversation.updatedAt,
+          createdAt: conversation.createdAt,
           ownerId: conversation.ownerId,
           fileName: entry.name,
+          parentConversationId: conversation.parentConversationId,
+          messageCount: conversation.messages.length,
+          hasPendingApprovals: Array.isArray(conversation.pendingApprovals) && conversation.pendingApprovals.length > 0,
         });
       }
     } catch {
@@ -369,6 +415,17 @@ class FileConversationStore implements ConversationStore {
       for (const conversation of parsed.conversations ?? []) {
         this.conversations.set(conversation.conversationId, conversation);
       }
+      // Rebuild if any entry is from an older index format (missing messageCount)
+      let needsRebuild = false;
+      for (const entry of this.conversations.values()) {
+        if (entry.messageCount === undefined) {
+          needsRebuild = true;
+          break;
+        }
+      }
+      if (needsRebuild) {
+        await this.rebuildIndexFromFiles();
+      }
     } catch {
       await this.rebuildIndexFromFiles();
     }
@@ -385,18 +442,22 @@ class FileConversationStore implements ConversationStore {
         conversationId: conversation.conversationId,
         title: conversation.title,
         updatedAt: conversation.updatedAt,
+        createdAt: conversation.createdAt,
         ownerId: conversation.ownerId,
         fileName,
+        parentConversationId: conversation.parentConversationId,
+        messageCount: conversation.messages.length,
+        hasPendingApprovals: Array.isArray(conversation.pendingApprovals) && conversation.pendingApprovals.length > 0,
       });
       await this.writeIndex();
     });
     await this.writing;
   }
 
-  async list(ownerId = DEFAULT_OWNER): Promise<Conversation[]> {
+  async list(ownerId?: string): Promise<Conversation[]> {
     await this.ensureLoaded();
     const summaries = Array.from(this.conversations.values())
-      .filter((conversation) => conversation.ownerId === ownerId)
+      .filter((conversation) => !ownerId || conversation.ownerId === ownerId)
       .sort((a, b) => b.updatedAt - a.updatedAt);
     const conversations: Conversation[] = [];
     for (const summary of summaries) {
@@ -408,6 +469,23 @@ class FileConversationStore implements ConversationStore {
     return conversations;
   }
 
+  async listSummaries(ownerId?: string): Promise<ConversationSummary[]> {
+    await this.ensureLoaded();
+    return Array.from(this.conversations.values())
+      .filter((c) => !ownerId || c.ownerId === ownerId)
+      .sort((a, b) => b.updatedAt - a.updatedAt)
+      .map((c) => ({
+        conversationId: c.conversationId,
+        title: c.title,
+        updatedAt: c.updatedAt,
+        createdAt: c.createdAt,
+        ownerId: c.ownerId,
+        parentConversationId: c.parentConversationId,
+        messageCount: c.messageCount,
+        hasPendingApprovals: c.hasPendingApprovals,
+      }));
+  }
+
   async get(conversationId: string): Promise<Conversation | undefined> {
     await this.ensureLoaded();
     const summary = this.conversations.get(conversationId);
@@ -573,7 +651,11 @@ type ConversationMeta = {
   conversationId: string;
   title: string;
   updatedAt: number;
+  createdAt?: number;
   ownerId: string;
+  parentConversationId?: string;
+  messageCount?: number;
+  hasPendingApprovals?: boolean;
 };
 
 abstract class KeyValueConversationStoreBase implements ConversationStore {
@@ -669,11 +751,15 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
     }
   }
 
-  async list(ownerId = DEFAULT_OWNER): Promise<Conversation[]> {
+  async list(ownerId?: string): Promise<Conversation[]> {
     const kv = await this.client();
     if (!kv) {
       return await this.memoryFallback.list(ownerId);
     }
+    if (!ownerId) {
+      // KV stores index per-owner; cross-owner listing not supported
+      return [];
+    }
     const ids = await this.getOwnerConversationIds(ownerId);
     const conversations: Conversation[] = [];
     for (const id of ids) {
@@ -690,6 +776,34 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
     return conversations.sort((a, b) => b.updatedAt - a.updatedAt);
   }
 
+  async listSummaries(ownerId?: string): Promise<ConversationSummary[]> {
+    const kv = await this.client();
+    if (!kv) {
+      return await this.memoryFallback.listSummaries(ownerId);
+    }
+    if (!ownerId) {
+      return [];
+    }
+    const ids = await this.getOwnerConversationIds(ownerId);
+    const summaries: ConversationSummary[] = [];
+    for (const id of ids) {
+      const meta = await this.getConversationMeta(id);
+      if (meta && meta.ownerId === ownerId) {
+        summaries.push({
+          conversationId: meta.conversationId,
+          title: meta.title,
+          updatedAt: meta.updatedAt,
+          createdAt: meta.createdAt,
+          ownerId: meta.ownerId,
+          parentConversationId: meta.parentConversationId,
+          messageCount: meta.messageCount,
+          hasPendingApprovals: meta.hasPendingApprovals,
+        });
+      }
+    }
+    return summaries.sort((a, b) => b.updatedAt - a.updatedAt);
+  }
+
   async get(conversationId: string): Promise<Conversation | undefined> {
     const kv = await this.client();
     if (!kv) {
@@ -741,7 +855,11 @@ abstract class KeyValueConversationStoreBase implements ConversationStore {
         conversationId: nextConversation.conversationId,
         title: nextConversation.title,
         updatedAt: nextConversation.updatedAt,
+        createdAt: nextConversation.createdAt,
         ownerId: nextConversation.ownerId,
+        parentConversationId: nextConversation.parentConversationId,
+        messageCount: nextConversation.messages.length,
+        hasPendingApprovals: Array.isArray(nextConversation.pendingApprovals) && nextConversation.pendingApprovals.length > 0,
       } satisfies ConversationMeta),
       this.ttl,
     );

package/src/subagent-manager.ts

@@ -0,0 +1,30 @@
+import type { AgentFailure, Message, RunResult } from "@poncho-ai/sdk";
+
+export interface SubagentResult {
+  subagentId: string;
+  status: "completed" | "error" | "stopped";
+  latestMessages?: Message[];
+  result?: RunResult;
+  error?: AgentFailure;
+}
+
+export interface SubagentSummary {
+  subagentId: string;
+  task: string;
+  status: string;
+  messageCount: number;
+}
+
+export interface SubagentManager {
+  spawn(opts: {
+    task: string;
+    parentConversationId: string;
+    ownerId: string;
+  }): Promise<SubagentResult>;
+
+  sendMessage(subagentId: string, message: string): Promise<SubagentResult>;
+
+  stop(subagentId: string): Promise<void>;
+
+  list(parentConversationId: string): Promise<SubagentSummary[]>;
+}

package/src/subagent-tools.ts

@@ -0,0 +1,160 @@
+import { defineTool, type Message, type ToolDefinition, getTextContent } from "@poncho-ai/sdk";
+import type { SubagentManager, SubagentResult } from "./subagent-manager.js";
+
+const LAST_MESSAGES_TO_RETURN = 10;
+
+const summarizeResult = (r: SubagentResult): Record<string, unknown> => {
+  const summary: Record<string, unknown> = {
+    subagentId: r.subagentId,
+    status: r.status,
+  };
+  if (r.result) {
+    summary.result = {
+      status: r.result.status,
+      response: r.result.response,
+      steps: r.result.steps,
+      duration: r.result.duration,
+    };
+  }
+  if (r.error) {
+    summary.error = r.error;
+  }
+  if (r.latestMessages && r.latestMessages.length > 0) {
+    summary.latestMessages = r.latestMessages
+      .slice(-LAST_MESSAGES_TO_RETURN)
+      .map((m: Message) => ({
+        role: m.role,
+        content: getTextContent(m).slice(0, 2000),
+      }));
+  }
+  return summary;
+};
+
+export const createSubagentTools = (
+  manager: SubagentManager,
+  getConversationId: () => string | undefined,
+  getOwnerId: () => string,
+): ToolDefinition[] => [
+  defineTool({
+    name: "spawn_subagent",
+    description:
+      "Spawn a subagent to work on a task and wait for it to finish. The subagent is a full copy of " +
+      "yourself running in its own conversation context with access to the same tools (except memory writes). " +
+      "This call blocks until the subagent completes and returns its result.\n\n" +
+      "Guidelines:\n" +
+      "- Use subagents to parallelize work: call spawn_subagent multiple times in one response for independent sub-tasks -- they run concurrently.\n" +
+      "- Prefer doing work yourself for simple or quick tasks. Spawn subagents for substantial, self-contained work.\n" +
+      "- The subagent has no memory of your conversation -- write thorough, self-contained instructions in the task.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        task: {
+          type: "string",
+          description:
+            "Thorough, self-contained instructions for the subagent. Include all relevant context, " +
+            "goals, and constraints -- the subagent starts with zero prior conversation history.",
+        },
+      },
+      required: ["task"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const task = typeof input.task === "string" ? input.task : "";
+      if (!task.trim()) {
+        return { error: "task is required" };
+      }
+      const conversationId = getConversationId();
+      if (!conversationId) {
+        return { error: "no active conversation to spawn subagent from" };
+      }
+      const result = await manager.spawn({
+        task: task.trim(),
+        parentConversationId: conversationId,
+        ownerId: getOwnerId(),
+      });
+      return summarizeResult(result);
+    },
+  }),
+
+  defineTool({
+    name: "message_subagent",
+    description:
+      "Send a follow-up message to a completed or stopped subagent and wait for it to finish. " +
+      "This restarts the subagent with the new message and blocks until it completes. " +
+      "Only works when the subagent is not currently running.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subagent_id: {
+          type: "string",
+          description: "The subagent ID (from spawn_subagent result or list_subagents).",
+        },
+        message: {
+          type: "string",
+          description: "The follow-up instructions or message to send.",
+        },
+      },
+      required: ["subagent_id", "message"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const subagentId = typeof input.subagent_id === "string" ? input.subagent_id : "";
+      const message = typeof input.message === "string" ? input.message : "";
+      if (!subagentId || !message.trim()) {
+        return { error: "subagent_id and message are required" };
+      }
+      const result = await manager.sendMessage(subagentId, message.trim());
+      return summarizeResult(result);
+    },
+  }),
+
+  defineTool({
+    name: "stop_subagent",
+    description:
+      "Stop a running subagent. The subagent's conversation is preserved but it will stop processing. " +
+      "Use this to cancel work that is no longer needed.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        subagent_id: {
+          type: "string",
+          description: "The subagent ID (from spawn_subagent result or list_subagents).",
+        },
+      },
+      required: ["subagent_id"],
+      additionalProperties: false,
+    },
+    handler: async (input) => {
+      const subagentId = typeof input.subagent_id === "string" ? input.subagent_id : "";
+      if (!subagentId) {
+        return { error: "subagent_id is required" };
+      }
+      await manager.stop(subagentId);
+      return { message: `Subagent "${subagentId}" has been stopped.` };
+    },
+  }),
+
+  defineTool({
+    name: "list_subagents",
+    description:
+      "List all subagents that have been spawned in this conversation. Returns each subagent's ID, " +
+      "original task, current status, and message count. Use this to look up subagent IDs before " +
+      "calling message_subagent or stop_subagent.",
+    inputSchema: {
+      type: "object",
+      properties: {},
+      additionalProperties: false,
+    },
+    handler: async () => {
+      const conversationId = getConversationId();
+      if (!conversationId) {
+        return { error: "no active conversation" };
+      }
+      const subagents = await manager.list(conversationId);
+      if (subagents.length === 0) {
+        return { message: "No subagents have been spawned in this conversation." };
+      }
+      return { subagents };
+    },
+  }),
+];