@cjhyy/code-shell-core 0.5.0-rc.0

package/dist/tool-system/builtin/plan.js

@@ -0,0 +1,55 @@
+/**
+ * Plan mode — restricts the agent to read-only exploration and text output.
+ *
+ * In plan mode the agent:
+ *   - Can only use read-only tools (Read, Glob, Grep, Bash read-only, WebSearch, etc.)
+ *   - CANNOT write, edit, or create files
+ *   - Outputs its plan as text directly in the conversation
+ *   - Exits plan mode when the user approves or via ExitPlanMode tool
+ */
+export const enterPlanModeToolDef = {
+    name: "EnterPlanMode",
+    description: "Enter plan mode for complex, high-risk, or ambiguous tasks. " +
+        "ONLY use this when: (1) the user explicitly asks for a plan before implementation, " +
+        "(2) the task involves large-scale refactoring across many files, or " +
+        "(3) the task is ambiguous and you need to propose an approach for user approval. " +
+        "Do NOT enter plan mode for straightforward tasks like fixing a bug, adding a small feature, " +
+        "or answering a question. In plan mode, output your plan as text, then call ExitPlanMode.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
+export const exitPlanModeToolDef = {
+    name: "ExitPlanMode",
+    description: "Exit plan mode and return to normal mode. Call this after outputting your plan " +
+        "so you can proceed with implementation.",
+    inputSchema: {
+        type: "object",
+        properties: {},
+    },
+};
+// ─── Tool implementations ─────────────────────────────────────
+export async function enterPlanModeTool(_args, ctx) {
+    if (ctx?.engine?.planMode) {
+        return "Already in plan mode. Output your plan as text, then call ExitPlanMode.";
+    }
+    ctx?.engine.setPlanMode(true);
+    return [
+        "Entered plan mode.",
+        "",
+        "Rules:",
+        "- You can ONLY use read-only tools: Read, Glob, Grep, WebSearch, WebFetch, and read-only Bash commands",
+        "- You CANNOT write, edit, or create any files",
+        "- Output your plan as text directly in the conversation",
+        "- Use markdown formatting with clear steps, file paths, and rationale",
+        "- Call ExitPlanMode when your plan is complete and ready for review",
+    ].join("\n");
+}
+export async function exitPlanModeTool(_args, ctx) {
+    if (!ctx?.engine?.planMode) {
+        return "Not currently in plan mode.";
+    }
+    ctx?.engine.setPlanMode(false);
+    return "Exited plan mode. You can now write and edit files to implement the plan.";
+}

package/dist/tool-system/builtin/powershell.d.ts

@@ -0,0 +1,11 @@
+/**
+ * PowerShellTool — execute PowerShell commands (Windows or pwsh).
+ *
+ * The lifecycle (spawn, abort/timeout cascade, IO drain, byte cap) is
+ * centralized in {@link safeSpawn}; this file only carries the pwsh /
+ * powershell.exe selection + the PowerShell-specific output formatting.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const powershellToolDef: ToolDefinition;
+export declare function powershellTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/powershell.js

@@ -0,0 +1,64 @@
+/**
+ * PowerShellTool — execute PowerShell commands (Windows or pwsh).
+ *
+ * The lifecycle (spawn, abort/timeout cascade, IO drain, byte cap) is
+ * centralized in {@link safeSpawn}; this file only carries the pwsh /
+ * powershell.exe selection + the PowerShell-specific output formatting.
+ */
+import { safeSpawn } from "../../runtime/safe-spawn.js";
+export const powershellToolDef = {
+    name: "PowerShell",
+    description: "Execute PowerShell commands. Available on Windows and cross-platform where PowerShell Core is installed.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            command: {
+                type: "string",
+                description: "The PowerShell command to execute",
+            },
+            timeout: {
+                type: "number",
+                description: "Timeout in milliseconds (default: 120000)",
+            },
+        },
+        required: ["command"],
+    },
+};
+const PS_MAX_BUFFER = 5 * 1024 * 1024;
+export async function powershellTool(args, ctx) {
+    const command = args.command;
+    const timeout = args.timeout ?? 120_000;
+    if (!command.trim()) {
+        return "Error: command is required.";
+    }
+    // Determine PowerShell executable.
+    const psCmd = process.platform === "win32" ? "powershell.exe" : "pwsh";
+    // A4: child process runs in the Engine's cwd, not the host process cwd.
+    const cwd = ctx?.cwd ?? process.cwd();
+    const wasAbortedBeforeStart = ctx?.signal?.aborted === true;
+    // PowerShell's -Command flag takes the script as a single argument;
+    // passing it through argv avoids shell quoting issues.
+    const result = await safeSpawn(psCmd, ["-NoProfile", "-NonInteractive", "-Command", command], {
+        cwd,
+        env: { ...process.env },
+        timeoutMs: timeout,
+        maxOutputBytes: PS_MAX_BUFFER,
+        signal: ctx?.signal,
+    });
+    if (result.aborted) {
+        return wasAbortedBeforeStart
+            ? "PowerShell aborted before starting."
+            : "PowerShell aborted by signal.";
+    }
+    if (result.timedOut) {
+        return `PowerShell timed out after ${timeout}ms`;
+    }
+    if (result.spawnFailed) {
+        return `PowerShell spawn error: ${result.error ?? "unknown error"}`;
+    }
+    if (result.exitCode !== 0) {
+        const out = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+        return `PowerShell error:\n${out || `exit code ${result.exitCode}`}`;
+    }
+    return result.stdout.trim() || "(no output)";
+}

