ikie-cli 0.1.33 → 0.1.34

package/dist/agent.js

@@ -1,9 +1,14 @@
 import chalk from 'chalk';
 import * as readline from 'node:readline';
-import { TOOL_DEFS, SAFE_TOOLS, PLAN_TOOLS, formatToolArgs, executeTool, isRestrictedPath } from './tools.js';
+import { TOOL_DEFS, SAFE_TOOLS, PLAN_TOOLS, formatToolArgs, executeTool, isRestrictedPath, getMcpToolDefs } from './tools.js';
 import { IKIE_PORT } from './config.js';
 import { renderMarkdown, extractThinkTags } from './renderer.js';
+import { getSkill, renderSkill, mapAllowedTools } from './skills.js';
 import { c, toolLine, toolSuccessLine, toolErrorLine, toolOutputBlock, toolDiffBlock, InlineSpinner, CH, toolMeta } from './theme.js';
+/** Default per-turn step budget — guards against runaway tool loops. */
+export const DEFAULT_MAX_STEPS = 60;
+/** Result synthesized for a tool call that never produced one (cancel/crash). */
+export const INTERRUPTED_TOOL_RESULT = 'Interrupted: this tool did not run to completion (the turn was cancelled).';
 export function estimateTokens(chars) {
     return Math.max(1, Math.round(chars / 4));
 }
@@ -21,6 +26,59 @@ export function extractUpstreamError(err) {
         e.message;
     return upstream || 'Unknown error';
 }
