qlogicagent 2.13.3 → 2.13.5

package/dist/skills/skill-system/skill-types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Parsed YAML frontmatter from a SKILL.md file.
+ * Keys are lowercased header names; values are always coerced to strings.
+ */
+export type ParsedSkillFrontmatter = Record<string, string>;
+/**
+ * A discovered skill on the filesystem.
+ */
+export interface WorkspaceSkill {
+    /** Display name (directory name by default). */
+    name: string;
+    /** One-line description extracted from frontmatter. */
+    description?: string;
+    /** Source tag for precedence/debugging, e.g. "bundled", "user", "project". */
+    source: string;
+    /** Absolute path to the SKILL.md file. */
+    filePath: string;
+    /** Absolute path to the skill directory (parent of SKILL.md). */
+    baseDir: string;
+    /** Primary runtime environment hint, e.g. "node", "python". */
+    primaryEnv?: string;
+    /** Environment variables the skill requires. */
+    requiredEnv?: string[];
+}
+/**
+ * Package-manager install specification for a skill dependency.
+ */
+export interface SkillInstallSpec {
+    id?: string;
+    kind: "brew" | "node" | "go" | "uv" | "download";
+    label?: string;
+    bins?: string[];
+    os?: string[];
+    formula?: string;
+    package?: string;
+    module?: string;
+    url?: string;
+    archive?: string;
+    extract?: boolean;
+    stripComponents?: number;
+    targetDir?: string;
+}
+/**
+ * Structured metadata from the `openclaw:` block inside SKILL.md frontmatter.
+ */
+export interface SkillMetadata {
+    /** If true, always include in prompt regardless of filter. */
+    always?: boolean;
+    /** Override key for deduplication / user-facing identification. */
+    skillKey?: string;
+    primaryEnv?: string;
+    emoji?: string;
+    homepage?: string;
+    /** Platform restriction: "win32", "darwin", "linux". */
+    os?: string[];
+    /** Use-case category for UI grouping. */
+    category?: string;
+    requires?: {
+        bins?: string[];
+        anyBins?: string[];
+        env?: string[];
+        config?: string[];
+    };
+    install?: SkillInstallSpec[];
+}
+/**
+ * Controls how a skill may be activated by user commands or model tool calls.
+ */
+export interface SkillInvocationPolicy {
+    /** Whether users can directly invoke this skill via slash-command. */
+    userInvocable: boolean;
+    /** If true, the model cannot trigger this skill autonomously. */
+    disableModelInvocation: boolean;
+}
+/**
+ * Slash-command dispatch specification for a skill.
+ */
+export interface SkillCommandDispatchSpec {
+    kind: "tool";
+    toolName: string;
+    argMode?: "raw";
+}
+/**
+ * A skill-derived slash-command for IM platforms.
+ */
+export interface SkillCommandSpec {
+    name: string;
+    skillName: string;
+    description: string;
+    dispatch?: SkillCommandDispatchSpec;
+}
+export type SkillScanSeverity = "info" | "warn" | "critical";
+export interface SkillScanFinding {
+    ruleId: string;
+    severity: SkillScanSeverity;
+    file: string;
+    line: number;
+    message: string;
+    evidence: string;
+}
+export interface SkillScanSummary {
+    scannedFiles: number;
+    critical: number;
+    warn: number;
+    info: number;
+    findings: SkillScanFinding[];
+}
+export interface SkillScanOptions {
+    includeFiles?: string[];
+    maxFiles?: number;
+    maxFileBytes?: number;
+}
+/**
+ * Filesystem dependencies injected by the host runtime.
+ * Keeps the skill system decoupled from Node.js `fs` / `path`.
+ */
+export interface SkillFsDeps {
+    readFileSync(path: string, encoding: "utf-8"): string;
+    readFile(path: string, encoding: "utf-8"): Promise<string>;
+    existsSync(path: string): boolean;
+    statSync(path: string): {
+        size: number;
+        mtimeMs: number;
+        isDirectory(): boolean;
+    };
+    readdirSync(path: string, opts: {
+        withFileTypes: true;
+    }): Array<{
+        name: string;
+        isDirectory(): boolean;
+        isSymbolicLink(): boolean;
+    }>;
+    realpathSync(path: string): string;
+}
+export interface SkillPathDeps {
+    join(...segments: string[]): string;
+    resolve(...segments: string[]): string;
+    extname(p: string): string;
+    sep: string;
+}

package/dist/skills/skill-system/skill-types.js