package/dist/tool-system/builtin/read.d.ts

@@ -0,0 +1,6 @@
+/**
+ * Built-in Read file tool.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const readToolDef: ToolDefinition;
+export declare function readTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/read.js

@@ -0,0 +1,70 @@
+/**
+ * Built-in Read file tool.
+ */
+import { readFile, stat } from "node:fs/promises";
+import { existsSync } from "node:fs";
+import { fileCache } from "./file-cache.js";
+export const readToolDef = {
+    name: "Read",
+    description: "Read a file from the local filesystem. Returns the file content with line numbers. " +
+        "By default reads up to 2000 lines from the beginning. " +
+        "Use offset and limit to read specific portions of large files. " +
+        "For large files, consider using Grep first to find the relevant lines.\n\n" +
+        "Do NOT re-read a file you just edited to verify — Edit/Write would have errored " +
+        "if the change failed.\n" +
+        "Do NOT re-read a file (or the same range of a file) you've already read earlier in " +
+        "this conversation. The content is already in your context. If you need a different " +
+        "part of the file, read a different offset; otherwise decide with what you have.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            file_path: { type: "string", description: "Absolute path to the file to read" },
+            offset: { type: "number", description: "Line number to start reading from (1-based)" },
+            limit: { type: "number", description: "Number of lines to read (default: 2000)" },
+        },
+        required: ["file_path"],
+    },
+};
+const MAX_CONTENT_CHARS = 200_000;
+export async function readTool(args) {
+    const filePath = args.file_path;
+    if (!filePath)
+        return "Error: file_path is required";
+    if (!existsSync(filePath))
+        return `Error: File not found: ${filePath}`;
+    try {
+        // Get file info first
+        const fileInfo = await stat(filePath);
+        const sizeKB = Math.round(fileInfo.size / 1024);
+        // Skip binary or excessively large files
+        if (fileInfo.size > 5 * 1024 * 1024) {
+            return `Error: File is too large (${sizeKB}KB). Use Grep to search for specific content, or provide offset and limit to read a portion.`;
+        }
+        // Try cache first, fall back to disk read
+        let content = await fileCache.get(filePath);
+        if (content === null) {
+            content = await readFile(filePath, "utf-8");
+            fileCache.set(filePath, content, fileInfo.mtimeMs);
+        }
+        const lines = content.split("\n");
+        const totalLines = lines.length;
+        const offset = Math.max(1, args.offset || 1);
+        const limit = args.limit || 2000;
+        const end = Math.min(totalLines, offset - 1 + limit);
+        const selected = lines.slice(offset - 1, end);
+        let numbered = selected.map((line, i) => `${offset + i}\t${line}`).join("\n");
+        // Truncate if too much content
+        if (numbered.length > MAX_CONTENT_CHARS) {
+            numbered = numbered.slice(0, MAX_CONTENT_CHARS) + "\n\n... content truncated";
+        }
+        // Add file metadata header
+        let header = "";
+        if (totalLines > limit || offset > 1) {
+            header = `[${filePath} — ${totalLines} lines total, showing ${offset}-${end}]\n`;
+        }
+        return header + (numbered || "(empty file)");
+    }
+    catch (err) {
+        return `Error reading file: ${err.message}`;
+    }
+}

package/dist/tool-system/builtin/remote-trigger.d.ts

