@ai-setting/roy-agent-core 1.0.0

package/src/env/task/delegate/delegate-tool.ts

@@ -0,0 +1,1014 @@
+/**
+ * @fileoverview delegate_task Tool
+ * 
+ * 基于 agent-core 的 delegate_task 实现
+ * 参考: packages/core/src/core/environment/expend/task/task-tool.ts
+ * 
+ * 功能：
+ * - 委派子Agent执行任务（同步/后台模式）
+ * - 支持多种 subagent 类型
+ * - 支持任务关联（task_id）
+ * - 发布 EnvEvent 事件
+ */
+
+import { z } from "zod";
+import type { Tool, ToolContext, ToolResult } from "../../tool/types";
+import type { TaskComponent } from "../task-component";
+import type { SessionComponent } from "../../session/session-component";
+import { createLogger } from "../../log-trace/logger";
+import { 
+  TaskEventTypes, 
+  createTaskStartedPayload, 
+  createTaskProgressPayload, 
+  createTaskCompletedPayload 
+} from "./task-events";
+import { env } from "process";
+import { AgentComponent } from "../../agent";
+
+// Hook 机制
+import { globalHookManager } from "../../hook/global-hook-manager";
+import { TaskHookPoints } from "../hooks";
+import type { TaskDelegateContext } from "../hooks/contexts";
+import type { TagService } from "../tag-service";
+
+const logger = createLogger("task:delegate");
+
+// ============================================================================
+// SubAgent Types (简化版)
+// ============================================================================
+
+export interface SubAgentSpec {
+  id: string;
+  name: string;
+  description: string;
+  mode: "subagent" | "primary" | "all";
+  promptOverride?: string;
+  /** 允许的工具列表（白名单） */
+  allowedTools?: string[];
+  /** 拒绝的工具列表（黑名单） */
+  deniedTools?: string[];
+}
+
+export const builtInSubAgents: SubAgentSpec[] = [
+  {
+    id: "general",
+    name: "general",
+    mode: "subagent",
+    description: "General-purpose agent for researching complex questions and executing multi-step tasks.",
+    promptOverride: `You are a subagent created by the main agent to handle a specific task.
+
+## Your Role
+- You were created to handle: {task_description}
+- Complete this task. That's your entire purpose.
+- You are NOT the main agent. Don't try to be.
+
+## Task Context Awareness (Required Behavior)
+
+**IMPORTANT: Before starting any work, you MUST gather task context to avoid working with outdated or missing information.**
+
+1. **Read task details first**: Use \`task_get\` to read the task's:
+   - \`description\`: Detailed description of what needs to be done
+   - \`goals_and_expected_deliverables\`: Clear success criteria and expected outputs
+   - \`current_status\`: Current work progress
+   - \`parent_task_id\`: If exists, this is a sub-task
+
+2. **Read recent operations**: Use \`task_operation_list\` to get the last ~15 operation records
+   - These provide history, progress, decisions, and context from previous work
+
+3. **Read parent task context** (if \`parent_task_id\` exists):
+   - Use \`task_get\` to read the parent task's description and goals
+   - Use \`task_operation_list\` to get parent's recent operations
+   - This forms the overall task background and ensures alignment
+
+**Why this matters**: 
+- The main agent may have made critical decisions recorded in operations
+- Parent task goals provide the broader context for your sub-task
+- Without this context, you risk working on wrong/outdated goals
+
+## Rules
+1. **Gather context first** - Always read task details and operations before starting
+2. **Stay focused** - Do your assigned task, nothing else
+3. **Complete the task** - Your final message will be automatically reported to the main agent
+4. **Don't initiate** - No heartbeats, no proactive actions, no side quests
+5. **Be ephemeral** - You may be terminated after task completion. That's fine.
+6. **No nested delegation** - Do NOT use delegate_task or stop_task tools. Complete the task yourself.
+
+## Execution
+- Use the available tools to complete the task
+- If you need more information, ask the main agent through the result
+- Return a clear summary of what you did and the results`,
+    // Prevent nested delegation by denying delegate_task and stop_task
+    deniedTools: ["delegate_task", "stop_task"],
+  },
+  {
+    id: "explore",
+    name: "explore",
+    mode: "subagent",
+    description: "Fast agent specialized for exploring codebases, finding files, and searching for patterns.",
+    allowedTools: ["glob", "grep", "read", "bash"],
+    deniedTools: ["delegate_task", "stop_task"],
+  },
+  {
+    id: "file_agent",
+    name: "file_agent",
+    mode: "subagent",
+    description: "File operation expert, skilled at reading, writing, searching and organizing files.",
+    allowedTools: ["file_read", "file_write", "file_glob", "grep", "glob", "read"],
+    deniedTools: ["delegate_task", "stop_task"],
+  },
+  {
+    id: "web_search_agent",
+    name: "web_search_agent",
+    mode: "subagent",
+    description: "Web search expert, using Exa search engine to get latest information.",
+    allowedTools: ["exa_web_search_exa"],
+    deniedTools: ["delegate_task", "stop_task"],
+  },
+];
+
+function getSubAgentSpec(id: string): SubAgentSpec | undefined {
+  return builtInSubAgents.find((agent) => agent.id === id);
+}
+
+function listSubAgents(): SubAgentSpec[] {
+  return [...builtInSubAgents];
+}
+
+function getSubAgentToolDescription(): string {
+  return builtInSubAgents.map((agent) => `- ${agent.id}: ${agent.description}`).join("\n");
+}
+
+// ============================================================================
+// SubAgent Registration Helper
+// ============================================================================
+
+/**
+ * 确保 subAgent 已注册到 AgentComponent
+ * 
+ * @param agentComponent AgentComponent 实例
+ * @param subagentType subAgent 类型（用作 agentName）
+ * @param basePrompt 基础 system prompt
+ * @param subAgent subAgent 配置（可能包含 allowedTools）
+ * @param deniedTools 拒绝的工具列表
+ * @returns 注册的 agent 实例
+ */
+function ensureSubAgentRegistered(
+  agentComponent: any,
+  subagentType: string,
+  basePrompt: string,
+  subAgent: SubAgentSpec | undefined,
+  deniedTools: string[]
+): any {
+  let agentInstance = agentComponent.getAgent(subagentType);
+  if (!agentInstance) {
+    const agentConfig: Record<string, unknown> = {
+      type: "sub",
+      systemPrompt: basePrompt,
+    };
+
+    // 添加 allowedTools（如果有）
+    if (subAgent?.allowedTools && subAgent.allowedTools.length > 0) {
+      agentConfig.allowedTools = subAgent.allowedTools;
+    }
+
+    // 添加 deniedTools（如果有）
+    if (deniedTools.length > 0) {
+      agentConfig.deniedTools = deniedTools;
+    }
+
+    agentInstance = agentComponent.registerAgent(subagentType, agentConfig as any);
+    logger.debug(`[delegate] Registered subagent: ${subagentType}`);
+  }
+  return agentInstance;
+}
+
+// ============================================================================
+// Tool Parameters Schema
+// ============================================================================
+
+export const DelegateToolParameters = z.object({
+  description: z.string().describe("A short (3-5 words) description of the task"),
+  prompt: z.string().describe("The task for the agent to perform"),
+  subagent_type: z
+    .string()
+    .describe("The type of specialized agent to use for this task")
+    .default("general"),
+  background: z
+    .boolean()
+    .describe("Whether to run the task in background. If true, returns immediately and notifies when complete (default: false)")
+    .default(false),
+  timeout: z
+    .number()
+    .describe("Task timeout in milliseconds. If set, task will be terminated after timeout (optional)")
+    .optional(),
+  cleanup: z
+    .enum(["delete", "keep"] as const)
+    .describe("Whether to delete sub session after completion. 'delete' removes the session, 'keep' retains it (default: keep)")
+    .default("keep")
+    .optional(),
+  task_id: z
+    .number()
+    .describe("Optional task ID to associate with this delegate task, for tracking in operation records")
+    .optional(),
+  reason: z
+    .string()
+    .describe("Brief reason for calling this tool (max 30 chars, e.g., 'Delegate refactor task')")
+    .optional(),
+});
+
+export type DelegateToolParams = z.infer<typeof DelegateToolParameters>;
+
+// ============================================================================
+// Delegate Tool Implementation
+// ============================================================================
+
+export interface DelegateToolResult {
+  tool: Tool;
+  backgroundTaskManager: BackgroundTaskManager;
+}
+
+export interface BackgroundTask {
+  id: string;
+  subSessionId: string;
+  parentSessionId: string;
+  description: string;
+  subagentType: string;
+  status: "pending" | "running" | "completed" | "failed" | "timeout" | "stopped";
+  createdAt: number;
+  startedAt?: number;
+  completedAt?: number;
+  result?: string;
+  error?: string;
+  progress?: number;
+  progressMessage?: string;
+  abortController?: AbortController;
+  taskId?: number; // 关联的任务ID
+}
+
+export interface CreateBackgroundTaskOptions {
+  parentSessionId: string;
+  description: string;
+  prompt: string;
+  subagentType: string;
+  timeout?: number;
+  cleanup?: "delete" | "keep";
+  taskId?: number;
+}
+
+const DEFAULT_TIMEOUT = 900000; // 15 minutes
+const PROGRESS_INTERVAL = 120000; // 2 minutes
+
+/**
+ * Background Task Manager (简化版)
+ * 
+ * 管理后台任务的创建、执行、状态跟踪
+ * 支持 EnvEvent 发布
+ */
+export class BackgroundTaskManager {
+  private tasks: Map<string, BackgroundTask> = new Map();
+  private progressTimers: Map<string, NodeJS.Timeout> = new Map();
+  private abortControllers: Map<string, AbortController> = new Map();
+
+  constructor(private env: any) {
+    // env 应该具有 pushEnvEvent 和 getComponent 方法
+  }
+
+  /**
+   * Get SessionComponent from env
+   */
+  private getSessionComponent(): any {
+    return this.env?.getComponent?.("session");
+  }
+
+  async createTask(options: CreateBackgroundTaskOptions): Promise<{ taskId: string; subSessionId: string }> {
+    const { parentSessionId, description, prompt, subagentType, timeout, cleanup, taskId } = options;
+
+    const taskIdGen = `task_${Date.now()}_${Math.random().toString(36).slice(2, 11)}`;
+
+    // Get SessionComponent
+    const sessionComponent = this.getSessionComponent();
+    if (!sessionComponent) {
+      throw new Error("SessionComponent not found");
+    }
+
+    // Create sub-session
+    const parentSession = await sessionComponent.get(parentSessionId);
+    if (!parentSession) {
+      throw new Error(`Parent session not found: ${parentSessionId}`);
+    }
+
+    const metadata: Record<string, unknown> = {
+      subagent_type: subagentType,
+      created_by: "subagent",
+      task_description: description,
+    };
+    if (taskId) {
+      metadata.task_id = taskId;
+    }
+
+    const subSession = await sessionComponent.create({
+      title: `${description} (@${subagentType} subagent)`,
+      metadata,
+    });
+
+    if (!subSession) {
+      throw new Error("Failed to create sub-session");
+    }
+
+    const abortController = new AbortController();
+
+    const task: BackgroundTask = {
+      id: taskIdGen,
+      subSessionId: subSession.id,
+      parentSessionId,
+      description,
+      subagentType,
+      status: "pending",
+      createdAt: Date.now(),
+      abortController,
+      taskId,
+    };
+    this.tasks.set(taskIdGen, task);
+    this.abortControllers.set(taskIdGen, abortController);
+
+    // Publish task.started event
+    this.publishEvent(TaskEventTypes.TASK_STARTED, createTaskStartedPayload(task, parentSessionId), parentSessionId);
+
+    // Start execution asynchronously
+    this.executeTask(taskIdGen, prompt, timeout, cleanup, parentSessionId).catch((err) => {
+      logger.error(`[BackgroundTaskManager] executeTask unhandled rejection`, {
+        taskId: taskIdGen,
+        error: err instanceof Error ? err.message : String(err),
+      });
+    });
+
+    return { taskId: taskIdGen, subSessionId: subSession.id };
+  }
+
+  private async executeTask(
+    taskId: string,
+    prompt: string,
+    timeout?: number,
+    cleanup?: "delete" | "keep",
+    parentSessionId?: string
+  ): Promise<void> {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      logger.warn(`[BackgroundTaskManager] executeTask: Task not found`, { taskId });
+      return;
+    }
+
+    task.status = "running";
+    task.startedAt = Date.now();
+
+    const timeoutMs = timeout || DEFAULT_TIMEOUT;
+    const abortController = this.abortControllers.get(taskId);
+
+    // Start progress reporter
+    this.startProgressReporter(taskId, parentSessionId || task.parentSessionId);
+
+    try {
+      const sessionComponent = this.getSessionComponent();
+      const subSession = await sessionComponent.get(task.subSessionId);
+      if (!subSession) {
+        throw new Error(`Sub session not found: ${task.subSessionId}`);
+      }
+
+      // Execute with timeout and abort support
+      const result = await this.executeWithAbort(subSession, prompt, timeoutMs, abortController?.signal);
+
+      if (abortController?.signal.aborted) {
+        logger.info(`[BackgroundTaskManager] Task was aborted`, { taskId });
+        return;
+      }
+
+      task.status = "completed";
+      task.completedAt = Date.now();
+      task.result = result;
+
+      // Publish task.completed event
+      const executionTimeMs = task.completedAt - task.startedAt!;
+      this.publishEvent(
+        TaskEventTypes.TASK_COMPLETED,
+        createTaskCompletedPayload(task, parentSessionId || task.parentSessionId, executionTimeMs),
+        parentSessionId || task.parentSessionId
+      );
+
+      logger.info(`[BackgroundTaskManager] Task completed successfully`, {
+        taskId,
+        executionTimeMs,
+      });
+    } catch (error) {
+      const errorMessage = error instanceof Error ? error.message : String(error);
+      const isStoppedError =
+        errorMessage.toLowerCase().includes("stopped") ||
+        errorMessage.toLowerCase().includes("aborted");
+
+      if (isStoppedError) {
+        task.status = "stopped";
+        // Publish task.stopped event
+        this.publishEvent(
+          TaskEventTypes.TASK_STOPPED,
+          createTaskCompletedPayload(task, parentSessionId || task.parentSessionId, 
+            task.completedAt! - task.startedAt!),
+          parentSessionId || task.parentSessionId
+        );
+      } else if (errorMessage.includes("timeout")) {
+        task.status = "timeout";
+        // Publish task.timeout event
+        this.publishEvent(
+          TaskEventTypes.TASK_TIMEOUT,
+          createTaskCompletedPayload(task, parentSessionId || task.parentSessionId,
+            task.completedAt! - task.startedAt!),
+          parentSessionId || task.parentSessionId
+        );
+      } else {
+        task.status = "failed";
+        // Publish task.failed event
+        this.publishEvent(
+          TaskEventTypes.TASK_FAILED,
+          createTaskCompletedPayload(task, parentSessionId || task.parentSessionId,
+            task.completedAt! - task.startedAt!),
+          parentSessionId || task.parentSessionId
+        );
+      }
+      task.error = errorMessage;
+      task.completedAt = Date.now();
+
+      logger.error(`[BackgroundTaskManager] Task execution error`, {
+        taskId,
+        status: task.status,
+        error: errorMessage,
+      });
+    } finally {
+      // Stop progress reporter
+      this.stopProgressReporter(taskId);
+    }
+  }
+
+  private async executeWithAbort(
+    subSession: any,
+    prompt: string,
+    timeoutMs: number,
+    signal?: AbortSignal
+  ): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        reject(new Error(`Task execution timeout after ${timeoutMs}ms`));
+      }, timeoutMs);
+
+      signal?.addEventListener("abort", () => {
+        clearTimeout(timer);
+        reject(new Error("Task execution stopped"));
+      });
+
+      // Build full prompt
+      const metadata = subSession.info?.metadata || {};
+      const taskId = metadata.task_id as number | undefined;
+      const taskDescription = metadata.task_description as string || "";
+      const sessionId = subSession.id;
+      const subagentType = metadata.subagent_type as string || "general";
+
+      const subAgent = getSubAgentSpec(subagentType);
+      let basePrompt = subAgent?.promptOverride || `You are a subagent. Complete this task: {task_description}`;
+
+      // Get denied tools from subagent config
+      const deniedTools = subAgent?.deniedTools || [];
+
+      // Only replace valid placeholders
+      let fullPrompt = basePrompt.replace(/{task_description}/g, taskDescription || "N/A");
+
+      // Add session info and execution guidelines
+      fullPrompt += `
+
+---
+
+# Session Info
+- task_id: ${taskId || "N/A"}
+- session_id: ${sessionId}
+
+---
+
+## 用户指令
+${prompt}
+
+---
+
+## 执行规范
+- 使用可用工具完成任务
+- 返回清晰的任务执行结果摘要
+- 适时调用 task_operation_create 记录进展`;
+
+      // Get AgentComponent and ensure subagent is registered
+      const agentComponent = this.env?.getComponent?.("agent") as any;
+
+      if (!agentComponent) {
+        clearTimeout(timer);
+        reject(new Error("AgentComponent not found"));
+        return;
+      }
+
+      // 注册 subagent（使用公共函数）
+      ensureSubAgentRegistered(agentComponent, subagentType, basePrompt, subAgent, deniedTools);
+
+      // Execute using handle_query with agentType specified
+      this.env.handle_query?.(fullPrompt, {
+        sessionId: sessionId,
+        deniedTools: deniedTools.length > 0 ? deniedTools : undefined,
+        agentType: subagentType, // handle_query will use this agent
+      })
+        .then((result: string) => {
+          clearTimeout(timer);
+          resolve(result);
+        })
+        .catch((error: Error) => {
+          clearTimeout(timer);
+          reject(error);
+        });
+    });
+  }
+
+  /**
+   * Start progress reporter for a task
+   */
+  private startProgressReporter(taskId: string, parentSessionId: string): void {
+    const timer = setInterval(() => {
+      const task = this.tasks.get(taskId);
+      if (!task || task.status !== "running") {
+        this.stopProgressReporter(taskId);
+        return;
+      }
+
+      // Update progress
+      if (task.startedAt) {
+        const elapsedMs = Date.now() - task.startedAt;
+        task.progress = Math.min(95, Math.floor((elapsedMs / PROGRESS_INTERVAL) * 100));
+      }
+
+      // Publish progress event
+      this.publishEvent(
+        TaskEventTypes.TASK_PROGRESS,
+        createTaskProgressPayload(task, parentSessionId),
+        parentSessionId
+      );
+    }, PROGRESS_INTERVAL);
+
+    this.progressTimers.set(taskId, timer);
+  }
+
+  /**
+   * Stop progress reporter for a task
+   */
+  private stopProgressReporter(taskId: string): void {
+    const timer = this.progressTimers.get(taskId);
+    if (timer) {
+      clearInterval(timer);
+      this.progressTimers.delete(taskId);
+    }
+  }
+
+  /**
+   * Publish an event to the environment
+   */
+  private publishEvent<T>(type: string, payload: T, triggerSessionId?: string): void {
+    if (this.env?.pushEnvEvent) {
+      this.env.pushEnvEvent({
+        type,
+        metadata: {
+          trigger_session_id: triggerSessionId,
+          source: "task.delegate",
+        },
+        payload,
+      });
+      logger.info(`[BackgroundTaskManager] Event published: ${type}`, { payload });
+    }
+  }
+
+  stopTask(taskId: string): { success: boolean; task?: BackgroundTask; message: string } {
+    const task = this.tasks.get(taskId);
+    if (!task) {
+      return { success: false, message: "Task not found" };
+    }
+
+    if (task.status === "completed" || task.status === "failed" || task.status === "stopped" || task.status === "timeout") {
+      return {
+        success: false,
+        task,
+        message: `Cannot stop task with status: ${task.status}`,
+      };
+    }
+
+    task.status = "stopped";
+    task.abortController?.abort();
+    task.completedAt = Date.now();
+
+    // Publish task.stopped event
+    this.publishEvent(
+      TaskEventTypes.TASK_STOPPED,
+      createTaskCompletedPayload(task, task.parentSessionId, task.completedAt - task.startedAt!),
+      task.parentSessionId
+    );
+
+    return { success: true, task, message: "Task has been stopped" };
+  }
+
+  getTask(taskId: string): BackgroundTask | undefined {
+    return this.tasks.get(taskId);
+  }
+
+  listTasks(): BackgroundTask[] {
+    return Array.from(this.tasks.values());
+  }
+
+  /**
+   * Dispose and cleanup all resources
+   * Call this when shutting down to prevent process from hanging
+   */
+  dispose(): void {
+    // Clear all progress timers
+    for (const [taskId, timer] of this.progressTimers) {
+      clearInterval(timer);
+      logger.debug(`[BackgroundTaskManager] Cleared progress timer for task: ${taskId}`);
+    }
+    this.progressTimers.clear();
+
+    // Abort all running tasks
+    for (const [taskId, controller] of this.abortControllers) {
+      controller.abort();
+      logger.debug(`[BackgroundTaskManager] Aborted task: ${taskId}`);
+    }
+    this.abortControllers.clear();
+
+    // Clear all tasks
+    this.tasks.clear();
+
+    logger.info(`[BackgroundTaskManager] Disposed`);
+  }
+}
+
+/**
+ * Create delegate_task tool
+ */
+export function createDelegateTool(taskComponent: TaskComponent): Tool {
+  // Pass taskComponent.env instead of taskComponent, so BackgroundTaskManager
+  // can correctly call this.env.getComponent("session")
+  const env = (taskComponent as any).env;
+  const backgroundTaskManager = new BackgroundTaskManager(env);
+
+  const tool: Tool = {
+    name: "delegate_task",
+    description: `Launch a new sub-agent to handle complex, multistep tasks autonomously.
+
+Available agent types:
+${getSubAgentToolDescription()}
+
+When using the delegate_task tool, you must specify a subagent_type parameter to select which agent type to use.
+
+## When to use delegate_task:
+- When you need to perform complex, multi-step tasks that require independent execution
+- When you need to explore a codebase thoroughly (use "explore" subagent)
+- When you need to run long-running tasks without blocking the main agent (use background=true)
+
+## Parameters:
+- **description**: A short (3-5 words) description of the task
+- **prompt**: The task for the agent to perform
+- **subagent_type**: The type of specialized agent to use (e.g., "general", "explore")
+- **background**: Whether to run in background (default: false)
+- **timeout**: Task timeout in milliseconds (optional)
+- **task_id**: Optional task ID to associate with this delegate task
+
+## Synchronous vs Background mode:
+**Synchronous mode (default)**: Waits for subagent to complete and returns result directly
+**Background mode (background=true)**: Returns immediately with "accepted" status, runs independently`,
+    parameters: DelegateToolParameters,
+    execute: async (args: unknown, ctx: ToolContext): Promise<ToolResult> => {
+      const startTime = Date.now();
+      const params = DelegateToolParameters.parse(args);
+      const { description, prompt, subagent_type = "general", background = false, timeout, cleanup, task_id, reason } = params;
+
+      const parentSessionId = ctx.session_id || "default";
+
+      logger.info(`[delegate_task] Called: description=${description}, subagent_type=${subagent_type}, background=${background}, task_id=${task_id}`);
+
+      // Validate subagent_type
+      const subAgent = getSubAgentSpec(subagent_type);
+      if (!subAgent) {
+        return {
+          success: false,
+          output: "",
+          error: `Unknown subagent type: ${subagent_type}`,
+          metadata: { execution_time_ms: Date.now() - startTime },
+        };
+      }
+
+      // Get TagService from TaskComponent
+      const tagService = taskComponent.getTagService();
+
+      // Build initial prompt - hook will inject similar tasks info
+      let promptWithTaskInfo = prompt;
+
+      // Execute delegate:before Hook (can modify prompt, subagentType, etc.)
+      const delegateCtx: TaskDelegateContext = {
+        taskId: task_id,
+        prompt: promptWithTaskInfo,
+        subagentType: subagent_type,
+        background,
+        timeout,
+        cleanup,
+        reason,
+        tagService,
+      };
+
+      const hookCtx = {
+        component: { name: "task", version: "1.0.0" },
+        data: delegateCtx,
+        metadata: { sessionId: parentSessionId },
+        phase: "before" as const,
+        hookPoint: TaskHookPoints.DELEGATE_BEFORE,
+      };
+
+      await globalHookManager.execute(TaskHookPoints.DELEGATE_BEFORE, hookCtx, { sessionId: parentSessionId });
+
+      // Use potentially modified prompt from hook
+      promptWithTaskInfo = delegateCtx.prompt;
+
+      if (background) {
+        // Background execution
+        return await handleBackgroundTask(
+          taskComponent,
+          backgroundTaskManager,
+          parentSessionId,
+          description,
+          promptWithTaskInfo,
+          delegateCtx.subagentType,
+          delegateCtx.timeout,
+          delegateCtx.cleanup,
+          delegateCtx.taskId
+        );
+      } else {
+        // Synchronous execution
+        return await handleSyncTask(
+          taskComponent,
+          parentSessionId,
+          description,
+          promptWithTaskInfo,
+          delegateCtx.subagentType,
+          delegateCtx.timeout,
+          delegateCtx.taskId
+        );
+      }
+    },
+  };
+
+  return tool;
+}
+
+async function handleSyncTask(
+  taskComponent: TaskComponent,
+  parentSessionId: string,
+  description: string,
+  prompt: string,
+  subagentType: string,
+  timeout?: number,
+  taskId?: number
+): Promise<ToolResult> {
+  const startTime = Date.now();
+
+  try {
+    // Get SessionComponent from environment
+    const sessionComponent = (taskComponent as any).env?.getComponent?.("session") as SessionComponent | undefined;
+    if (!sessionComponent) {
+      return {
+        success: false,
+        output: "",
+        error: "SessionComponent not found",
+        metadata: { execution_time_ms: Date.now() - startTime },
+      };
+    }
+
+    const parentSession = await sessionComponent.get(parentSessionId);
+    if (!parentSession) {
+      return {
+        success: false,
+        output: "",
+        error: `Parent session not found: ${parentSessionId}`,
+        metadata: { execution_time_ms: Date.now() - startTime },
+      };
+    }
+
+    // Create sub-session
+    const metadata: Record<string, unknown> = {
+      subagent_type: subagentType,
+      created_by: "subagent",
+      task_description: description,
+    };
+    if (taskId) {
+      metadata.task_id = taskId;
+    }
+
+    const subSession = await sessionComponent.create({
+      parentID: parentSessionId,
+      title: `${description} (@${subagentType} subagent)`,
+      metadata,
+    });
+
+    if (!subSession) {
+      return {
+        success: false,
+        output: "",
+        error: "Failed to create sub-session",
+        metadata: { execution_time_ms: Date.now() - startTime },
+      };
+    }
+
+    // Build full prompt
+    const subAgent = getSubAgentSpec(subagentType);
+    let basePrompt = subAgent?.promptOverride || `You are a subagent. Complete this task: {task_description}`;
+
+    // Get denied tools from subagent config
+    const deniedTools = subAgent?.deniedTools || [];
+
+    // Only replace valid placeholders
+    let fullPrompt = basePrompt.replace(/{task_description}/g, description || "N/A");
+
+    fullPrompt += `
+
+---
+
+# Session Info
+- task_id: ${taskId || "N/A"}
+- session_id: ${subSession.id}
+
+---
+
+## 用户指令
+${prompt}
+
+---
+
+## 执行规范
+- 使用可用工具完成任务
+- 返回清晰的任务执行结果摘要
+- 适时调用 task_operation_create 记录进展`;
+
+    const agentComponent = (taskComponent as any).env?.getComponent?.("agent") as any;
+
+    if (!agentComponent) {
+      return {
+        success: false,
+        output: "",
+        error: "AgentComponent not found",
+        metadata: { execution_time_ms: Date.now() - startTime },
+      };
+    }
+
+    // 注册 subagent（使用公共函数）
+    ensureSubAgentRegistered(agentComponent, subagentType, basePrompt, subAgent, deniedTools);
+
+    // 使用 handle_query 执行，通过 agentType 指定 agent
+    const timeoutMs = timeout || DEFAULT_TIMEOUT;
+    let result: string;
+    
+    try {
+      result = await Promise.race([
+        (taskComponent as any).env?.handle_query?.(fullPrompt, { 
+          sessionId: subSession.id,
+          deniedTools: deniedTools.length > 0 ? deniedTools : undefined,
+          agentType: subagentType, // 传入 agentType，handle_query 会使用对应的 agent
+        }),
+        new Promise<string>((_, reject) =>
+          setTimeout(() => reject(new Error(`Task execution timeout after ${timeoutMs}ms`)), timeoutMs)
+        ),
+      ]);
+    } catch (error) {
+      result = error instanceof Error ? error.message : String(error);
+    }
+
+    // Add result message to session
+    await sessionComponent.addMessage(subSession.id, {
+      role: "assistant",
+      content: result,
+    });
+
+    return {
+      success: true,
+      output: result + "\n\n" + [
+        "<task_metadata>",
+        `session_id: ${subSession.id}`,
+        `subagent_type: ${subagentType}`,
+        "</task_metadata>",
+      ].join("\n"),
+      metadata: {
+        execution_time_ms: Date.now() - startTime,
+        sessionId: subSession.id,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      output: "",
+      error: error instanceof Error ? error.message : String(error),
+      metadata: { execution_time_ms: Date.now() - startTime },
+    };
+  }
+}
+
+async function handleBackgroundTask(
+  taskComponent: TaskComponent,
+  backgroundTaskManager: BackgroundTaskManager,
+  parentSessionId: string,
+  description: string,
+  prompt: string,
+  subagentType: string,
+  timeout?: number,
+  cleanup?: "delete" | "keep",
+  taskId?: number
+): Promise<ToolResult> {
+  const startTime = Date.now();
+
+  try {
+    // Create or update task
+    let associatedTaskId = taskId;
+    
+    if (!associatedTaskId) {
+      // Create new task
+      const newTask = await taskComponent.createTask({
+        title: description,
+        description: `Background task delegated to ${subagentType} subagent`,
+        priority: "medium",
+        goals_and_expected_deliverables: prompt,
+        sessionId: parentSessionId,
+      });
+      associatedTaskId = newTask.id;
+
+      // Create operation record
+      await taskComponent.createOperation({
+        taskId: associatedTaskId,
+        sessionId: parentSessionId,
+        actionType: "create",
+        actionTitle: `Delegated to ${subagentType} subagent`,
+        actionDescription: `Background task started: ${description}`,
+      });
+    } else {
+      // Update existing task
+      await taskComponent.updateTask(associatedTaskId, {
+        status: "active",
+        current_status: `Running ${subagentType} subagent`,
+      });
+
+      await taskComponent.createOperation({
+        taskId: associatedTaskId,
+        sessionId: parentSessionId,
+        actionType: "progress",
+        actionTitle: `Started ${subagentType} subagent`,
+        actionDescription: `Background task: ${description}`,
+      });
+    }
+
+    // Create background task
+    const { taskId: bgTaskId, subSessionId } = await backgroundTaskManager.createTask({
+      parentSessionId,
+      description,
+      prompt,
+      subagentType,
+      timeout,
+      cleanup,
+      taskId: associatedTaskId,
+    });
+
+    const output = [
+      `✅ Background task accepted`,
+      "",
+      `📋 Task ID: ${bgTaskId}`,
+      `📝 Description: ${description}`,
+      `🤖 Sub-agent: ${subagentType}`,
+      associatedTaskId ? `📌 Associated Task: #${associatedTaskId}` : "",
+      `⏱️ Timeout: ${(timeout || DEFAULT_TIMEOUT) / 1000}s`,
+      "",
+      `Use stop_task with task_id="${bgTaskId}" to cancel this task.`,
+    ].filter(Boolean).join("\n");
+
+    return {
+      success: true,
+      output,
+      metadata: {
+        execution_time_ms: Date.now() - startTime,
+        sessionId: subSessionId,
+        background: true,
+        status: "accepted",
+        task_id: associatedTaskId,
+        bgTaskId,
+      },
+    };
+  } catch (error) {
+    return {
+      success: false,
+      output: "",
+      error: error instanceof Error ? error.message : String(error),
+      metadata: { execution_time_ms: Date.now() - startTime },
+    };
+  }
+}
+
+// Export for stop_task tool
+export { handleBackgroundTask, handleSyncTask };