@@ -0,0 +1,6 @@
+//-------------------------------------------------------------------------
+// Skill system type definitions — portable, runtime-agnostic.
+// Mirrors openclaw/src/agents/skills/types.ts + security/skill-scanner.ts
+// but decoupled from framework internals.
+//-------------------------------------------------------------------------
+export {};

package/dist/skills/skill-system/skill-validation.d.ts

@@ -0,0 +1,29 @@
+export interface FrontmatterValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+    /** Parsed frontmatter if valid. */
+    parsed?: Record<string, string>;
+}
+/**
+ * Validate SKILL.md content for required frontmatter structure.
+ * Used before persisting agent-created skills.
+ */
+export declare function validateSkillContent(content: string, expectedName?: string): FrontmatterValidationResult;
+/**
+ * Generate valid SKILL.md content with proper frontmatter from minimal inputs.
+ * Used when auto-persisting skills from skill_instruction events.
+ */
+export declare function generateSkillContent(params: {
+    name: string;
+    description: string;
+    tools?: string[];
+    body: string;
+    version?: string;
+    category?: string;
+}): string;
+/**
+ * Auto-fix common frontmatter issues in LLM-generated skill content.
+ * Returns fixed content or null if unfixable.
+ */
+export declare function autoFixFrontmatter(content: string, name: string, description?: string): string | null;

package/dist/skills/skill-system/skill-validation.js

@@ -0,0 +1,154 @@
+//-------------------------------------------------------------------------
+// Skill frontmatter validation — enforces required fields and structure
+// for agent-created skills. Prevents low-quality skill proliferation.
+//
+// Required fields:
+//   - name: string (must match directory name)
+//   - description: string (≤200 chars, non-empty)
+//
+// Optional but validated:
+//   - version: semver-like string
+//   - tools: YAML list of tool names
+//   - category: string
+//-------------------------------------------------------------------------
+import { parseFrontmatter } from "./skill-frontmatter.js";
+//-------------------------------------------------------------------------
+// Constants
+//-------------------------------------------------------------------------
+const MAX_DESCRIPTION_LENGTH = 1024;
+const MAX_CONTENT_LENGTH = 100_000; // 100KB
+const NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+//-------------------------------------------------------------------------
+// Validation
+//-------------------------------------------------------------------------
+/**
+ * Validate SKILL.md content for required frontmatter structure.
+ * Used before persisting agent-created skills.
+ */
+export function validateSkillContent(content, expectedName) {
+    const errors = [];
+    const warnings = [];
+    // Basic content checks
+    if (!content || content.trim().length === 0) {
+        return { valid: false, errors: ["Content is empty"], warnings: [] };
+    }
+    if (content.length > MAX_CONTENT_LENGTH) {
+        return { valid: false, errors: [`Content exceeds ${MAX_CONTENT_LENGTH} chars`], warnings: [] };
+    }
+    // Must start with frontmatter delimiter
+    if (!content.trimStart().startsWith("---")) {
+        errors.push("SKILL.md must start with YAML frontmatter (---)");
+        return { valid: false, errors, warnings };
+    }
+    // Must have closing delimiter
+    const normalized = content.replace(/\r\n/g, "\n");
+    const endIdx = normalized.indexOf("\n---", 3);
+    if (endIdx === -1) {
+        errors.push("YAML frontmatter has no closing delimiter (---)");
+        return { valid: false, errors, warnings };
+    }
+    // Parse frontmatter
+    const parsed = parseFrontmatter(content);
+    // Required: name
+    if (!parsed.name) {
+        errors.push("Frontmatter must include 'name' field");
+    }
+    else {
+        if (!NAME_PATTERN.test(parsed.name)) {
+            errors.push(`Skill name '${parsed.name}' must be lowercase alphanumeric with dots, hyphens, or underscores`);
+        }
+        if (expectedName && parsed.name !== expectedName) {
+            warnings.push(`Frontmatter name '${parsed.name}' differs from expected '${expectedName}'`);
+        }
+    }
+    // Required: description
+    if (!parsed.description) {
+        errors.push("Frontmatter must include 'description' field");
+    }
+    else if (parsed.description.length > MAX_DESCRIPTION_LENGTH) {
+        errors.push(`Description exceeds ${MAX_DESCRIPTION_LENGTH} characters`);
+    }
+    // Body must have content after frontmatter
+    const body = normalized.slice(endIdx + 4).trim();
+    if (!body) {
+        errors.push("SKILL.md must have content after frontmatter");
+    }
+    // Optional validation: version format
+    if (parsed.version) {
+        if (!/^\d+\.\d+(\.\d+)?(-[\w.]+)?$/.test(parsed.version)) {
+            warnings.push(`Version '${parsed.version}' is not a valid semver format`);
+        }
+    }
+    return {
+        valid: errors.length === 0,
+        errors,
+        warnings,
+        parsed: errors.length === 0 ? parsed : undefined,
+    };
+}
+/**
+ * Generate valid SKILL.md content with proper frontmatter from minimal inputs.
+ * Used when auto-persisting skills from skill_instruction events.
+ */
+export function generateSkillContent(params) {
+    const lines = ["---"];
+    lines.push(`name: ${params.name}`);
+    lines.push(`description: ${params.description.slice(0, MAX_DESCRIPTION_LENGTH)}`);
+    if (params.version)
+        lines.push(`version: ${params.version}`);
+    if (params.category)
+        lines.push(`category: ${params.category}`);
+    if (params.tools && params.tools.length > 0) {
+        lines.push("tools:");
+        for (const t of params.tools) {
+            lines.push(`  - ${t}`);
+        }
+    }
+    lines.push("---");
+    lines.push("");
+    lines.push(params.body);
+    return lines.join("\n");
+}
+/**
+ * Auto-fix common frontmatter issues in LLM-generated skill content.
+ * Returns fixed content or null if unfixable.
+ */
+export function autoFixFrontmatter(content, name, description) {
+    const normalized = content.replace(/\r\n/g, "\n");
+    // Case 1: No frontmatter at all — wrap with one
+    if (!normalized.trimStart().startsWith("---")) {
+        return generateSkillContent({
+            name,
+            description: description ?? `Auto-learned skill: ${name}`,
+            body: normalized.trim(),
+            version: "1.0.0",
+        });
+    }
+    // Case 2: Has frontmatter but missing required fields
+    const parsed = parseFrontmatter(content);
+    const endIdx = normalized.indexOf("\n---", 3);
+    if (endIdx === -1) {
+        // Broken frontmatter — rewrap
+        return generateSkillContent({
+            name,
+            description: description ?? `Auto-learned skill: ${name}`,
+            body: normalized.replace(/^---.*$/m, "").trim(),
+            version: "1.0.0",
+        });
+    }
+    let fixed = false;
+    let frontmatterBlock = normalized.slice(4, endIdx);
+    const body = normalized.slice(endIdx + 4).trim();
+    if (!parsed.name) {
+        frontmatterBlock += `\nname: ${name}`;
+        fixed = true;
+    }
+    if (!parsed.description) {
+        const desc = description ?? `Auto-learned skill: ${name}`;
+        frontmatterBlock += `\ndescription: ${desc}`;
+        fixed = true;
+    }
+    if (!fixed)
+        return content; // nothing to fix
+    return `---\n${frontmatterBlock}\n---\n\n${body}`;
+}