@@ -0,0 +1,6 @@
+/**
+ * RemoteTriggerTool — trigger remote agents/workflows.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const remoteTriggerToolDef: ToolDefinition;
+export declare function remoteTriggerTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/remote-trigger.js

@@ -0,0 +1,54 @@
+/**
+ * RemoteTriggerTool — trigger remote agents/workflows.
+ */
+export const remoteTriggerToolDef = {
+    name: "RemoteTrigger",
+    description: "Trigger a remote agent or workflow to execute a task. " +
+        "The agent runs asynchronously and results can be checked later.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            name: {
+                type: "string",
+                description: "The name/identifier of the remote trigger to execute",
+            },
+            prompt: {
+                type: "string",
+                description: "The task prompt to send to the remote agent",
+            },
+            config: {
+                type: "object",
+                description: "Optional configuration for the remote execution",
+            },
+        },
+        required: ["name", "prompt"],
+    },
+};
+export async function remoteTriggerTool(args) {
+    const name = args.name;
+    const prompt = args.prompt;
+    const config = args.config;
+    // Remote triggers are dispatched via the cron scheduler or external API
+    try {
+        const { existsSync, readFileSync, writeFileSync, mkdirSync } = await import("node:fs");
+        const { join } = await import("node:path");
+        const { homedir } = await import("node:os");
+        // Store trigger request for pickup by external scheduler
+        const triggerDir = join(homedir(), ".code-shell", "triggers");
+        mkdirSync(triggerDir, { recursive: true });
+        const trigger = {
+            id: `trigger_${Date.now()}_${Math.random().toString(36).slice(2, 8)}`,
+            name,
+            prompt,
+            config,
+            createdAt: new Date().toISOString(),
+            status: "pending",
+        };
+        const triggerFile = join(triggerDir, `${trigger.id}.json`);
+        writeFileSync(triggerFile, JSON.stringify(trigger, null, 2), "utf-8");
+        return `Remote trigger "${name}" dispatched (ID: ${trigger.id}).\nStored at: ${triggerFile}`;
+    }
+    catch (err) {
+        return `Remote trigger error: ${err.message}`;
+    }
+}

package/dist/tool-system/builtin/repl.d.ts

@@ -0,0 +1,11 @@
+/**
+ * REPLTool — execute code in an interactive REPL environment.
+ *
+ * The lifecycle (spawn, abort/timeout cascade, IO drain, byte cap) is
+ * centralized in {@link safeSpawn}; this file only carries the language
+ * runtime selection table and the REPL-specific output formatting.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const replToolDef: ToolDefinition;
+export declare function replTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/repl.js

@@ -0,0 +1,82 @@
+/**
+ * REPLTool — execute code in an interactive REPL environment.
+ *
+ * The lifecycle (spawn, abort/timeout cascade, IO drain, byte cap) is
+ * centralized in {@link safeSpawn}; this file only carries the language
+ * runtime selection table and the REPL-specific output formatting.
+ */
+import { safeSpawn } from "../../runtime/safe-spawn.js";
+export const replToolDef = {
+    name: "REPL",
+    description: "Execute code in an interactive REPL environment. Supports JavaScript/TypeScript (Node/Bun), " +
+        "Python, and Ruby. Results are returned as text output.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            language: {
+                type: "string",
+                enum: ["javascript", "typescript", "python", "ruby"],
+                description: "The programming language to execute",
+            },
+            code: {
+                type: "string",
+                description: "The code to execute",
+            },
+            timeout: {
+                type: "number",
+                description: "Timeout in milliseconds (default: 30000)",
+            },
+        },
+        required: ["language", "code"],
+    },
+};
+const REPL_MAX_BUFFER = 1024 * 1024;
+export async function replTool(args, ctx) {
+    const language = args.language;
+    const code = args.code;
+    const timeout = args.timeout ?? 30_000;
+    // A4: child process runs in the Engine's cwd, not the host process cwd.
+    const cwd = ctx?.cwd ?? process.cwd();
+    if (!code.trim()) {
+        return "Error: no code provided.";
+    }
+    // A2: each entry is (file, [args]) so we can spawn without a shell.
+    // Args are passed as separate arguv entries, eliminating the
+    // execSync-style shell-quoting risk.
+    const commands = {
+        javascript: { file: "node", pre: ["-e"] },
+        typescript: typeof globalThis.Bun !== "undefined"
+            ? { file: "bun", pre: ["-e"] }
+            : { file: "npx", pre: ["tsx", "-e"] },
+        python: { file: "python3", pre: ["-c"] },
+        ruby: { file: "ruby", pre: ["-e"] },
+    };
+    const runtime = commands[language];
+    if (!runtime) {
+        return `Unsupported language: ${language}. Supported: ${Object.keys(commands).join(", ")}`;
+    }
+    const wasAbortedBeforeStart = ctx?.signal?.aborted === true;
+    const result = await safeSpawn(runtime.file, [...runtime.pre, code], {
+        cwd,
+        env: { ...process.env },
+        timeoutMs: timeout,
+        maxOutputBytes: REPL_MAX_BUFFER,
+        signal: ctx?.signal,
+    });
+    if (result.aborted) {
+        return wasAbortedBeforeStart
+            ? `${language} aborted before starting.`
+            : `${language} aborted by signal.`;
+    }
+    if (result.timedOut) {
+        return `${language} timed out after ${timeout}ms`;
+    }
+    if (result.spawnFailed) {
+        return `Failed to spawn ${language}: ${result.error ?? "unknown error"}`;
+    }
+    if (result.exitCode !== 0) {
+        const out = [result.stdout.trim(), result.stderr.trim()].filter(Boolean).join("\n");
+        return `Error executing ${language}:\n${out || `exit code ${result.exitCode}`}`;
+    }
+    return result.stdout.trim() || "(no output)";
+}

