neoctl 0.2.4 → 0.2.5

package/dist/repl/index.js

@@ -27,11 +27,17 @@ import { createTaskTools } from "../tasks/task-tools.js";
 import { TaskStore } from "../tasks/task-store.js";
 import { cliHelpText, isModelReasoningArgument, isValidReplCommandLine, parseCliReplCommandArgs, parseReplCommand, helpText, replCommandDefinitions } from "./commands.js";
 import { estimateMarkdownLineCount, markdownRenderKey, MarkdownText } from "./markdown-renderer.js";
+import { DefaultContextManager } from "../context/context-manager.js";
+import { buildEffectiveSystemPrompt } from "../context/prompts.js";
 import { writeSessionMarkdownExport } from "../session/session-export.js";
 import { readClipboard } from "./clipboard.js";
 import { formatTipLine, initialTipIndex, tipAt } from "../tips.js";
 import { openDirectory } from "../open-directory.js";
 import { runWebServer } from "../web/index.js";
+import { getNeoctlHome } from "../paths.js";
+import { FileSystemSkillCatalog } from "../skills/skill-filesystem.js";
+import { createSkillAwareCanUseTool, createSkillTool, requireSkillName } from "../skills/skill-tool.js";
+import { createSkillManagementTools } from "../skills/skill-management-tools.js";
 const e = React.createElement;
 class SessionUsageTracker {
     totals = emptyUsageTotals();
@@ -128,6 +134,50 @@ function binaryName() {
     const name = parsed.name || "neo";
     return name === "index" ? "neo" : name;
 }
+class SkillCatalogContextManager {
+    catalog;
+    base;
+    constructor(catalog, base = new DefaultContextManager()) {
+        this.catalog = catalog;
+        this.base = base;
+    }
+    async build(input) {
+        const runtimeContext = await this.base.build(input);
+        const skillSection = await buildSkillCatalogPromptSection(this.catalog);
+        if (!skillSection)
+            return runtimeContext;
+        const promptSections = [...runtimeContext.promptSections, skillSection];
+        return {
+            ...runtimeContext,
+            promptSections,
+            systemPrompt: buildEffectiveSystemPrompt(promptSections, input),
+        };
+    }
+}
+async function buildSkillCatalogPromptSection(catalog) {
+    const skills = await catalog.list();
+    if (skills.length === 0)
+        return undefined;
+    const visible = skills.slice(0, 80);
+    const lines = visible.map((skill) => {
+        const tags = skill.tags?.length ? `; tags=${skill.tags.join(",")}` : "";
+        const tools = skill.allowedTools?.length ? `; allowedTools=${skill.allowedTools.join(",")}` : "";
+        return `- ${skill.name}: ${skill.description} (execution=${skill.execution}${tags}${tools})`;
+    });
+    if (skills.length > visible.length)
+        lines.push(`- ... ${skills.length - visible.length} more skills available; use skill_list for the full catalog.`);
+    return {
+        name: "Available Skills",
+        cacheStable: false,
+        content: [
+            "Reusable skills are available through the `skill` tool and the `/skill` REPL command.",
+            "When the user's task matches a skill name, description, tags, or domain capability, proactively call the `skill` tool before doing the work directly.",
+            "Do not wait for the user to explicitly say 'use skill'. Use skill_list/skill_read if you need to inspect details.",
+            "Available skill catalog:",
+            ...lines,
+        ].join("\n"),
+    };
+}
 function createTaskNotificationSource(taskStore) {
     return {
         collectUnnotifiedCompletions() {
@@ -151,6 +201,14 @@ async function createRuntime() {
     const modelGateway = new LoggingModelGateway(createModelGatewayFromProcessEnv(process.env), communicationLogger);
     const taskStore = new TaskStore();
     const tools = new ToolRegistry();
+    const skillWorkspaceRoot = path.resolve(process.cwd(), ".neo", "skills");
+    const skills = new FileSystemSkillCatalog({
+        roots: [
+            { root: skillWorkspaceRoot, kind: "workspace" },
+            { root: path.resolve(getNeoctlHome(), "skills"), kind: "user" },
+        ],
+        createRoot: skillWorkspaceRoot,
+    });
     tools.register(editTool);
     tools.register(writeTool);
     tools.register(createExecTool({ taskStore }));
@@ -162,6 +220,9 @@ async function createRuntime() {
     if (modelConfig?.provider === "openai")
         tools.register(createOpenAIImageGenerationTool());
     tools.register(planTool);
+    tools.register(createSkillTool(skills));
+    for (const tool of createSkillManagementTools(skills, { requireApproval: true, allowDelete: false }))
+        tools.register(tool);
     const agentRuntime = { modelGateway, tools, taskStore };
     tools.register(createAgentTool(agentRuntime));
     const resumeHandler = async (taskId, directive) => {
@@ -183,6 +244,8 @@ async function createRuntime() {
         reasoning: modelConfig?.defaultReasoning,
         modelGateway,
         tools,
+        contextManager: new SkillCatalogContextManager(skills),
+        canUseTool: createSkillAwareCanUseTool(skills),
         taskNotificationSource,
         commands: replCommandDefinitions.map((command) => command.usage),
         session: {
@@ -205,6 +268,8 @@ async function createRuntime() {
         usage: new SessionUsageTracker(),
         taskStore,
         tools,
+        skills,
+        skillWorkspaceRoot,
         initialMetrics,
         defaultReasoning: modelConfig?.defaultReasoning,
         envPath: process.env.NEO_ENV_FILE?.trim() ? path.resolve(process.env.NEO_ENV_FILE.trim()) : envLoad.userDotEnvPath,
@@ -418,6 +483,7 @@ function InkRepl({ runtime, initialCommandLine }) {
     const [pasteStatus, setPasteStatus] = useState(undefined);
     const pasteStatusTimerRef = useRef(undefined);
     const [slashCompletionIndex, setSlashCompletionIndex] = useState(0);
+    const [skillCompletions, setSkillCompletions] = useState([]);
     const [loginForm, setLoginForm] = useState(undefined);
     const loginFormRef = useRef(undefined);
     useEffect(() => {
@@ -488,6 +554,18 @@ function InkRepl({ runtime, initialCommandLine }) {
         loginFormRef.current = next;
         setLoginForm(next);
     };
+    const refreshSkillCompletions = useCallback(async () => {
+        try {
+            const skills = await runtime.skills.list();
+            setSkillCompletions(skills.map((skill) => ({ name: skill.name, description: skill.description, execution: skill.execution, tags: skill.tags })));
+        }
+        catch {
+            setSkillCompletions([]);
+        }
+    }, [runtime]);
+    useEffect(() => {
+        void refreshSkillCompletions();
+    }, [refreshSkillCompletions]);
     const syncAttachmentsForText = (text) => {
         const next = attachmentsRef.current.filter((attachment) => text.includes(attachment.label));
         if (next.length === attachmentsRef.current.length)
@@ -855,6 +933,7 @@ function InkRepl({ runtime, initialCommandLine }) {
     };
     const handleCommandOrPrompt = async (text, submitAttachments = []) => {
         const command = parseReplCommand(text);
+        let promptText = command.type === "input" ? command.text : text;
         if (command.type === "exit") {
             app.exit();
             return;
@@ -993,6 +1072,16 @@ function InkRepl({ runtime, initialCommandLine }) {
             await handleSessionsCommand(runtime, runningSessionIds(backgroundSessionRunsRef.current), setSessionsBrowser, (line) => append(line));
             return;
         }
+        if (command.type === "skill") {
+            if (command.action !== "invoke" || !command.name || !command.args) {
+                append(await handleSkillCommand(command, runtime));
+                if (command.action === "import" || command.action === "delete")
+                    void refreshSkillCompletions();
+                return;
+            }
+            promptText = renderSkillInvocationPrompt(command.name, command.args);
+            text = `/skill ${command.name} ${command.args}`;
+        }
         if (command.type === "login") {
             setSessionsBrowser(undefined);
             setLoginFormState(createLoginFormState(runtime.envPath));
@@ -1023,11 +1112,11 @@ function InkRepl({ runtime, initialCommandLine }) {
             }
             return;
         }
-        if (text.trimStart().startsWith("/")) {
+        if (command.type !== "skill" && text.trimStart().startsWith("/")) {
             append({ kind: "error", text: `Unknown or incomplete command: ${text.trim()}\nType /help for commands.` });
             return;
         }
-        const promptPayload = buildPromptPayload(command.text, submitAttachments);
+        const promptPayload = buildPromptPayload(promptText, submitAttachments);
         append({ kind: "user", text });
         const runToken = ++foregroundRunTokenRef.current;
         const abortController = new AbortController();
@@ -1131,7 +1220,7 @@ function InkRepl({ runtime, initialCommandLine }) {
     const promptDisplayCursor = cursor;
     const promptLayoutText = activePlaceholder ? ` ${activePlaceholder}` : promptDisplayText;
     const promptLayoutCursor = activePlaceholder ? 0 : promptDisplayCursor;
-    const slashCompletions = inputLockedByQueue || (input.length === 0 && promptPlaceholder !== undefined) || loginForm ? [] : slashCommandCompletions(input, cursor);
+    const slashCompletions = inputLockedByQueue || (input.length === 0 && promptPlaceholder !== undefined) || loginForm ? [] : slashCommandCompletions(input, cursor, skillCompletions);
     const visibleSlashCompletionCount = slashCompletions.length;
     const selectedSlashCompletionIndex = visibleSlashCompletionCount === 0
         ? 0
@@ -1248,12 +1337,21 @@ function InkRepl({ runtime, initialCommandLine }) {
         if (key.return) {
             const currentText = inputRef.current;
             const currentCursor = cursorRef.current;
-            const completion = selectedSlashCommandCompletion(currentText, currentCursor, slashCompletionIndexRef.current);
+            const completion = selectedSlashCommandCompletion(currentText, currentCursor, slashCompletionIndexRef.current, skillCompletions);
             if (completion !== undefined && completion.kind === "command" && completion.arguments !== "none") {
                 const nextText = `${completion.insertText} ${currentText.slice(currentCursor)}`;
                 setPromptState(nextText, completion.insertText.length + 1);
                 return;
             }
+            if (currentText.trimEnd() === "/skill") {
+                void submitLine(currentText);
+                return;
+            }
+            if (completion !== undefined && completion.kind === "skill-action") {
+                const nextText = `${completion.insertText}${currentText.slice(currentCursor)}`;
+                setPromptState(nextText, completion.insertText.length);
+                return;
+            }
             if (currentText.trimEnd() === "/model" && completion?.kind !== "command") {
                 void submitLine(currentText);
                 return;
@@ -1274,7 +1372,7 @@ function InkRepl({ runtime, initialCommandLine }) {
             return;
         }
         if (key.leftArrow) {
-            const completionCount = slashCompletionSelectableCount(inputRef.current, cursorRef.current);
+            const completionCount = slashCompletionSelectableCount(inputRef.current, cursorRef.current, skillCompletions);
             if (completionCount > SLASH_COMPLETION_PAGE_SIZE) {
                 setSlashCompletionSelection((slashCompletionIndexRef.current + completionCount - SLASH_COMPLETION_PAGE_SIZE) % completionCount);
                 return;
@@ -1287,7 +1385,7 @@ function InkRepl({ runtime, initialCommandLine }) {
             return;
         }
         if (key.rightArrow) {
-            const completionCount = slashCompletionSelectableCount(inputRef.current, cursorRef.current);
+            const completionCount = slashCompletionSelectableCount(inputRef.current, cursorRef.current, skillCompletions);
             if (completionCount > SLASH_COMPLETION_PAGE_SIZE) {
                 setSlashCompletionSelection((slashCompletionIndexRef.current + SLASH_COMPLETION_PAGE_SIZE) % completionCount);
                 return;
@@ -1318,7 +1416,7 @@ function InkRepl({ runtime, initialCommandLine }) {
                 setTipIndex((current) => current - 1);
                 return;
             }
-            const completionCount = slashCompletionSelectableCount(inputRef.current, cursorRef.current);
+            const completionCount = slashCompletionSelectableCount(inputRef.current, cursorRef.current, skillCompletions);
             if (completionCount > 0) {
                 setSlashCompletionSelection((slashCompletionIndexRef.current + completionCount - 1) % completionCount);
                 return;
@@ -1335,7 +1433,7 @@ function InkRepl({ runtime, initialCommandLine }) {
                 setTipIndex((current) => current + 1);
                 return;
             }
-            const completionCount = slashCompletionSelectableCount(inputRef.current, cursorRef.current);
+            const completionCount = slashCompletionSelectableCount(inputRef.current, cursorRef.current, skillCompletions);
             if (completionCount > 0) {
                 setSlashCompletionSelection((slashCompletionIndexRef.current + 1) % completionCount);
                 return;
@@ -1361,7 +1459,7 @@ function InkRepl({ runtime, initialCommandLine }) {
                 return;
             }
             const currentCursor = cursorRef.current;
-            const completions = slashCommandCompletions(currentText, currentCursor);
+            const completions = slashCommandCompletions(currentText, currentCursor, skillCompletions);
             const completion = completions[Math.min(slashCompletionIndexRef.current, completions.length - 1)];
             if (completion !== undefined) {
                 const nextText = `${completion.insertText}${currentText.slice(currentCursor)}`;
@@ -1806,7 +1904,11 @@ function fitStatusSegments(segments, width) {
 const SLASH_COMPLETION_PAGE_SIZE = 10;
 const MODEL_REASONING_EFFORTS = ["none", "minimal", "low", "medium", "high", "xhigh", "max"];
 const MODEL_REASONING_CONTROL_CHOICES = ["default", "off"];
-function slashCommandCompletions(text, cursor) {
+const SKILL_COMMAND_ACTIONS = [
+    { name: "import", description: "Import by linking a skill directory" },
+    { name: "delete", description: "Delete a workspace skill link/directory", aliases: ["remove", "rm"] },
+];
+function slashCommandCompletions(text, cursor, skills = []) {
     const safeCursor = Math.max(0, Math.min(cursor, text.length));
     const prefix = text.slice(0, safeCursor);
     if (!prefix.startsWith("/") || /\r|\n/.test(prefix))
@@ -1819,6 +1921,9 @@ function slashCommandCompletions(text, cursor) {
     if (prefix.startsWith("/model") && (prefix.length === "/model".length || prefix["/model".length] === " ")) {
         return modelCommandCompletions(prefix);
     }
+    if (prefix.startsWith("/skill") && (prefix.length === "/skill".length || prefix["/skill".length] === " ")) {
+        return skillCommandCompletions(prefix, skills);
+    }
     if (prefix.length > 1 && !/^\/[\w-]*$/.test(prefix))
         return [];
     const normalizedPrefix = prefix.toLowerCase();
@@ -1826,6 +1931,56 @@ function slashCommandCompletions(text, cursor) {
         .flatMap((command) => [command.name, ...(command.aliases ?? [])].map((name) => ({ value: name, insertText: name, description: command.description, arguments: command.arguments, kind: "command" })))
         .filter((command) => command.value.toLowerCase().startsWith(normalizedPrefix));
 }
+function skillCommandCompletions(prefix, skills) {
+    const hasTrailingSpace = /\s$/.test(prefix);
+    const tokens = prefix.trim().split(/\s+/).filter(Boolean);
+    const argumentTokens = tokens.slice(1);
+    if (!hasTrailingSpace && argumentTokens.length === 0 && !"/skill".startsWith(prefix.toLowerCase()))
+        return [];
+    if (argumentTokens.length === 0) {
+        return [...skillActionCompletions(""), ...skillNameCompletions(skills, "")];
+    }
+    const [first = "", second = ""] = argumentTokens;
+    if (first === "import")
+        return [];
+    if (first === "delete" || first === "remove" || first === "rm") {
+        if (argumentTokens.length > 1 && hasTrailingSpace)
+            return [];
+        return skillNameCompletions(skills, hasTrailingSpace ? "" : second, "delete");
+    }
+    if (argumentTokens.length > 1)
+        return [];
+    if (hasTrailingSpace)
+        return [];
+    return [...skillActionCompletions(first), ...skillNameCompletions(skills, first)];
+}
+function skillActionCompletions(current) {
+    return SKILL_COMMAND_ACTIONS
+        .flatMap((action) => [action.name, ...("aliases" in action ? action.aliases ?? [] : [])].map((name) => ({ name, description: action.description })))
+        .filter((action) => action.name.startsWith(current.toLowerCase()))
+        .map((action) => ({
+        value: action.name,
+        insertText: `/skill ${action.name} `,
+        description: action.description,
+        arguments: "optional",
+        kind: "skill-action",
+    }));
+}
+function skillNameCompletions(skills, current, action) {
+    return skills
+        .filter((skill) => skill.name.toLowerCase().includes(current.toLowerCase()))
+        .map((skill) => ({
+        value: skill.name,
+        insertText: action === "delete" ? `/skill delete ${skill.name}` : `/skill ${skill.name}`,
+        description: formatSkillCompletionDescription(skill),
+        arguments: "optional",
+        kind: "skill",
+    }));
+}
+function formatSkillCompletionDescription(skill) {
+    const tags = skill.tags?.length ? ` · ${skill.tags.join(",")}` : "";
+    return `${skill.description}${skill.execution ? ` · ${skill.execution}` : ""}${tags}`;
+}
 function modelCommandCompletions(prefix) {
     const hasTrailingSpace = /\s$/.test(prefix);
     const tokens = prefix.trim().split(/\s+/).filter(Boolean);
@@ -1911,11 +2066,11 @@ function slashCompletionViewHeight(completions) {
         return 0;
     return Math.min(completions.length, SLASH_COMPLETION_PAGE_SIZE) + 2;
 }
-function slashCompletionSelectableCount(text, cursor) {
-    return slashCommandCompletions(text, cursor).length;
+function slashCompletionSelectableCount(text, cursor, skills = []) {
+    return slashCommandCompletions(text, cursor, skills).length;
 }
-function selectedSlashCommandCompletion(text, cursor, selectedIndex) {
-    const completions = slashCommandCompletions(text, cursor);
+function selectedSlashCommandCompletion(text, cursor, selectedIndex, skills = []) {
+    const completions = slashCommandCompletions(text, cursor, skills);
     if (completions.length === 0)
         return undefined;
     return completions[Math.max(0, Math.min(selectedIndex, completions.length - 1))];
@@ -1988,6 +2143,126 @@ function SlashCompletionLines({ completions, width, prompt, selectedIndex }) {
         e(Text, { key: "slash-completion-footer", color: "gray" }, fitToWidth(footer, contentWidth)),
     ].map((line, index) => e(Box, { key: `slash-completion-line-${index}`, height: 1, overflow: "hidden" }, e(Text, { color: "gray" }, " ".repeat(prompt.length)), line));
 }
+async function handleSkillCommand(command, runtime) {
+    if (command.action === "import")
+        return handleSkillImportCommand(command, runtime);
+    if (command.action === "delete")
+        return handleSkillDeleteCommand(command, runtime);
+    if (!command.name) {
+        const skills = await runtime.skills.list();
+        return systemLine(formatSkillList(skills), EXPANDED_SUMMARY_MAX_LINES);
+    }
+    const skill = await runtime.skills.get(command.name);
+    if (!skill)
+        return { kind: "error", text: `Unknown skill: ${command.name}\nUse /skill to list available skills.` };
+    return systemLine(formatSkillDetails(skill), EXPANDED_SUMMARY_MAX_LINES);
+}
+async function handleSkillImportCommand(command, runtime) {
+    if (!command.path)
+        return { kind: "error", text: "Usage: /skill import <path-to-skill-directory> [name]" };
+    const sourceDirectory = path.resolve(command.path);
+    const skillFile = path.join(sourceDirectory, "SKILL.md");
+    try {
+        const stat = await fs.stat(skillFile);
+        if (!stat.isFile())
+            return { kind: "error", text: `SKILL.md is not a file: ${skillFile}` };
+    }
+    catch (error) {
+        return { kind: "error", text: `Invalid skill path: ${skillFile}\n${error instanceof Error ? error.message : String(error)}` };
+    }
+    const name = requireSkillName(command.name ?? path.basename(sourceDirectory));
+    const linkPath = path.join(runtime.skillWorkspaceRoot, name);
+    const relativeTarget = path.relative(path.dirname(linkPath), sourceDirectory) || sourceDirectory;
+    try {
+        await fs.mkdir(runtime.skillWorkspaceRoot, { recursive: true });
+        const existing = await safeLstat(linkPath);
+        if (existing)
+            return { kind: "error", text: `Skill already exists at ${linkPath}. Delete it first with /skill delete ${name}.` };
+        await fs.symlink(relativeTarget, linkPath, "junction");
+        const imported = await runtime.skills.get(name);
+        return systemLine(`Imported skill ${name}\nLink: ${linkPath}\nTarget: ${sourceDirectory}${imported ? `\nDescription: ${imported.description}` : ""}`);
+    }
+    catch (error) {
+        return { kind: "error", text: `Failed to import skill ${name}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+async function handleSkillDeleteCommand(command, runtime) {
+    if (!command.name)
+        return { kind: "error", text: "Usage: /skill delete <name>" };
+    const name = requireSkillName(command.name);
+    const skillPath = path.join(runtime.skillWorkspaceRoot, name);
+    const existing = await safeLstat(skillPath);
+    if (!existing)
+        return { kind: "error", text: `No workspace skill named ${name} at ${skillPath}` };
+    try {
+        if (existing.isSymbolicLink())
+            await fs.unlink(skillPath);
+        else
+            await fs.rm(skillPath, { recursive: true, force: true });
+        return systemLine(`Deleted workspace skill ${name}: ${skillPath}`);
+    }
+    catch (error) {
+        return { kind: "error", text: `Failed to delete skill ${name}: ${error instanceof Error ? error.message : String(error)}` };
+    }
+}
+async function safeLstat(file) {
+    try {
+        return await fs.lstat(file);
+    }
+    catch {
+        return undefined;
+    }
+}
+function renderSkillInvocationPrompt(name, args) {
+    return `Use skill ${JSON.stringify(name)} with these arguments:\n${args}`;
+}
+function formatSkillList(skills) {
+    if (skills.length === 0) {
+        return [
+            "No skills found.",
+            "Skill roots:",
+            "  - .neo/skills/<name>/SKILL.md",
+            "  - ~/.neoctl/skills/<name>/SKILL.md",
+            "Create one with the skill_create tool or add a SKILL.md file.",
+        ].join("\n");
+    }
+    const width = Math.max(...skills.map((skill) => skill.name.length));
+    return [
+        "Available skills:",
+        ...skills.map((skill) => {
+            const tags = skill.tags?.length ? ` [${skill.tags.join(", ")}]` : "";
+            const execution = skill.execution ? ` (${skill.execution})` : "";
+            return `  ${skill.name.padEnd(width)}  ${skill.description}${execution}${tags}`;
+        }),
+        "",
+        "Usage:",
+        "  /skill <name>                 Show skill details",
+        "  /skill <name> <args>          Invoke skill with arguments",
+        "  /skill import <path> [name]   Import by linking a skill directory",
+        "  /skill delete <name>          Delete workspace skill link/directory",
+    ].join("\n");
+}
+function formatSkillDetails(skill) {
+    const lines = [
+        `Skill: ${skill.name}`,
+        skill.title ? `Title: ${skill.title}` : undefined,
+        `Description: ${skill.description}`,
+        `Execution: ${skill.execution}`,
+        skill.version ? `Version: ${skill.version}` : undefined,
+        skill.tags?.length ? `Tags: ${skill.tags.join(", ")}` : undefined,
+        skill.allowedTools?.length ? `Allowed tools: ${skill.allowedTools.join(", ")}` : undefined,
+        skill.model ? `Model: ${skill.model}` : undefined,
+        skill.effort ? `Effort: ${skill.effort}` : undefined,
+        skill.trustLevel ? `Trust: ${skill.trustLevel}` : undefined,
+        skill.source?.path ? `Path: ${skill.source.path}` : undefined,
+        "",
+        "Entrypoint:",
+        skill.entrypoint,
+        "",
+        `Invoke: /skill ${skill.name} <args>`,
+    ].filter((line) => line !== undefined);
+    return lines.join("\n");
+}
 async function handleModelCommand(command, runtime) {
     const current = runtime.engine.getModelSettings();
     const nextModel = command.model ?? current.model;
@@ -3034,9 +3309,11 @@ function formatToolUse(toolUse) {
             text: formatPlanToolPayload(toolUse.input),
         };
     }
+    const description = toolUse.name === "exec" ? execDescriptionFromInput(toolUse.input) : undefined;
     return {
         kind: "tool",
         title: toolTitle(toolUse.name, "running"),
+        bodyTitle: description,
         text: formatJson(toolUse.input, 1200),
         previewStyle: "summary",
     };
@@ -3063,9 +3340,11 @@ function formatToolResultLine(toolName, output, ok) {
 }
 function formatToolFinishedWithoutResult(toolUse, ok) {
     const inputText = formatJson(toolUse.input, 1200);
+    const description = toolUse.name === "exec" ? execDescriptionFromInput(toolUse.input) : undefined;
     return {
         kind: ok ? "tool" : "error",
         title: toolTitle(toolUse.name, "finished"),
+        bodyTitle: description,
         titleStatus: ok ? "success" : "failure",
         text: inputText ? `${ok ? "finished" : "failed"}\n${inputText}` : ok ? "finished" : "failed",
         previewStyle: "summary",
@@ -3078,6 +3357,12 @@ function toolTitle(toolName, phase) {
         return `${phase === "running" ? "◇" : "◆"} plan`;
     return `${phase === "running" ? "◇" : "◆"} ${toolName}`;
 }
+function execDescriptionFromInput(input) {
+    if (!isRecord(input))
+        return undefined;
+    const description = typeof input.description === "string" ? input.description.trim() : "";
+    return description || undefined;
+}
 function isPlanToolPayload(value) {
     if (!isRecord(value) || !Array.isArray(value.items))
         return false;
@@ -3301,8 +3586,10 @@ function formatExecToolResult(output, ok) {
         : output.exitCode === 0
             ? "exit 0"
             : `exit ${output.exitCode ?? output.signal ?? "unknown"}`;
+    const description = typeof output.description === "string" ? output.description.trim() : "";
     const lines = [
         "exec result",
+        ...(description ? [`purpose: ${description}`] : []),
         `status: ${status}`,
         `duration: ${output.durationMs}ms`,
         `command: ${output.command}`,