package/dist/skills/tool-access.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Tool access constants for sub-agent tool filtering.
+ *
+ * CC-aligned: constants/tools.ts pattern.
+ * Tool filtering happens at agent SPAWN time (not per-iteration in tool loop).
+ *
+ * CC reference: claude-code-haha/src/constants/tools.ts
+ * CC reference: claude-code-haha/src/tools/AgentTool/agentToolUtils.ts
+ */
+import type { ToolDefinition } from "../protocol/wire/index.js";
+/**
+ * Tools that ALL sub-agents are forbidden from using.
+ * CC: ALL_AGENT_DISALLOWED_TOOLS
+ */
+export declare const AGENT_DISALLOWED_TOOLS: Set<string>;
+/**
+ * Additional tools denied for custom (user-defined) agents.
+ * CC: CUSTOM_AGENT_DISALLOWED_TOOLS
+ */
+export declare const CUSTOM_AGENT_DISALLOWED_TOOLS: Set<string>;
+/**
+ * Filter tools available to a sub-agent.
+ *
+ * CC pattern: tool filtering happens at agent SPAWN time,
+ * not per-iteration inside the tool loop.
+ *
+ * @param tools - Parent's full tool pool
+ * @param isBuiltIn - Whether the agent is a built-in agent type (vs custom)
+ */
+export declare function filterToolsForAgent(tools: ToolDefinition[], isBuiltIn: boolean): ToolDefinition[];

package/dist/skills/tool-access.js