package/dist/tool-system/builtin/send-message.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SendMessage tool — send messages between named agents.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const sendMessageToolDef: ToolDefinition;
+export declare function sendMessageTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/send-message.js

@@ -0,0 +1,47 @@
+/**
+ * SendMessage tool — send messages between named agents.
+ */
+import { agentCoordinator } from "../../agent/coordinator.js";
+export const sendMessageToolDef = {
+    name: "SendMessage",
+    description: "Send a message to another named agent. The target agent must have been " +
+        "spawned with a 'name' parameter via the Agent tool. " +
+        "Use this for coordinating work between multiple agents.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            to: {
+                type: "string",
+                description: "The name of the target agent",
+            },
+            content: {
+                type: "string",
+                description: "The message content to send",
+            },
+        },
+        required: ["to", "content"],
+    },
+};
+export async function sendMessageTool(args) {
+    const to = args.to;
+    const content = args.content;
+    const from = args.__agentName ?? "main";
+    if (!to)
+        return "Error: 'to' is required";
+    if (!content)
+        return "Error: 'content' is required";
+    const target = agentCoordinator.get(to);
+    if (!target) {
+        const active = agentCoordinator.listActive();
+        const names = active.map((a) => a.name).join(", ");
+        return `Error: No agent named "${to}". Active agents: ${names || "none"}`;
+    }
+    if (target.status !== "running") {
+        return `Agent "${to}" is not running (status: ${target.status}).`;
+    }
+    const sent = agentCoordinator.send(from, to, content);
+    if (!sent) {
+        return `Failed to send message to "${to}".`;
+    }
+    return `Message sent to "${to}".`;
+}

package/dist/tool-system/builtin/skill-prompt.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Skill listing renderer for the system prompt. Mirrors Claude Code's split
+ * between scan/data layer (skills/scanner.ts) and render layer (this file),
+ * matching tools/SkillTool/prompt.ts in CC.
+ */
+import type { SkillDefinition } from "../../skills/scanner.js";
+/**
+ * Render the system-prompt skill listing grouped by namespace.
+ *
+ * Skill names follow the convention `<namespace>:<short>` for plugin
+ * skills (see scanner.ts's `namespacedName`) and plain `<short>` for
+ * skills the user installs into ~/.code-shell/skills or the project's
+ * .code-shell/skills directory.
+ *
+ * A flat list grew unreadable once a few plugins were installed, and
+ * the LLM had to skim 40+ lines under a single heading. Grouping by
+ * namespace keeps related skills adjacent and lets the LLM scan
+ * intents ("which plugin handles X?") in one pass.
+ */
+export declare function buildSkillListing(skills: SkillDefinition[]): string;

package/dist/tool-system/builtin/skill-prompt.js

