skyloom 1.16.2 → 1.17.0

package/src/core/tool.ts

@@ -144,15 +144,22 @@ function coerceValue(value: unknown, targetType: string): [boolean, unknown] {
     return [true, value];
   }
 
+  // string target accepts scalars (number/boolean) by stringifying them —
+  // the model sometimes sends 5 where a string id is expected.
+  if (targetType === "string" && (typeof value === "number" || typeof value === "boolean")) {
+    return [true, String(value)];
+  }
+
   // Lenient coercion from string
   if (typeof value === "string") {
     const stripped = value.trim();
 
     if (targetType === "integer" || targetType === "number") {
-      const num = parseInt(stripped, 10);
-      if (!isNaN(num)) return [true, num];
-      const float = parseFloat(stripped);
-      if (!isNaN(float)) return [true, float];
+      // Number() handles ints and floats uniformly; parseInt truncated floats
+      // ("3.5" -> 3), silently corrupting numeric args.
+      if (stripped === "") return [false, value];
+      const num = Number(stripped);
+      if (!isNaN(num)) return [true, targetType === "integer" ? Math.trunc(num) : num];
       return [false, value];
     }
 
@@ -164,16 +171,35 @@ function coerceValue(value: unknown, targetType: string): [boolean, unknown] {
     }
 
     if (targetType === "array") {
+      // The model often sends a JSON-encoded array string for array params.
+      if (stripped.startsWith("[")) {
+        try { const parsed = JSON.parse(stripped); if (Array.isArray(parsed)) return [true, parsed]; } catch { /* fall through */ }
+      }
       if (stripped.includes(",")) {
         return [true, stripped.split(",").map((s) => s.trim())];
       }
       return [true, [value]];
     }
+
+    if (targetType === "object") {
+      try {
+        const parsed = JSON.parse(stripped);
+        if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) return [true, parsed];
+      } catch { /* not JSON */ }
+      return [false, value];
+    }
   }
 
   return [false, value];
 }
 
+/** Describe a value's runtime type for an error message. */
+function describeType(v: unknown): string {
+  if (v === null) return "null";
+  if (Array.isArray(v)) return "array";
+  return typeof v;
+}
+
 /**
  * Tool registry and executor
  */
@@ -265,32 +291,59 @@ export class ToolRegistry extends EventEmitter {
   }
 
   /**
-   * Validate tool parameters
+   * Validate tool inputs against the declared schema AND return coerced args:
+   * required-field presence, per-param type coercion (string<->number/bool,
+   * JSON-string -> array/object), and enum membership. Returning the coerced
+   * params means the handler receives clean, typed values (the model often
+   * sends "5" / "true" / a JSON string), and rejecting malformed input before
+   * execution gives the model a precise, actionable error to retry against.
    */