@@ -0,0 +1,58 @@
+/**
+ * Tool access constants for sub-agent tool filtering.
+ *
+ * CC-aligned: constants/tools.ts pattern.
+ * Tool filtering happens at agent SPAWN time (not per-iteration in tool loop).
+ *
+ * CC reference: claude-code-haha/src/constants/tools.ts
+ * CC reference: claude-code-haha/src/tools/AgentTool/agentToolUtils.ts
+ */
+// ── Deny Lists (CC parity) ─────────────────────────────────
+/**
+ * Tools that ALL sub-agents are forbidden from using.
+ * CC: ALL_AGENT_DISALLOWED_TOOLS
+ */
+export const AGENT_DISALLOWED_TOOLS = new Set([
+    // Session/lifecycle management — only top-level agent should manage these
+    "gateway",
+    "agents_list",
+    "session_status",
+    "sessions_send",
+    "sessions_list",
+    "sessions_history",
+    "sessions_spawn",
+    // Scheduled tasks — only top-level agent
+    "cron",
+    // Config — only top-level agent
+    "config",
+    // Prevent recursive workflow execution inside sub-agents (CC parity)
+    "workflow",
+]);
+/**
+ * Additional tools denied for custom (user-defined) agents.
+ * CC: CUSTOM_AGENT_DISALLOWED_TOOLS
+ */
+export const CUSTOM_AGENT_DISALLOWED_TOOLS = new Set([
+    ...AGENT_DISALLOWED_TOOLS,
+    // Custom agents cannot spawn other agents (prevent recursion)
+    "agent",
+]);
+// ── Filter Function (CC parity: filterToolsForAgent) ────────
+/**
+ * Filter tools available to a sub-agent.
+ *
+ * CC pattern: tool filtering happens at agent SPAWN time,
+ * not per-iteration inside the tool loop.
+ *
+ * @param tools - Parent's full tool pool
+ * @param isBuiltIn - Whether the agent is a built-in agent type (vs custom)
+ */
+export function filterToolsForAgent(tools, isBuiltIn) {
+    const denySet = isBuiltIn ? AGENT_DISALLOWED_TOOLS : CUSTOM_AGENT_DISALLOWED_TOOLS;
+    return tools.filter((tool) => {
+        // MCP tools always allowed (CC parity)
+        if (tool.function.name.startsWith("mcp__"))
+            return true;
+        return !denySet.has(tool.function.name);
+    });
+}

package/dist/skills/tools/agent-tool.d.ts