@@ -0,0 +1,52 @@
+/**
+ * Skill listing renderer for the system prompt. Mirrors Claude Code's split
+ * between scan/data layer (skills/scanner.ts) and render layer (this file),
+ * matching tools/SkillTool/prompt.ts in CC.
+ */
+/**
+ * Render the system-prompt skill listing grouped by namespace.
+ *
+ * Skill names follow the convention `<namespace>:<short>` for plugin
+ * skills (see scanner.ts's `namespacedName`) and plain `<short>` for
+ * skills the user installs into ~/.code-shell/skills or the project's
+ * .code-shell/skills directory.
+ *
+ * A flat list grew unreadable once a few plugins were installed, and
+ * the LLM had to skim 40+ lines under a single heading. Grouping by
+ * namespace keeps related skills adjacent and lets the LLM scan
+ * intents ("which plugin handles X?") in one pass.
+ */
+export function buildSkillListing(skills) {
+    if (skills.length === 0)
+        return "";
+    // Bucket by the part before the first ":" — that is either the
+    // plugin name (e.g. "superpowers") or an empty namespace for
+    // user/project skills, which we group under a friendlier label.
+    const USER_GROUP = "用户 / 项目";
+    const groups = new Map();
+    for (const s of skills) {
+        const colon = s.name.indexOf(":");
+        const key = colon > 0 ? s.name.slice(0, colon) : USER_GROUP;
+        const list = groups.get(key);
+        if (list)
+            list.push(s);
+        else
+            groups.set(key, [s]);
+    }
+    // Stable order: user/project first, then plugin namespaces
+    // alphabetically. The LLM benefits from a predictable layout.
+    const entries = [...groups.entries()].sort(([a], [b]) => {
+        if (a === USER_GROUP)
+            return -1;
+        if (b === USER_GROUP)
+            return 1;
+        return a.localeCompare(b);
+    });
+    const sections = [];
+    for (const [group, list] of entries) {
+        list.sort((a, b) => a.name.localeCompare(b.name));
+        const lines = list.map((s) => s.description ? `- ${s.name}: ${s.description}` : `- ${s.name}:`);
+        sections.push(`## ${group} (${list.length})\n${lines.join("\n")}`);
+    }
+    return `# Available Skills\n\n${sections.join("\n\n")}`;
+}

package/dist/tool-system/builtin/skill.d.ts

@@ -0,0 +1,9 @@
+/**
+ * SkillTool — load a skill's SKILL.md body and return it as the tool result.
+ * The scanner is the single source of truth; this tool never reads the disk
+ * directly. Matches Claude Code's tools/SkillTool/SkillTool.ts pattern.
+ */
+import type { ToolDefinition } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export declare const skillToolDef: ToolDefinition;
+export declare function skillTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;

package/dist/tool-system/builtin/skill.js

@@ -0,0 +1,55 @@
+/**
+ * SkillTool — load a skill's SKILL.md body and return it as the tool result.
+ * The scanner is the single source of truth; this tool never reads the disk
+ * directly. Matches Claude Code's tools/SkillTool/SkillTool.ts pattern.
+ */
+import { dirname } from "node:path";
+import { scanSkills } from "../../skills/scanner.js";
+export const skillToolDef = {
+    name: "Skill",
+    description: "Execute a skill within the main conversation. Skills provide specialized " +
+        "capabilities and domain knowledge. Use this tool with the skill name and " +
+        "optional arguments.",
+    inputSchema: {
+        type: "object",
+        properties: {
+            skill: {
+                type: "string",
+                description: "The skill name to invoke (e.g., 'pdf', 'brainstorming')",
+            },
+            args: {
+                type: "string",
+                description: "Optional arguments substituted into $ARGUMENTS / {args} placeholders",
+            },
+        },
+        required: ["skill"],
+    },
+};
+export async function skillTool(args, ctx) {
+    const skillName = args.skill;
+    const skillArgs = args.args ?? "";
+    if (!skillName) {
+        return "Error: skill name is required.";
+    }
+    // Reject disabled skills before scanning so the user gets a clear
+    // message that distinguishes "disabled" from "not found" — matches
+    // the UI's toggle semantics. The scanner would also filter the entry
+    // out, which alone would produce a misleading "not found" reply.
+    const disabledSkills = ctx?.disabledSkills;
+    if (disabledSkills && disabledSkills.includes(skillName)) {
+        return `Skill "${skillName}" is disabled. Enable it in Customize or remove it from settings.disabledSkills.`;
+    }
+    // A4: scan skills from the Engine's cwd, not the host process cwd.
+    const skills = scanSkills(ctx?.cwd ?? process.cwd(), { disabledSkills });
+    const found = skills.find((s) => s.name === skillName);
+    if (!found) {
+        return `Skill "${skillName}" not found. Run /skills to list available skills.`;
+    }
+    const skillDir = dirname(found.filePath);
+    const body = found.content
+        .replace(/\$ARGUMENTS/g, skillArgs)
+        .replace(/\{args\}/g, skillArgs)
+        .replace(/\$\{CODESHELL_SKILL_DIR\}/g, skillDir)
+        .replace(/\$\{CLAUDE_SKILL_DIR\}/g, skillDir);
+    return `Base directory for this skill: ${skillDir}\n\n${body}`;
+}