+/**
+ * Guarantee the OpenAI invariant: every `assistant` message that carries
+ * `tool_calls` is followed by a `tool` message for each call id. A turn that is
+ * cancelled (ESC/Ctrl-C), throws mid-stream, or is restored from a session saved
+ * mid-flight can leave "dangling" tool calls with no result — and the provider
+ * then rejects the *next* request ("an assistant message with 'tool_calls' must
+ * be followed by tool messages"). This splices a synthetic result for any
+ * unanswered call so history is always replayable. Pure and idempotent.
+ */
+export function repairDanglingToolCalls(messages) {
+    const answeredIds = new Set();
+    for (const m of messages) {
+        if (m.role === 'tool') {
+            const id = m.tool_call_id;
+            if (typeof id === 'string')
+                answeredIds.add(id);
+        }
+    }
+    const out = [];
+    for (const m of messages) {
+        out.push(m);
+        if (m.role !== 'assistant')
+            continue;
+        const tcs = m.tool_calls;
+        if (!Array.isArray(tcs))
+            continue;
+        for (const tc of tcs) {
+            if (tc?.id && !answeredIds.has(tc.id)) {
+                out.push({ role: 'tool', tool_call_id: tc.id, content: INTERRUPTED_TOOL_RESULT });
+                answeredIds.add(tc.id);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Whether the agent loop should make another model call. We continue purely on
+ * "there were tool calls to answer" — NOT on `finishReason`, because some
+ * providers send `finish_reason: 'stop'` (or null) alongside tool calls, which
+ * would otherwise silently drop the calls. `maxSteps` caps runaway loops.
+ */
+export function shouldContinue(toolCallCount, _finishReason, step, maxSteps) {
+    return toolCallCount > 0 && step < maxSteps;
+}
+/**
+ * Drop malformed tool calls (no function name) accumulated from a stream. An
+ * unnamed call can't be dispatched or answered, so keeping it would create an
+ * un-satisfiable `tool_calls` entry. Applied to both the dispatch list and the
+ * assistant message so they stay in lockstep.
+ */
+export function normalizeToolCalls(calls) {
+    return calls.filter(tc => typeof tc.name === 'string' && tc.name.trim().length > 0);
+}
 /**
  * Safely restore previously-saved stdin listeners after a raw-mode interaction
  * (permission prompt, ask_user, theme picker, agent turn).
@@ -45,6 +103,44 @@ const requestTimestamps = [];
 function sleep(ms) {
     return new Promise(resolve => setTimeout(resolve, ms));
 }
+/** Extract HTTP status from an OpenAI/fetch error. */
+function extractStatus(err) {
+    const e = err;
+    if (typeof e.status === 'number')
+        return e.status;
+    if (e.response?.status)
+        return e.response.status;
+    return null;
+}
+/**
+ * Retry a function on transient failures (network errors, 5xx, 429) with
+ * exponential backoff + jitter. Does NOT retry 4xx (except 429).
+ */
+async function withRetry(fn, opts) {
+    const maxRetries = opts?.maxRetries ?? 2;
+    let lastErr;
+    for (let attempt = 0; attempt <= maxRetries; attempt++) {
+        if (attempt > 0) {
+            const delay = Math.min(1000 * Math.pow(2, attempt - 1), 8000) + Math.random() * 1000;
+            if (opts?.label) {
+                process.stdout.write(`\n  ${c.muted(`Retry ${attempt}/${maxRetries} for ${opts.label} in ${(delay / 1000).toFixed(1)}s`)}`);
+            }
+            await sleep(delay);
+        }
+        try {
+            return await fn();
+        }
+        catch (err) {
+            lastErr = err;
+            if (opts?.signal?.aborted)
+                throw err;
+            const status = extractStatus(err);
+            if (status && status >= 400 && status < 500 && status !== 429)
+                throw err;
+        }
+    }
+    throw lastErr;
+}
 /**
  * True when a bash command tries to kill/free processes by ikie's own host
  * port — `kill $(lsof -ti:PORT)`, `fuser -k PORT/tcp`, `pkill ... PORT`, etc.
@@ -74,7 +170,7 @@ function toolPhaseLabel(name) {
         case 'write_file': return 'Writing file';
         case 'edit_file': return 'Editing file';
         case 'read_file': return 'Reading';
-        case 'bash': return 'Preparing command';
+        case 'bash': return 'Running command';
         case 'spawn_agent': return 'Spawning agent';
         case 'list_dir': return 'Listing directory';
         case 'search_files': return 'Searching';
@@ -89,7 +185,15 @@ function toolPhaseLabel(name) {
         case 'use_skill': return 'Loading skill';
         case 'install_skill': return 'Installing skill';
         case 'remove_skill': return 'Removing skill';
-        default: return `Preparing ${name}`;
+        case 'mcp_list': return 'Listing MCP servers';
+        case 'mcp_add': return 'Adding MCP server';
+        default: {
+            if (name.startsWith('mcp__')) {
+                const parts = name.split('__');
+                return `MCP ${parts[1] ?? '?'}`;
+            }
+            return `Running ${name}`;
+        }
     }
 }
 export class Agent {
@@ -119,7 +223,8 @@ export class Agent {
         return this.conversation;
     }
     setConversation(messages) {
-        this.conversation = [...messages];
+        // Loaded sessions may have been saved mid-turn — repair before reuse.
+        this.conversation = repairDanglingToolCalls(messages);
     }
     getLastTurnStats() {
         return { ...this.lastTurnStats };
@@ -143,7 +248,7 @@ export class Agent {
         if (!this.conversation.length)
             return { before: 0, after: 0 };
         const before = this.estimateConversationTokens();
-        const res = await this.client.chat.completions.create({
+        const res = await withRetry(() => this.client.chat.completions.create({
             model: this.config.model,
             max_tokens: 4096,
             messages: [
@@ -161,7 +266,7 @@ export class Agent {
                         + 'This summary will replace the full conversation history.',
                 },
             ],
-        });
+        }), { label: 'compact' });
         const summary = res.choices[0]?.message?.content ?? '(no summary)';
         this.conversation = [
             {
@@ -185,6 +290,9 @@ export class Agent {
     async send(userMessage, opts = {}) {
         this.activeTurnStats = { modelCalls: 0, toolCalls: 0, filesChanged: 0 };
         this.activeChangedFiles = new Set();
+        // A prior turn may have ended mid-tool-call (cancelled/errored). Heal the
+        // history before adding the new turn so the request is always valid.
+        this.conversation = repairDanglingToolCalls(this.conversation);
         this.conversation.push({ role: 'user', content: userMessage });
         try {
             await this.runLoop(opts);
@@ -250,20 +358,67 @@ export class Agent {
     }
     // ── Main agent loop ───────────────────────────────────────────────────────
     async runLoop(opts) {
+        const maxSteps = Math.max(1, opts.maxSteps ?? DEFAULT_MAX_STEPS);
+        let step = 0;
         while (true) {
             if (opts.signal?.aborted)
                 break;
+            step++;
             const { assistantMsg, toolCalls, finishReason } = await this.callModel(opts);
             this.conversation.push(assistantMsg);
-            if (opts.signal?.aborted)
-                break;
-            if (finishReason !== 'tool_calls' || !toolCalls.length)
+            // No tool calls → the model is done talking. Stop (regardless of how the
+            // provider labelled finish_reason).
+            if (!toolCalls.length)
                 break;
+            // Track which tool_call ids we've answered so we can guarantee the
+            // assistant message stays balanced even if the turn is cancelled partway.
+            const answered = new Set();
+            const pushResult = (id, content) => {
+                if (answered.has(id))
+                    return;
+                answered.add(id);
+                this.conversation.push({ role: 'tool', tool_call_id: id, content });
+            };
             const groups = this.groupToolCalls(toolCalls);
+            // ── Pass 1: all spawn_agents in parallel across groups ──────────────
+            const spawnResults = new Map(); // tool_call_id → result
+            {
+                const spawnTasks = [];
+                for (const group of groups) {
+                    for (const tc of group) {
+                        if (tc.name === 'spawn_agent') {
+                            let input;
+                            try {
+                                input = JSON.parse(tc.argsStr || '{}');
+                            }
+                            catch {
+                                input = {};
+                            }
+                            spawnTasks.push({ tc, input });
+                        }
+                    }
+                }
+                if (spawnTasks.length > 0) {
+                    if (this.activeTurnStats)
+                        this.activeTurnStats.toolCalls += spawnTasks.length;
+                    const results = await Promise.all(spawnTasks.map(st => this.runSubagent(st.input, opts)));
+                    spawnTasks.forEach((st, i) => spawnResults.set(st.tc.id, results[i]));
+                }
+            }
+            // ── Pass 2: remaining groups in order ──────────────────────────────
             for (const group of groups) {
                 if (opts.signal?.aborted)
                     break;
-                const inputs = group.map(tc => {
+                // Push spawn_agent results for any spawn calls in this group
+                for (const tc of group) {
+                    const r = spawnResults.get(tc.id);
+                    if (r !== undefined)
+                        pushResult(tc.id, r);
+                }
+                const remaining = group.filter(tc => !spawnResults.has(tc.id));
+                if (remaining.length === 0)
+                    continue;
+                const inputs = remaining.map(tc => {
                     try {
                         return JSON.parse(tc.argsStr || '{}');
                     }
@@ -273,64 +428,46 @@ export class Agent {
                 });
                 // Plan mode is read-only. The model normally isn't even offered mutating
                 // tools (see buildParams), but refuse here too as defense-in-depth.
-                if (this.mode === 'plan' && !PLAN_TOOLS.has(group[0].name)) {
+                if (this.mode === 'plan' && !PLAN_TOOLS.has(remaining[0].name)) {
                     if (this.activeTurnStats)
-                        this.activeTurnStats.toolCalls += group.length;
-                    process.stdout.write(`\n${this.indent}${toolLine(group[0].name, formatToolArgs(group[0].name, inputs[0])).trimStart()}\n`);
+                        this.activeTurnStats.toolCalls += remaining.length;
+                    process.stdout.write(`\n${this.indent}${toolLine(remaining[0].name, formatToolArgs(remaining[0].name, inputs[0])).trimStart()}\n`);
                     process.stdout.write(`${this.indent}${toolErrorLine('blocked · plan mode is read-only')}\n`);
-                    for (const tc of group) {
-                        this.conversation.push({
-                            role: 'tool', tool_call_id: tc.id,
-                            content: 'Blocked: plan mode is read-only. Do not attempt changes — propose a plan instead. The user can switch to agent mode to apply it.',
-                        });
+                    for (const tc of remaining) {
+                        pushResult(tc.id, 'Blocked: plan mode is read-only. Do not attempt changes — propose a plan instead. The user can switch to agent mode to apply it.');
                     }
                     continue;
                 }
-                if (group.length === 1) {
+                if (remaining.length === 1) {
                     if (this.activeTurnStats)
                         this.activeTurnStats.toolCalls++;
-                    process.stdout.write(`\n${this.indent}${toolLine(group[0].name, formatToolArgs(group[0].name, inputs[0])).trimStart()}\n`);
-                    const result = await this.handleToolCall(group[0].name, group[0].id, inputs[0], opts);
-                    this.conversation.push({ role: 'tool', tool_call_id: group[0].id, content: result });
+                    process.stdout.write(`\n${this.indent}${toolLine(remaining[0].name, formatToolArgs(remaining[0].name, inputs[0])).trimStart()}\n`);
+                    const result = await this.handleToolCall(remaining[0].name, remaining[0].id, inputs[0], opts);
+                    pushResult(remaining[0].id, result);
                 }
                 else {
                     if (this.activeTurnStats)
-                        this.activeTurnStats.toolCalls += group.length;
-                    const summary = this.formatGroupSummary(group[0].name, inputs);
-                    process.stdout.write(`\n${this.indent}${toolLine(`${group[0].name} ×${group.length}`, summary).trimStart()}\n`);
-                    if (!opts.autoApprove && !this.config.autoApprove && !SAFE_TOOLS.has(group[0].name) && group[0].name !== 'switch_mode') {
-                        const allowed = await this.checkPermission(group[0].name, inputs[0]);
+                        this.activeTurnStats.toolCalls += remaining.length;
+                    const summary = this.formatGroupSummary(remaining[0].name, inputs);
+                    process.stdout.write(`\n${this.indent}${toolLine(`${remaining[0].name} ×${remaining.length}`, summary).trimStart()}\n`);
+                    if (!opts.autoApprove && !this.config.autoApprove && !SAFE_TOOLS.has(remaining[0].name) && remaining[0].name !== 'switch_mode') {
+                        const allowed = await this.checkPermission(remaining[0].name, inputs[0]);
                         if (!allowed) {
-                            for (const tc of group) {
-                                this.conversation.push({
-                                    role: 'tool', tool_call_id: tc.id,
-                                    content: `Tool execution denied by user: ${tc.name}`,
-                                });
+                            for (const tc of remaining) {
+                                pushResult(tc.id, `Tool execution denied by user: ${tc.name}`);
                             }
                             continue;
                         }
                     }
                     const t0 = Date.now();
                     let errors = 0;
-                    // Separate subagents so they can run in parallel; keep other tools sequential
-                    // to avoid races on file mutations.
-                    const spawnIndices = [];
-                    const otherIndices = [];
-                    for (let i = 0; i < group.length; i++) {
-                        if (group[i].name === 'spawn_agent')
-                            spawnIndices.push(i);
-                        else
-                            otherIndices.push(i);
-                    }
+                    const groupSpinner = new InlineSpinner(`${toolPhaseLabel(remaining[0].name)} (${remaining.length} operations)`, t0);
+                    groupSpinner.start();
                     const results = new Map();
-                    if (spawnIndices.length > 0) {
-                        const spawnResults = await Promise.all(spawnIndices.map(i => this.runSubagent(inputs[i], opts)));
-                        spawnIndices.forEach((idx, i) => results.set(idx, spawnResults[i]));
-                    }
-                    for (const i of otherIndices) {
+                    for (let i = 0; i < remaining.length; i++) {
                         if (opts.signal?.aborted)
                             break;
-                        const tc = group[i];
+                        const tc = remaining[i];
                         try {
                             if (tc.name === 'read_file' && isRestrictedPath(String(inputs[i].path ?? ''))) {
                                 const allowed = await this.checkPermission('read_file', inputs[i]);
@@ -339,7 +476,9 @@ export class Agent {
                                     continue;
                                 }
                             }
-                            const result = await executeTool(tc.name, inputs[i]);
+                            const result = tc.name === 'use_skill'
+                                ? await this.handleToolCall(tc.name, tc.id, inputs[i], opts)
+                                : await executeTool(tc.name, inputs[i]);
                             if (result.startsWith('Error'))
                                 errors++;
                             this.recordChangedFile(tc.name, inputs[i], result);
@@ -350,37 +489,102 @@ export class Agent {
                             results.set(i, `Tool error: ${err}`);
                         }
                     }
-                    for (let i = 0; i < group.length; i++) {
+                    groupSpinner.stop();
+                    for (let i = 0; i < remaining.length; i++) {
                         const result = results.get(i);
-                        if (result !== undefined) {
-                            this.conversation.push({ role: 'tool', tool_call_id: group[i].id, content: result });
-                        }
+                        if (result !== undefined)
+                            pushResult(remaining[i].id, result);
                     }
                     const ms = Date.now() - t0;
                     const lineStr = errors === 0
-                        ? toolSuccessLine(ms, `${group.length} operations`)
-                        : toolErrorLine(`${errors} of ${group.length} operations`);
+                        ? toolSuccessLine(ms, `${remaining.length} operations`)
+                        : toolErrorLine(`${errors} of ${remaining.length} operations`);
                     process.stdout.write(`${this.indent}${lineStr}\n`);
                 }
             }
+            // Invariant: balance the assistant message. Any tool_call that didn't get
+            // a result (aborted mid-group, an unexpected skip) is answered with a
+            // synthetic "interrupted" result so the next request is always valid.
+            for (const tc of toolCalls) {
+                if (!answered.has(tc.id))
+                    pushResult(tc.id, INTERRUPTED_TOOL_RESULT);
+            }
+            if (opts.signal?.aborted)
+                break;
+            if (!shouldContinue(toolCalls.length, finishReason, step, maxSteps)) {
+                // Hit the step budget while still wanting tools — stop cleanly and ask
+                // for a final summary (with tools disabled, so it can't dangle).
+                await this.summarizeAndStop(opts, maxSteps);
+                break;
+            }
             process.stdout.write('\n');
         }
     }
+    /**
+     * Final wrap-up when the per-turn step budget is exhausted. One model call with
+     * tools disabled, so it produces a plain summary and can never leave a dangling
+     * tool call. Best-effort: failures here don't throw out of the turn.
+     */
+    async summarizeAndStop(opts, maxSteps) {
+        process.stdout.write(`\n${this.indent}${c.warning('◔')} ${c.muted(`Reached step budget (${maxSteps}) — wrapping up.`)}\n`);
+        this.conversation.push({
+            role: 'user',
+            content: `[system] You have reached the ${maxSteps}-step tool budget for this turn. `
+                + 'Stop calling tools now. Briefly summarize what you accomplished, what remains, '
+                + 'and the exact next step to resume — no tool calls.',
+        });
+        try {
+            if (this.activeTurnStats)
+                this.activeTurnStats.modelCalls++;
+            await this.throttleModelRequest();
+            const params = this.buildParams();
+            const resp = await withRetry(() => this.client.chat.completions.create({
+                ...params,
+                tools: undefined,
+                tool_choice: undefined,
+            }, (opts.signal ? { signal: opts.signal } : undefined)), { signal: opts.signal, label: 'final-summary' });
+            const text = resp.choices[0]?.message?.content ?? '';
+            this.conversation.push({ role: 'assistant', content: text || null });
+            if (text)
+                printResponse(text, this.indent);
+        }
+        catch (err) {
+            if (!opts.signal?.aborted) {
+                process.stdout.write(`${this.indent}${toolErrorLine(extractUpstreamError(err))}\n`);
+            }
+        }
+    }
     // ── Model calls ───────────────────────────────────────────────────────────
     async callModel(opts) {
+        // Count + throttle exactly once per model turn (the non-streaming fallback
+        // below is part of the SAME turn, so it must not double-count or double-wait).
+        if (this.activeTurnStats)
+            this.activeTurnStats.modelCalls++;
+        await this.throttleModelRequest();
+        const state = { emitted: false };
         try {
-            return await this.callModelStreaming(opts);
+            return await this.callModelStreaming(opts, state);
         }
         catch (err) {
             if (opts.signal?.aborted)
                 throw err;
+            // Only fall back to non-streaming if the stream produced nothing yet.
+            // If it already streamed output then failed, replaying would double-print
+            // and double-bill — surface the error instead.
+            if (state.emitted)
+                throw err;
             return await this.callModelNonStreaming(opts);
         }
     }
     buildParams() {
+        // Always work on a copy — never push into the shared TOOL_DEFS array.
         let tools = this.depth >= 1
             ? TOOL_DEFS.filter(t => t.function.name !== 'spawn_agent')
-            : TOOL_DEFS;
+            : [...TOOL_DEFS];
+        // Append first-class MCP tools in agent mode only (we can't prove they're read-only).
+        if (this.mode === 'agent' && this.depth === 0) {
+            tools = tools.concat(getMcpToolDefs());
+        }
         // Always include switch_mode so the agent can request a mode change.
         const switchModeTool = TOOL_DEFS.find(t => t.function.name === 'switch_mode');
         // Plan mode: only offer read-only tools, and steer toward proposing a plan.
@@ -428,19 +632,16 @@ export class Agent {
         }
         requestTimestamps.push(Date.now());
     }
-    async callModelStreaming(opts) {
+    async callModelStreaming(opts, state) {
         const spinner = new InlineSpinner('Working', opts.startedAt);
         spinner.start();
         const requestOpts = opts.signal ? { signal: opts.signal } : undefined;
         let stream;
         try {
-            if (this.activeTurnStats)
-                this.activeTurnStats.modelCalls++;
-            await this.throttleModelRequest();
-            stream = await this.client.chat.completions.create({
+            stream = await withRetry(() => this.client.chat.completions.create({
                 ...this.buildParams(),
                 stream: true,
-            }, requestOpts);
+            }, requestOpts), { signal: opts.signal, label: 'stream' });
         }
         catch (err) {
             spinner.stop();
@@ -470,8 +671,10 @@ export class Agent {
                 if (delta.content) {
                     textContent += delta.content;
                     phase = 'Generating';
+                    state.emitted = true;
                 }
                 if (delta.tool_calls) {
+                    state.emitted = true;
                     for (const tc of delta.tool_calls) {
                         const idx = tc.index;
                         if (!toolCallsMap.has(idx)) {
@@ -519,7 +722,7 @@ export class Agent {
         if (textContent) {
             printResponse(textContent, this.indent);
         }
-        const toolCalls = [...toolCallsMap.values()];
+        const toolCalls = normalizeToolCalls([...toolCallsMap.values()]);
         const assistantMsg = {
             role: 'assistant',
             content: textContent || null,
@@ -539,12 +742,9 @@ export class Agent {
         const requestOpts = opts.signal ? { signal: opts.signal } : undefined;
         let resp;
         try {
-            if (this.activeTurnStats)
-                this.activeTurnStats.modelCalls++;
-            await this.throttleModelRequest();
-            resp = await this.client.chat.completions.create({
+            resp = await withRetry(() => this.client.chat.completions.create({
                 ...this.buildParams(),
-            }, requestOpts);
+            }, requestOpts), { signal: opts.signal, label: 'non-stream' });
         }
         catch (err) {
             spinner.stop();
@@ -560,17 +760,19 @@ export class Agent {
         if (textContent) {
             printResponse(textContent, this.indent);
         }
-        const toolCalls = (msg.tool_calls ?? []).map(tc => ({
+        const toolCalls = normalizeToolCalls((msg.tool_calls ?? []).map(tc => ({
             id: tc.id, name: tc.function.name, argsStr: tc.function.arguments,
-        }));
+        })));
         const assistantMsg = {
             role: 'assistant',
             content: textContent || null,
+            // Derive from the normalized list so the message and the dispatch list
+            // stay in lockstep (no dangling/un-dispatchable calls).
             ...(toolCalls.length ? {
-                tool_calls: (msg.tool_calls ?? []).map(tc => ({
+                tool_calls: toolCalls.map(tc => ({
                     id: tc.id,
                     type: 'function',
-                    function: tc.function,
+                    function: { name: tc.name, arguments: tc.argsStr },
                 })),
             } : {}),
         };
@@ -581,6 +783,9 @@ export class Agent {
         if (name === 'switch_mode') {
             return this.handleSwitchMode(input);
         }
+        if (name === 'use_skill') {
+            return this.handleUseSkill(input);
+        }
         if (name === 'spawn_agent') {
             return this.runSubagent(input, opts);
         }
@@ -598,7 +803,7 @@ export class Agent {
                     return `Tool execution denied by user: read_file ${path}`;
             }
         }
-        if (!opts.autoApprove && !this.config.autoApprove && !SAFE_TOOLS.has(name)) {
+        if (!opts.autoApprove && !this.config.autoApprove && !SAFE_TOOLS.has(name) && !this.sessionAllowList.has(name)) {
             // Self-kill safeguard: a bash command that kills/frees processes by ikie's
             // own host port (e.g. `kill $(lsof -ti:3000)`) can match ikie's outbound
             // socket and SIGTERM the session. Force a confirmation even if bash is
@@ -612,8 +817,17 @@ export class Agent {
                 return `Tool execution denied by user: ${name}`;
         }
         const t0 = Date.now();
+        const spinner = new InlineSpinner(toolPhaseLabel(name), t0);
+        // For bash commands with streaming, show spinner briefly then let output flow
+        const isStreamingBash = name === 'bash' && /\b(build|compile|test|deploy|install)\b/i.test(String(input.command ?? ''));
+        if (!isStreamingBash) {
+            spinner.start();
+        }
         try {
             const result = await executeTool(name, input);
+            if (!isStreamingBash) {
+                spinner.stop();
+            }
             this.recordChangedFile(name, input, result);
             const ms = Date.now() - t0;
             let block;
@@ -626,15 +840,31 @@ export class Agent {
             else {
                 block = toolOutputBlock(result, ms, this.indent);
             }
-            process.stdout.write(`${block}\n`);
+            if (block)
+                process.stdout.write(`${block}\n`);
             return result;
         }
         catch (err) {
+            if (!isStreamingBash) {
+                spinner.stop();
+            }
             const msg = err instanceof Error ? err.message : String(err);
             process.stdout.write(`${this.indent}${toolErrorLine(msg)}\n`);
             return msg;
         }
     }
+    async handleUseSkill(input) {
+        const name = (input.name ?? '').trim();
+        if (!name)
+            return 'Error: use_skill requires a name.';
+        const skill = getSkill(name);
+        if (!skill)
+            return `Error: no skill named "${name}".`;
+        for (const tool of mapAllowedTools(skill.allowedTools)) {
+            this.sessionAllowList.add(tool);
+        }
+        return renderSkill(skill);
+    }
     async handleSwitchMode(input) {
         if (this.depth > 0) {
             return 'Error: subagents cannot switch mode. Return your findings and let the main agent decide.';
@@ -755,10 +985,44 @@ export class Agent {
             process.stdout.write(`${this.indent}${c.error('✗')} ${c.muted('subagent failed')}\n`);
             return `Subagent error: ${err instanceof Error ? err.message : String(err)}`;
         }
-        const result = sub.getLastAssistantText();
+        let result = sub.getLastAssistantText();
+        // The subagent's reply IS the only thing returned to the parent. If it ended
+        // without a textual summary (e.g. stopped right after a tool call), ask once
+        // more for a self-contained summary so we never hand back an empty result.
+        if (!result && !opts.signal?.aborted) {
+            result = await sub.requestFinalSummary(opts.signal);
+        }
         process.stdout.write(`${this.indent}${c.success('✓')} ${c.muted('subagent done')}\n\n`);
         return result || '(subagent completed but produced no summary)';
     }
+    /**
+     * Best-effort: one tool-less model call asking for a concise, self-contained
+     * summary of the work so far. Used to guarantee a non-empty subagent result.
+     */
+    async requestFinalSummary(signal) {
+        this.conversation.push({
+            role: 'user',
+            content: 'Summarize what you did and any key results (paths changed, findings, answers) '
+                + 'in a few sentences. Do not call any tools.',
+        });
+        try {
+            if (this.activeTurnStats)
+                this.activeTurnStats.modelCalls++;
+            await this.throttleModelRequest();
+            const params = this.buildParams();
+            const resp = await withRetry(() => this.client.chat.completions.create({
+                ...params,
+                tools: undefined,
+                tool_choice: undefined,
+            }, (signal ? { signal } : undefined)), { signal, label: 'sub-summary' });
+            const text = resp.choices[0]?.message?.content ?? '';
+            this.conversation.push({ role: 'assistant', content: text || null });
+            return text;
+        }
+        catch {
+            return '';
+        }
+    }
     getLastAssistantText() {
         for (let i = this.conversation.length - 1; i >= 0; i--) {
             const m = this.conversation[i];
@@ -782,25 +1046,12 @@ export class Agent {
         const t0 = Date.now();
         const preview = formatToolArgs(toolName, input);
         const { verb, tint } = toolMeta(toolName);
-        const makePrompt = (elapsed) => `\n  ${tint('●')} ${c.white.bold('permission')} ${c.muted(`(${elapsed}s)`)} ${c.muted('·')} ${c.white(verb)} ${c.dim(preview)}\n` +
-            `  ${c.muted('⎿')} ` +
-            `${c.success.bold('y')} ${c.muted('allow')}   ` +
-            `${c.error.bold('n')} ${c.muted('deny')}   ` +
-            `${c.info.bold('a')} ${c.muted('always')}   ` +
-            `${c.muted.bold('!')} ${c.muted('never')}\n` +
-            `  ${c.muted(CH.arrow)} `;
-        process.stdout.write(makePrompt('0.0'));
-        const timerUpdate = () => {
-            const elapsed = ((Date.now() - t0) / 1000).toFixed(1);
-            process.stdout.write(`\x1b[3A\x1b[0J${makePrompt(elapsed)}`);
-        };
-        const timerInterval = setInterval(timerUpdate, 100);
-        const cleanup = () => {
-            clearInterval(timerInterval);
-        };
+        const line = `\n  ${tint('●')} ${c.white.bold('permission')} ${c.muted(`(${((Date.now() - t0) / 1000).toFixed(1)}s)`)} ${c.muted('·')} ${c.white(verb)} ${c.dim(preview)}\n`;
+        process.stdout.write(line);
+        const optionsStr = `${c.success(' y allow ')}  ${c.error(' n deny ')}  ${c.info(' a always ')}  ${c.muted(' ! never ')}`;
+        process.stdout.write(`  ${optionsStr}\n  ${c.muted(CH.arrow)} `);
         return new Promise((resolve) => {
             if (!process.stdin.isTTY) {
-                cleanup();
                 process.stdout.write(chalk.dim('(non-interactive, denying)\n'));
                 resolve(false);
                 return;
@@ -815,34 +1066,35 @@ export class Agent {
                 process.stdin.resume();
             }
             const onData = (data) => {
-                cleanup();
+                const text = data.toString();
+                const key = text.toLowerCase();
                 process.stdin.removeListener('data', onData);
-                // Restore raw mode to what it was (keeps REPL's ESC handler working)
-                if (process.stdin.isTTY) {
+                if (process.stdin.isTTY)
                     process.stdin.setRawMode(wasRaw);
-                }
                 restoreStdinListeners(savedDataListeners, savedKeypressListeners);
-                // Only pause if nobody else was listening (no REPL ESC handler)
-                if (!savedDataListeners.length) {
+                if (!savedDataListeners.length)
                     process.stdin.pause();
-                }
-                const key = data.toString().toLowerCase();
-                if (key === 'y' || key === '\r' || key === '\n') {
-                    process.stdout.write(chalk.green('y\n'));
+                let label;
+                if (key === 'y') {
+                    label = c.success('allow');
+                    process.stdout.write(`${label}\n`);
                     resolve(true);
                 }
                 else if (key === 'a') {
-                    process.stdout.write(chalk.blue('a (always)\n'));
+                    label = c.info('always');
                     this.sessionAllowList.add(toolName);
+                    process.stdout.write(`${label}\n`);
                     resolve(true);
                 }
                 else if (key === '!') {
-                    process.stdout.write(chalk.dim('! (always deny)\n'));
+                    label = c.muted('never');
                     this.sessionDenyList.add(toolName);
+                    process.stdout.write(`${label}\n`);
                     resolve(false);
                 }
                 else {
-                    process.stdout.write(chalk.red('n\n'));
+                    label = c.error('deny');
+                    process.stdout.write(`${label}\n`);
                     resolve(false);
                 }
             };
@@ -1081,22 +1333,22 @@ only the non-obvious. Use \`ask_user\` only when truly blocked on a decision you
   unsure. Don't ask for confirmation on safe operations.
 
 ## MCP (Model Context Protocol) System
-- \`mcp_list\`: List all installed MCP servers and their available tools. MCPs extend ikie
-  with specialized capabilities like GitHub API, database access, browser automation, etc.
-- \`mcp_install\`: Install a new MCP server from npm, git URL, or local path.
-- \`mcp_start\`: Start an MCP server to make its tools available for use.
-- \`mcp_stop\`: Stop a running MCP server.
-- \`mcp_call\`: Call a tool from a running MCP. Use \`mcp_list\` first to see available tools.
-- \`mcp_uninstall\`: Remove an installed MCP (built-in MCPs cannot be uninstalled).
-- \`mcp_add\`: Add an MCP by specifying the full command directly (Claude/Cline-style). Use when the MCP runs via npx, a script, or any custom command. Example: \`mcp_add(name="magic", commandArgs="npx -y @21st-dev/magic@latest", env={API_KEY: "..."})\`. After adding, you must run \`mcp_start\` to activate it.
+MCP servers extend ikie with specialized capabilities like GitHub API, database access,
+browser automation, etc. When a server is configured, each of its tools appears as a
+first-class tool named \`mcp__<server>__<tool>\`. Call those tools directly — there is no
+meta-tool dance.
+
+- \`mcp_list\`: List all configured MCP servers and their status/tools.
+- \`mcp_add\`: Add an MCP server by specifying the command directly (Claude/Cline-style).
+  Example: \`mcp_add(name="magic", commandArgs="npx -y @21st-dev/magic@latest", env={API_KEY: "..."})\`.
 
-**Recognizing MCP config patterns:** When the user says things like "install this MCP", "claude mcp add", "add this MCP", or pastes a Claude-style MCP config, parse it and use \`mcp_add\`. The format is: \`<any-prefix> mcp add <name> [--scope user] [--env KEY=VALUE ...] -- <command> [args...]\`. Everything after \`--\` is the full command string. Translate this to \`mcp_add\` — do NOT try to run it as a bash command.
+**Recognizing MCP config patterns:** When the user says things like "install this MCP",
+"claude mcp add", "add this MCP", or pastes a Claude-style MCP config, parse it and use
+\`mcp_add\`. The format is: \`<any-prefix> mcp add [--scope user|project|local] [--env KEY=VALUE]... [--header "H: v"]... [--transport stdio|http|sse] <name> [url | -- <command> args...]\`. Everything after \`--\` is the full command string. Translate this to \`mcp_add\` — do NOT try to run it as a bash command.
 
-**Built-in MCPs:**
-- **filesystem**: Enhanced file operations (read multiple files, directory trees)
-- **github**: GitHub API operations (search repos, manage issues, read files from repos)
-- **database**: Database operations for SQLite and PostgreSQL
-- **puppeteer**: Browser automation and web scraping
+You can also configure servers by creating a \`.mcp.json\` file in the project root (or
+\`.mcp.local.json\` for machine-local overrides, or \`~/.ikie/mcp.json\` for global ones).
+Each entry has shape \`{ "type": "stdio|http|sse", "command": "...", "args": [...], "env": {...}, "url": "...", "headers": {...}, "enabled": true, "autoStart": true }\`.
 
 **When to use MCPs:** When you need specialized functionality beyond basic tools. For example:
 - Use GitHub MCP to interact with repositories, issues, pull requests