@@ -0,0 +1,102 @@
+import type { PortableTool } from "../portable-tool.js";
+export declare const AGENT_TOOL_NAME: "agent";
+/**
+ * Built-in agent types (CC-aligned registry).
+ * The LLM selects which agent to fork based on the task.
+ */
+export type BuiltInAgentType = "general" | "explore" | "plan" | "code" | "research" | "verify";
+export declare const BUILT_IN_AGENT_TYPES: BuiltInAgentType[];
+export interface AgentToolParams {
+    /** Built-in agent type to invoke. */
+    agent: BuiltInAgentType;
+    /** Detailed task prompt for the sub-agent. */
+    prompt: string;
+    /** Short description of the task (3-7 words). Used for status display. */
+    description?: string;
+    /** Max turns override (default varies by agent type). */
+    maxTurns?: number;
+    /** Run in background (returns task_id immediately). */
+    background?: boolean;
+    /** Inherit a trimmed prefix of the parent conversation (default false). */
+    inheritContext?: boolean;
+}
+export declare const AGENT_TOOL_SCHEMA: {
+    readonly type: "object";
+    readonly properties: {
+        readonly agent: {
+            readonly type: "string";
+            readonly enum: readonly ["general", "explore", "plan", "code", "research", "verify"];
+            readonly description: string;
+        };
+        readonly prompt: {
+            readonly type: "string";
+            readonly description: string;
+        };
+        readonly description: {
+            readonly type: "string";
+            readonly description: "Short description (3-7 words) for status tracking.";
+        };
+        readonly maxTurns: {
+            readonly type: "number";
+            readonly description: "Max turns for the sub-agent. Defaults: general=200, explore=50, plan=80, code=200, research=30, verify=40.";
+        };
+        readonly background: {
+            readonly type: "boolean";
+            readonly description: string;
+        };
+        readonly inheritContext: {
+            readonly type: "boolean";
+            readonly description: string;
+        };
+    };
+    readonly required: readonly ["agent", "prompt"];
+    readonly additionalProperties: false;
+};
+export interface AgentResult {
+    /** Foreground: synthetic fork id. Background: real TaskStore task id (poll via task tool). */
+    agentId: string;
+    status: "completed" | "running" | "failed";
+    output?: string;
+    error?: string;
+    maxTurnsReached?: boolean;
+    tokensUsed?: number;
+}
+/**
+ * Host-provided fork execution backend.
+ *
+ * Actual behavior (not aspirational):
+ * - The child starts FRESH by default: it receives only the `prompt` as a single
+ *   user message. With inheritContext=true (foreground only), the host prepends a
+ *   trimmed, budget-capped slice of the parent conversation (no system prompt,
+ *   media/tool plumbing stripped) — best-effort cache reuse, NOT byte-identical.
+ * - Child inherits the parent's tool pool, filtered by the agent definition.
+ * - Fork depth is tracked via AsyncLocalStorage; spawns past MAX_FORK_DEPTH are rejected.
+ * - Output is returned via in-memory streaming (not DB).
+ */
+export interface AgentToolDeps {
+    /**
+     * Fork and run a sub-agent.
+     * The implementation must:
+     * - Pass `prompt` as the child's task; if inheritContext, prepend the parent
+     *   conversation slice (foreground only — background always starts fresh)
+     * - Inherit parent's tool pool (filtered by agent definition)
+     * - Track fork depth (reject if >= MAX_FORK_DEPTH)
+     * - Return output via in-memory streaming backflow
+     */
+    forkAgent(params: {
+        agent: BuiltInAgentType;
+        prompt: string;
+        description?: string;
+        maxTurns?: number;
+        background?: boolean;
+        inheritContext?: boolean;
+        abortSignal?: AbortSignal;
+    }): Promise<AgentResult>;
+    /** Abort signal from the parent turn. */
+    abortSignal?: AbortSignal;
+    /** Current fork depth (0 = root). Used for depth guard. */
+    currentForkDepth?: number;
+}
+/** Maximum fork depth for in-memory agents. */
+export declare const MAX_FORK_DEPTH = 4;
+export declare function createAgentTool(deps: AgentToolDeps): PortableTool<AgentToolParams>;

package/dist/skills/tools/agent-tool.js