package/dist/tool-system/builtin/sleep.d.ts

@@ -0,0 +1,6 @@
+/**
+ * SleepTool — pause execution for a specified duration.
+ */
+import type { ToolDefinition } from "../../types.js";
+export declare const sleepToolDef: ToolDefinition;
+export declare function sleepTool(args: Record<string, unknown>): Promise<string>;

package/dist/tool-system/builtin/sleep.js

@@ -0,0 +1,33 @@
+/**
+ * SleepTool — pause execution for a specified duration.
+ */
+export const sleepToolDef = {
+    name: "Sleep",
+    description: "Pause execution for a specified number of seconds. " +
+        "Useful for polling workflows or waiting for external processes. " +
+        "Maximum duration is 300 seconds (5 minutes).",
+    inputSchema: {
+        type: "object",
+        properties: {
+            seconds: {
+                type: "number",
+                description: "Number of seconds to sleep (max 300)",
+            },
+        },
+        required: ["seconds"],
+    },
+};
+export async function sleepTool(args) {
+    const seconds = Math.min(Math.max(Number(args.seconds) || 1, 0.1), 300);
+    const signal = args.__signal;
+    if (signal?.aborted)
+        return "Sleep aborted.";
+    await new Promise((resolve, reject) => {
+        const timer = setTimeout(resolve, seconds * 1000);
+        signal?.addEventListener("abort", () => {
+            clearTimeout(timer);
+            reject(new Error("Sleep aborted"));
+        });
+    }).catch(() => { });
+    return `Slept for ${seconds} seconds.`;
+}

package/dist/tool-system/builtin/task.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Built-in task management — a single TodoWrite tool, cc-style.
+ *
+ * Design (2026-05-24 simplification, replacing the legacy 6-tool API):
+ *
+ *   - One tool, one shape: TodoWrite({ todos: [{content, status, activeForm}] }).
+ *     Each call replaces the entire snapshot — no per-item update API.
+ *   - The transcript IS the task store. The LLM reads its own last
+ *     TodoWrite tool_use input to know "where am I in the list".
+ *   - No module singleton. No in-memory map. No file persistence.
+ *     Resume hydrates by scanning the loaded transcript for the most
+ *     recent TodoWrite tool_use.
+ *   - Sub-agent isolation: when called from a spawned sub-agent, the
+ *     emitted task_update event carries the sub-agent's id so the UI
+ *     can keep the main and sub-agent todo lists separate (cc bucketing
+ *     by `context.agentId ?? sessionId`).
+ *
+ * Why no TaskManager:
+ *   The legacy TaskCreate/Update/Stop/Get/Output/List sextet stored
+ *   state behind a module-level TaskManager singleton. Desktop spawns
+ *   one worker process per agent/run, so the singleton vanished after
+ *   each run — the next run's `TaskList` returned "No tasks" even
+ *   though the transcript still had the full plan. Replacing the
+ *   sextet with one snapshot tool whose output lives in the transcript
+ *   makes the worker's lifecycle irrelevant: every restart re-reads
+ *   the snapshot for free.
+ */
+import type { ToolDefinition, TaskInfo, TranscriptEvent } from "../../types.js";
+import type { ToolContext } from "../context.js";
+export type TaskStatus = "pending" | "in_progress" | "completed";
+export interface TodoItem {
+    content: string;
+    status: TaskStatus;
+    /** Present-continuous form shown while in_progress (e.g. "Fixing auth"). */
+    activeForm: string;
+}
+export type Task = TaskInfo;
+export declare const todoWriteToolDef: ToolDefinition;
+export declare function todoWriteTool(args: Record<string, unknown>, ctx?: ToolContext): Promise<string>;
+/**
+ * Pull the latest todo snapshot from a transcript's event stream.
+ *
+ * Walks newest-first looking for a `tool_use` event whose toolName is
+ * TodoWrite — its args carry the canonical snapshot. Returns null if
+ * no TodoWrite call exists in the transcript (e.g. fresh session, or
+ * a session where the agent never used the tool).
+ */
+export declare function readLastTodoSnapshot(events: TranscriptEvent[]): TaskInfo[] | null;