-  validateParameters(toolName: string, params: Record<string, unknown>): [boolean, string] {
+  validateAndCoerce(
+    toolName: string,
+    params: Record<string, unknown>,
+  ): { ok: boolean; error?: string; params?: Record<string, unknown> } {
     const tool = this.tools.get(toolName);
-    if (!tool) {
-      return [false, `Tool ${toolName} not found`];
-    }
-
-    if (!tool.parameters) {
-      return [true, ""];
-    }
+    if (!tool) return { ok: false, error: `Tool ${toolName} not found` };
+    if (!tool.parameters || tool.parameters.length === 0) return { ok: true, params };
 
+    const out: Record<string, unknown> = { ...params };
     for (const param of tool.parameters) {
-      if (param.required && !(param.name in params)) {
-        return [false, `Missing required parameter: ${param.name}`];
+      const has = param.name in params && params[param.name] !== null && params[param.name] !== undefined;
+      if (!has) {
+        if (param.required) {
+          return { ok: false, error: `Missing required parameter '${param.name}' (expected ${param.type}).` };
+        }
+        continue;
       }
 
-      if (param.name in params) {
-        const [valid] = coerceValue(params[param.name], param.type);
-        if (!valid) {
-          return [false, `Invalid type for parameter ${param.name}: expected ${param.type}`];
-        }
+      const [valid, coerced] = coerceValue(params[param.name], param.type);
+      if (!valid) {
+        return {
+          ok: false,
+          error: `Invalid type for parameter '${param.name}': expected ${param.type}, got ${describeType(params[param.name])}.`,
+        };
+      }
+
+      if (param.enum && param.enum.length > 0 && !param.enum.includes(String(coerced))) {
+        return {
+          ok: false,
+          error: `Invalid value for parameter '${param.name}': '${String(coerced)}' is not allowed. Valid values: ${param.enum.join(", ")}.`,
+        };
       }
+
+      out[param.name] = coerced;
     }
 
-    return [true, ""];
+    return { ok: true, params: out };
+  }
+
+  /**
+   * Validate tool parameters (legacy boolean/message form; delegates to
+   * validateAndCoerce).
+   */
+  validateParameters(toolName: string, params: Record<string, unknown>): [boolean, string] {
+    const r = this.validateAndCoerce(toolName, params);
+    return [r.ok, r.error || ""];
   }
 
   /**
@@ -316,6 +369,18 @@ export class ToolRegistry extends EventEmitter {
       };
     }
 
+    // Validate + coerce inputs against the schema BEFORE cache/execute, so the
+    // handler and the cache key both use clean, typed values.
+    const validated = this.validateAndCoerce(toolName, params);
+    if (!validated.ok) {
+      return {
+        success: false,
+        result: "",
+        error: validated.error,
+      };
+    }
+    params = validated.params!;
+
     // Check cache
     if (tool.cacheable) {
       const cacheKey = stableStringify(params);
@@ -330,16 +395,6 @@ export class ToolRegistry extends EventEmitter {
       }
     }
 
-    // Validate parameters
-    const [valid, error] = this.validateParameters(toolName, params);
-    if (!valid) {
-      return {
-        success: false,
-        result: "",
-        error,
-      };
-    }
-
     // Execute with retries
     const maxRetries = tool.maxRetries ?? DEFAULT_RETRIES;
     const retryDelay = (tool.retryDelay ?? DEFAULT_RETRY_DELAY) * 1000;

package/src/plugins/loader.ts

@@ -1,14 +1,52 @@
 /**
- * Plugin loader — loads external plugins that register additional tools.
+ * Plugin loader — discovers external plugins and runs them through an ordered
+ * hook lifecycle.
+ *
+ * A plugin is a directory with an `index.js` exporting either:
+ *   - activate(ctx): the lifecycle form. `ctx` scopes every registration to the
+ *     plugin (registerTool / on(hook, fn)), so unload(name) cleanly removes
+ *     exactly what the plugin added.
+ *   - register(registry): the legacy form. Still supported — tools it adds are
+ *     diffed against the registry so they're tracked for unload too.
+ *
+ * Hooks fire in registration order. Core hooks: `init` (after all plugins
+ * load), `tool.register` (a tool was added), `provider.update` (model/provider
+ * config changed). Plugins may define and emit their own hook names.
  */
 
 import * as fs from 'fs';
 import * as path from 'path';
-import { ToolRegistry } from '../core/tool';
+import { ToolRegistry, type ToolDefinition } from '../core/tool';
 import { getLogger } from '../core/logger';
 
 const log = getLogger('plugin-loader');
 
+export type PluginHook = 'init' | 'tool.register' | 'provider.update' | string;
+export type HookHandler = (payload?: any) => void | Promise<void>;
+
+/** Scoped API handed to a plugin's activate(); every call is tracked for unload. */
+export interface PluginContext {
+  readonly name: string;
+  readonly config: any;
+  readonly log: ReturnType<typeof getLogger>;
+  registerTool(def: ToolDefinition): void;
+  on(hook: PluginHook, handler: HookHandler): void;
+}
+
+export interface Plugin {
+  name?: string;
+  activate?(ctx: PluginContext): void | Promise<void>;
+  register?(registry: ToolRegistry): void; // legacy
+  deactivate?(): void | Promise<void>;
+}
+
+interface LoadedPlugin {
+  name: string;
+  module: Plugin;
+  tools: string[];
+  hooks: Array<{ hook: string; fn: HookHandler }>;
+}
+
 /**
  * A plugin path is safe to `require` only if neither it nor (on POSIX) its
  * permissions allow group/world write — otherwise a less-privileged user could
@@ -28,14 +66,17 @@ export function isSafePluginPath(target: string): boolean {
 
 export class PluginLoader {
   private toolRegistry: ToolRegistry;
+  private config: any;
+  private plugins = new Map<string, LoadedPlugin>();
+  /** hook name -> handlers in registration order, each tagged with its plugin. */
+  private hookHandlers = new Map<string, Array<{ plugin: string; fn: HookHandler }>>();
 
-  constructor(toolRegistry: ToolRegistry) {
+  constructor(toolRegistry: ToolRegistry, config?: any) {
     this.toolRegistry = toolRegistry;
+    this.config = config ?? {};
   }
 
-  /**
-   * Load plugins from specified directories.
-   */
+  /** Load plugins from specified directories. Returns the number activated. */
   loadFromDirectories(directories: string[]): number {
     let total = 0;
     for (const dir of directories) {
@@ -44,9 +85,6 @@ export class PluginLoader {
     return total;
   }
 
-  /**
-   * Load a single plugin directory.
-   */
   private loadDirectory(dir: string): number {
     if (!fs.existsSync(dir)) {
       log.debug('plugin_dir_not_found', { dir });
@@ -55,10 +93,9 @@ export class PluginLoader {
 
     let count = 0;
     try {
-      const entries = fs.readdirSync(dir);
-      for (const entry of entries) {
+      for (const entry of fs.readdirSync(dir)) {
         const pluginPath = path.join(dir, entry);
-        if (!fs.statSync(pluginPath).isDirectory()) continue;
+        try { if (!fs.statSync(pluginPath).isDirectory()) continue; } catch { continue; }
 
         const pluginFile = path.join(pluginPath, 'index.js');
         if (!fs.existsSync(pluginFile)) continue;
@@ -72,12 +109,8 @@ export class PluginLoader {
         }
 
         try {
-          const plugin = require(pluginFile);
-          if (typeof plugin.register === 'function') {
-            plugin.register(this.toolRegistry);
-            count++;
-            log.info('plugin_loaded', { name: entry });
-          }
+          const mod = require(pluginFile) as Plugin;
+          if (this.activatePlugin(entry, mod)) count++;
         } catch (e) {
           log.warn('plugin_load_failed', { name: entry, error: String(e) });
         }
@@ -88,4 +121,98 @@ export class PluginLoader {
 
     return count;
   }
+
+  /**
+   * Activate a plugin module under a name. Reactivating an already-loaded name
+   * unloads the previous instance first. Returns true if anything registered.
+   */
+  activatePlugin(name: string, mod: Plugin): boolean {
+    const pluginName = mod.name || name;
+    if (this.plugins.has(pluginName)) this.unload(pluginName);
+
+    const record: LoadedPlugin = { name: pluginName, module: mod, tools: [], hooks: [] };
+    const self = this;
+
+    if (typeof mod.activate === 'function') {
+      const ctx: PluginContext = {
+        name: pluginName,
+        config: this.config,
+        log: getLogger(`plugin:${pluginName}`),
+        registerTool(def: ToolDefinition) {
+          self.toolRegistry.register(def);
+          record.tools.push(def.name);
+          void self.emit('tool.register', { plugin: pluginName, tool: def.name });
+        },
+        on(hook: PluginHook, handler: HookHandler) {
+          record.hooks.push({ hook, fn: handler });
+          const arr = self.hookHandlers.get(hook) || [];
+          arr.push({ plugin: pluginName, fn: handler });
+          self.hookHandlers.set(hook, arr);
+        },
+      };
+      try {
+        void mod.activate(ctx);
+      } catch (e) {
+        log.warn('plugin_activate_failed', { name: pluginName, error: String(e) });
+        this.unload(pluginName);
+        return false;
+      }
+    } else if (typeof mod.register === 'function') {
+      // Legacy: diff the registry to learn which tools the plugin added.
+      const before = new Set(this.toolRegistry.listNames());
+      try {
+        mod.register(this.toolRegistry);
+      } catch (e) {
+        log.warn('plugin_register_failed', { name: pluginName, error: String(e) });
+        return false;
+      }
+      for (const n of this.toolRegistry.listNames()) {
+        if (!before.has(n)) record.tools.push(n);
+      }
+    } else {
+      log.warn('plugin_no_entrypoint', { name: pluginName });
+      return false;
+    }
+
+    this.plugins.set(pluginName, record);
+    log.info('plugin_loaded', { name: pluginName, tools: record.tools.length, hooks: record.hooks.length });
+    return true;
+  }
+
+  /** Fire a hook; handlers run in registration order. Errors are isolated. */
+  async emit(hook: PluginHook, payload?: any): Promise<void> {
+    const handlers = this.hookHandlers.get(hook);
+    if (!handlers || handlers.length === 0) return;
+    for (const { plugin, fn } of [...handlers]) {
+      try {
+        await fn(payload);
+      } catch (e) {
+        log.warn('plugin_hook_failed', { hook, plugin, error: String(e) });
+      }
+    }
+  }
+
+  /** Unload a plugin: remove its tools and hook handlers, call deactivate. */
+  unload(name: string): boolean {
+    const record = this.plugins.get(name);
+    if (!record) return false;
+
+    for (const tool of record.tools) this.toolRegistry.unregister(tool);
+    for (const [hook, arr] of this.hookHandlers) {
+      const filtered = arr.filter((h) => h.plugin !== name);
+      if (filtered.length) this.hookHandlers.set(hook, filtered);
+      else this.hookHandlers.delete(hook);
+    }
+    try { record.module.deactivate?.(); } catch (e) { log.warn('plugin_deactivate_failed', { name, error: String(e) }); }
+
+    this.plugins.delete(name);
+    log.info('plugin_unloaded', { name });
+    return true;
+  }
+
+  /** Names of currently loaded plugins. */
+  list(): string[] { return [...this.plugins.keys()]; }
+
+  /** Number of handlers registered for a hook (for diagnostics/tests). */
+  hookCount(hook: PluginHook): number { return this.hookHandlers.get(hook)?.length ?? 0; }
 }

package/src/tools/builtin.ts

@@ -10,6 +10,8 @@ import { registerComputerTools } from './computer';
 import { registerExtraTools } from './extra';
 import { isPrivateIp, assertFetchAllowed, fenceRoot, fenceCheck } from './guards';
 import { webSearch, formatSearchResults, readPage } from './websearch';
+import { countOccurrences, unifiedDiff } from '../core/diff';
+import { getDiagnostics, formatDiagnostics } from '../core/diagnostics';
 
 // Re-exported so existing importers/tests keep resolving these from builtin.
 export { isPrivateIp, assertFetchAllowed, fenceRoot, fenceCheck };
@@ -77,32 +79,69 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
 
   registry.register({
     name: 'edit_file',
-    description: 'Edit a file by replacing old_text with new_text. Use this for targeted edits.',
+    description: 'Edit a file by replacing an exact occurrence of old_text with new_text. old_text must match the file exactly (including whitespace and indentation) and must be UNIQUE — include enough surrounding context to disambiguate, or set replace_all to change every occurrence. Returns a unified diff of the change.',
     parameters: [
       { name: 'path', type: 'string', description: 'Path to the file to edit', required: true },
-      { name: 'old_text', type: 'string', description: 'Text to search for and replace', required: true },
-      { name: 'new_text', type: 'string', description: 'Text to replace with', required: true },
+      { name: 'old_text', type: 'string', description: 'Exact text to replace (must match the file verbatim, and be unique unless replace_all is set)', required: true },
+      { name: 'new_text', type: 'string', description: 'Replacement text (must differ from old_text)', required: true },
+      { name: 'replace_all', type: 'boolean', description: 'Replace every occurrence instead of requiring a unique match (default false)', required: false },
     ],
     handler: async (params) => {
       const filePath = path.resolve(params.path as string);
       const fenced = fenceCheck(filePath); if (fenced) return fenced;
       if (!fs.existsSync(filePath)) return `Error: File not found: ${filePath}`;
+      const oldText = params.old_text as string;
+      const newText = params.new_text as string;
+      const replaceAll = params.replace_all === true || params.replace_all === 'true';
+      if (oldText === newText) return 'Error: old_text and new_text are identical — nothing to change.';
       try {
-        let content = fs.readFileSync(filePath, 'utf-8');
-        const oldText = params.old_text as string;
-        const newText = params.new_text as string;
-        if (!content.includes(oldText)) {
-          return `Error: old_text not found in file. Searched for: ${oldText.slice(0, 50)}...`;
+        const orig = fs.readFileSync(filePath, 'utf-8');
+        const n = countOccurrences(orig, oldText);
+        if (n === 0) {
+          return `Error: old_text not found in ${filePath}. It must match exactly (including whitespace). Searched for: ${JSON.stringify(oldText.slice(0, 80))}`;
         }
-        content = content.replace(oldText, newText);
-        fs.writeFileSync(filePath, content, 'utf-8');
-        return `Successfully edited ${filePath}`;
+        if (n > 1 && !replaceAll) {
+          return `Error: old_text appears ${n} times in ${filePath} — the edit is ambiguous. Add more surrounding context to make it unique, or set replace_all=true to change all ${n} occurrences.`;
+        }
+        // Literal replacement: split/join (replace_all) and a function replacer
+        // (single) both avoid String.replace interpreting `$&`/`$1` in new_text.
+        const updated = replaceAll
+          ? orig.split(oldText).join(newText)
+          : orig.replace(oldText, () => newText);
+        fs.writeFileSync(filePath, updated, 'utf-8');
+        const rel = path.relative(process.cwd(), filePath) || filePath;
+        const diff = unifiedDiff(orig, updated, { path: rel, context: 3 });
+        const occ = replaceAll ? ` (${n} occurrence${n > 1 ? 's' : ''})` : '';
+        const body = diff.text ? `\n${diff.text}` : '';
+        return `Successfully edited ${filePath}${occ} · +${diff.stat.added} -${diff.stat.removed}${body}`;
       } catch (e) {
         return `Error editing file: ${e}`;
       }
     },
   });
 
+  registry.register({
+    name: 'get_diagnostics',
+    idempotent: true,
+    description: 'Get LSP-style diagnostics (type errors, lint issues with line:col) for a source file. TS/JS work out of the box via the workspace TypeScript; other languages use a configured checker (config.yaml diagnostics map). Call this after editing code to confirm it is error-free, or to locate the root cause of a type error.',
+    parameters: [
+      { name: 'path', type: 'string', description: 'Path to the source file to check', required: true },
+    ],
+    handler: async (params) => {
+      const filePath = path.resolve(params.path as string);
+      const fenced = fenceCheck(filePath); if (fenced) return fenced;
+      let config: any = {};
+      try { const { loadConfig } = require('../core/config'); config = loadConfig(); } catch { /* defaults */ }
+      try {
+        const result = getDiagnostics(filePath, config);
+        if (!Array.isArray(result)) return `[diagnostics unavailable] ${result.unavailable}`;
+        return formatDiagnostics(path.relative(process.cwd(), filePath) || filePath, result);
+      } catch (e) {
+        return `Error getting diagnostics: ${e}`;
+      }
+    },
+  });
+
   registry.register({
     name: 'delete_file',
     description: 'Delete a file at the given path.',
@@ -172,13 +211,23 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
 
   registry.register({
     name: 'run_bash',
-    description: 'Execute a shell command and return its output.',
+    description: 'Execute a shell command and return its output. Set background=true for long-running processes (dev servers, watchers, builds): it returns a job id immediately — read its output later with bash_output, stop it with kill_bash.',
     parameters: [
       { name: 'command', type: 'string', description: 'Command to execute', required: true },
-      { name: 'timeout', type: 'number', description: 'Timeout in milliseconds (default: 30000)', required: false },
+      { name: 'timeout', type: 'number', description: 'Timeout in milliseconds (default: 30000). Ignored when background=true.', required: false },
+      { name: 'background', type: 'boolean', description: 'Run detached in the background and return a job id instead of blocking (default false)', required: false },
     ],
     handler: async (params) => {
       const cmd = params.command as string;
+      const background = params.background === true || params.background === 'true';
+      if (background) {
+        try {
+          const { getBackgroundManager } = require('../core/bgproc');
+          const { id, error } = getBackgroundManager().start(cmd);
+          if (error) return error;
+          return `[background job ${id} started] pid running. Use bash_output("${id}") to read output, kill_bash("${id}") to stop, list_bash to see all jobs.`;
+        } catch (e: any) { return `Error: ${e.message || e}`; }
+      }
       const timeout = (params.timeout as number) || 30000;
       try {
         const { runInSandbox, formatSandboxResult } = require('../core/sandbox');
@@ -189,6 +238,51 @@ export function registerBuiltinTools(registry: ToolRegistry): void {
     dangerous: true,
   });
 
+  registry.register({
+    name: 'bash_output',
+    description: 'Read new output from a background shell job (started by run_bash with background=true) since the last read, plus its current status.',
+    parameters: [
+      { name: 'id', type: 'string', description: 'The background job id', required: true },
+    ],
+    handler: async (params) => {
+      const { getBackgroundManager } = require('../core/bgproc');
+      const r = getBackgroundManager().read(String(params.id || ''));
+      if (!r.ok) return r.error || 'Error reading background job.';
+      const statusLine = `[job ${params.id} · ${r.status}${r.exitCode != null ? ` · exit ${r.exitCode}` : ''}]`;
+      const out = r.text && r.text.length ? r.text : '(no new output)';
+      return `${statusLine}\n${out}`;
+    },
+  });
+
+  registry.register({
+    name: 'list_bash',
+    description: 'List background shell jobs with their status, pid, and runtime.',
+    parameters: [],
+    handler: async () => {
+      const { getBackgroundManager } = require('../core/bgproc');
+      const jobs = getBackgroundManager().list();
+      if (!jobs.length) return 'No background jobs.';
+      return jobs.map((j: any) => {
+        const dur = ((j.endedAt || Date.now()) - j.startedAt) / 1000;
+        const ex = j.exitCode != null ? ` exit ${j.exitCode}` : '';
+        return `${j.id} · ${j.status}${ex} · pid ${j.pid ?? '?'} · ${dur.toFixed(1)}s · ${j.command.slice(0, 60)}`;
+      }).join('\n');
+    },
+  });
+
+  registry.register({
+    name: 'kill_bash',
+    description: 'Terminate a running background shell job.',
+    parameters: [
+      { name: 'id', type: 'string', description: 'The background job id to kill', required: true },
+    ],
+    handler: async (params) => {
+      const { getBackgroundManager } = require('../core/bgproc');
+      const r = getBackgroundManager().kill(String(params.id || ''));
+      return r.ok ? `[job ${params.id} killed]` : (r.error || 'Error killing background job.');
+    },
+  });
+
   // ── HTTP Tools ──
 
   registry.register({

package/src/tools/spawn.ts

@@ -0,0 +1,92 @@
+/**
+ * spawn_agent tool — launch a general-purpose, isolated-context subagent to
+ * handle one focused, self-contained task and return only its final report.
+ *
+ * This is sky's analogue of Claude Code's Task tool. Subagent types are
+ * discovered from built-ins plus `.claude/agents` / `.sky/agents` definition
+ * files (see core/subagent). Subagents never receive spawn_agent themselves,
+ * so there is no recursive fan-out.
+ */
+
+import type { ToolDefinition } from '../core/tool';
+import type { ToolRegistry } from '../core/tool';
+import type { SkillRegistry } from '../core/skill';
+import type { LLMClient } from '../core/llm';
+import type { MessageBus } from '../core/bus';
+import { loadSubagentDefinitions, runSubagent } from '../core/subagent';
+
+export function createSpawnAgentTool(opts: {
+  config: any;
+  llm: LLMClient;
+  bus: MessageBus;
+  baseToolRegistry: ToolRegistry;
+  baseSkillRegistry: SkillRegistry;
+  cwd?: string;
+}): ToolDefinition {
+  const cwd = opts.cwd || process.cwd();
+
+  const buildDescription = (): string => {
+    const defs = loadSubagentDefinitions(cwd);
+    const lines = [...defs.values()].map((d) => `  - ${d.name}: ${d.description}`);
+    return (
+      '派生一个隔离上下文的子智能体来独立完成一个聚焦、自洽的任务,只返回它的最终报告。' +
+      '当任务需要大量搜索/调研、或你想把一段独立工作从主上下文里隔离出去时使用。' +
+      '子智能体看不到你的对话历史,所以 task 必须自带全部所需上下文(目标、相关文件、约束)。' +
+      '它无法反问你,会一次性完成并汇报。可并行派生多个互不依赖的子智能体。\n\n可用子智能体类型:\n' +
+      lines.join('\n')
+    );
+  };
+
+  return {
+    name: 'spawn_agent',
+    description: buildDescription(),
+    parameters: [
+      {
+        name: 'agent_type',
+        type: 'string',
+        description: '子智能体类型(见工具描述中的可用类型,如 general-purpose / explore 或自定义)',
+        required: true,
+      },
+      {
+        name: 'task',
+        type: 'string',
+        description: '完整、自洽的任务描述。子智能体看不到对话历史,必须在此写清目标、相关文件路径与约束。',
+        required: true,
+      },
+      {
+        name: 'description',
+        type: 'string',
+        description: '可选:对该任务的简短(3-5 词)标签,用于展示。',
+        required: false,
+      },
+    ],
+    // Long-running by nature (full nested agent loop); give it generous headroom.
+    timeout: 600000,
+    handler: async (params) => {
+      const agentType = String(params.agent_type || '').trim();
+      const task = String(params.task || '').trim();
+      if (!agentType) return '[spawn_agent error] agent_type is required.';
+      if (!task) return '[spawn_agent error] task is required.';
+
+      const defs = loadSubagentDefinitions(cwd);
+      const def = defs.get(agentType);
+      if (!def) {
+        const available = [...defs.keys()].join(', ');
+        return `[spawn_agent error] unknown agent_type '${agentType}'. Available: ${available}`;
+      }
+
+      const report = await runSubagent({
+        def,
+        task,
+        config: opts.config,
+        llm: opts.llm,
+        bus: opts.bus,
+        baseToolRegistry: opts.baseToolRegistry,
+        baseSkillRegistry: opts.baseSkillRegistry,
+      });
+
+      const header = `[subagent ${def.name} 完成]`;
+      return `${header}\n${report}`;
+    },
+  };
+}