@@ -0,0 +1,159 @@
+// ============================================================
+// Agent Tool — CC-aligned fork sub-agent with built-in registry.
+// Reference: claude-code-haha/src/tools/AgentTool/AgentTool.tsx
+//            claude-code-haha/src/tools/AgentTool/runAgent.ts
+//            claude-code-haha/src/tools/AgentTool/forkSubagent.ts
+//            claude-code-haha/src/tools/AgentTool/builtInAgents.ts
+// Category: system
+// ============================================================
+export const AGENT_TOOL_NAME = "agent";
+export const BUILT_IN_AGENT_TYPES = [
+    "general", "explore", "plan", "code", "research", "verify",
+];
+export const AGENT_TOOL_SCHEMA = {
+    type: "object",
+    properties: {
+        agent: {
+            type: "string",
+            enum: ["general", "explore", "plan", "code", "research", "verify"],
+            description: "Sub-agent type to fork:\n" +
+                "- general: Full tool access, any task\n" +
+                "- explore: Read-only codebase exploration (search, read, analyze)\n" +
+                "- plan: Planning mode (explore + produce plan, no writes)\n" +
+                "- code: Coding agent with full tool access\n" +
+                "- research: Web research and information gathering\n" +
+                "- verify: Run tests, check builds, validate changes",
+        },
+        prompt: {
+            type: "string",
+            description: "Detailed, self-contained task for the sub-agent. By default the sub-agent does " +
+                "NOT see this conversation, so include all context it needs here. " +
+                "Be specific about what information to return in the final response.",
+        },
+        description: {
+            type: "string",
+            description: "Short description (3-7 words) for status tracking.",
+        },
+        maxTurns: {
+            type: "number",
+            description: "Max turns for the sub-agent. Defaults: general=200, explore=50, plan=80, code=200, research=30, verify=40.",
+        },
+        background: {
+            type: "boolean",
+            description: "If true, runs in the background and immediately returns a task id. " +
+                "Check progress/result with task(action=\"output\", taskId=...); cancel with task(action=\"cancel\", taskId=...). " +
+                "Completion is also announced automatically at the start of your next turn. Default: false (blocks until done).",
+        },
+        inheritContext: {
+            type: "boolean",
+            description: "If true, the sub-agent receives a trimmed prefix of THIS conversation " +
+                "(system prompt dropped, media/tool plumbing stripped, budget-capped) so it shares your context. " +
+                "If false (default), the sub-agent starts fresh and only sees your `prompt` — " +
+                "in that case make the prompt fully self-contained. " +
+                "Ignored for background sub-agents (they always start fresh).",
+        },
+    },
+    required: ["agent", "prompt"],
+    additionalProperties: false,
+};
+/** Maximum fork depth for in-memory agents. */
+export const MAX_FORK_DEPTH = 4;
+export function createAgentTool(deps) {
+    return {
+        name: AGENT_TOOL_NAME,
+        label: "Sub-Agent",
+        description: "Fork a sub-agent to handle complex tasks autonomously. " +
+            "Sub-agents have isolated tool state and by default start FRESH — they see only your `prompt`, " +
+            "not this conversation — so make the prompt self-contained (or set inheritContext=true to share a trimmed context prefix). " +
+            "Use for: parallel research, code exploration, testing, delegating large tasks to specialized agents. " +
+            "Set background=true to run without blocking — you get a task id back, keep working, " +
+            "and the result is announced on your next turn (or poll via task action=\"output\"). " +
+            "Launch several background agents in one message for parallel independent work.",
+        parameters: AGENT_TOOL_SCHEMA,
+        searchHint: "fork subagent delegate spawn child parallel worker background",
+        isConcurrencySafe: true,
+        execute: async (_toolCallId, params, signal) => {
+            // Validate prompt
+            if (!params.prompt || params.prompt.trim().length < 10) {
+                return {
+                    content: [{ type: "text", text: "Error: prompt must be at least 10 characters." }],
+                    details: { type: "agent", error: "prompt_too_short" },
+                };
+            }
+            // Validate agent type
+            if (!BUILT_IN_AGENT_TYPES.includes(params.agent)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: unknown agent "${params.agent}". Available: ${BUILT_IN_AGENT_TYPES.join(", ")}`,
+                        }],
+                    details: { type: "agent", error: "invalid_agent_type" },
+                };
+            }
+            // Fork depth guard
+            const depth = deps.currentForkDepth ?? 0;
+            if (depth >= MAX_FORK_DEPTH) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: `Error: maximum fork depth (${MAX_FORK_DEPTH}) reached. Cannot spawn more sub-agents. Complete current work instead.`,
+                        }],
+                    details: { type: "agent", error: "max_depth_reached", depth },
+                };
+            }
+            try {
+                const result = await deps.forkAgent({
+                    agent: params.agent,
+                    prompt: params.prompt.trim(),
+                    description: params.description,
+                    maxTurns: params.maxTurns,
+                    background: params.background,
+                    inheritContext: params.inheritContext,
+                    abortSignal: signal ?? deps.abortSignal,
+                });
+                // Background mode — return task reference
+                if (params.background && result.status === "running") {
+                    return {
+                        content: [{
+                                type: "text",
+                                text: `Sub-agent "${params.agent}" started in background.\n` +
+                                    `Task ID: ${result.agentId}\n` +
+                                    `Poll with task(action="output", taskId="${result.agentId}"); cancel with task(action="cancel", taskId="${result.agentId}").\n` +
+                                    `Completion will also be announced at the start of your next turn.`,
+                            }],
+                        details: { type: "agent", agentId: result.agentId, status: "running", background: true },
+                    };
+                }
+                // Failed
+                if (result.status === "failed") {
+                    return {
+                        content: [{ type: "text", text: `Sub-agent failed: ${result.error || "unknown error"}` }],
+                        details: { type: "agent", agentId: result.agentId, status: "failed", error: result.error },
+                    };
+                }
+                // Completed — return output with metadata
+                const output = result.output || "(sub-agent returned no output)";
+                const suffix = result.maxTurnsReached
+                    ? "\n\n[Note: Sub-agent reached turn limit. Output may be incomplete.]"
+                    : "";
+                return {
+                    content: [{ type: "text", text: output + suffix }],
+                    details: {
+                        type: "agent",
+                        agentId: result.agentId,
+                        status: "completed",
+                        tokensUsed: result.tokensUsed,
+                        maxTurnsReached: result.maxTurnsReached,
+                    },
+                };
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                return {
+                    content: [{ type: "text", text: `Sub-agent execution failed: ${msg}` }],
+                    details: { type: "agent", error: "execution_error", message: msg },
+                };
+            }
+        },
+    };
+}