codemini-cli 0.2.2 → 0.2.3

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "codemini-cli",
-  "version": "0.2.2",
+  "version": "0.2.3",
   "description": "Coding CLI optimized for small-model workflows and Windows PowerShell",
   "keywords": [
     "cli",

package/skills/superpowers-lite/SKILL.md

@@ -20,18 +20,21 @@ Routing:
 
 2. If the goal is clear but there are multiple reasonable implementation paths:
 - use `brainstorm`
-- give 2-3 short options
-- do not choose for the user unless the user explicitly asks for a recommendation
+- ask exactly one clarifying question first
+- do not give options, recommendations, or a tentative solution in the same response
+- stop after the question and wait for the user's answer before continuing
 
 3. If the request is still missing a key constraint or success condition:
 - ask exactly one clarifying question
 - do not give options yet
 - do not write code yet
+- stop after the question and wait for the user's answer
 
 4. If the request is greenfield and underspecified, such as "build a page", "make a site", "generate an app", or similar:
 - treat it as missing key constraints by default
 - ask one high-value question before coding
 - do not assume features, storage model, or scope unless the user already gave them
+- stop after the question and wait for the user's answer
 
 Tool order:
 - prefer `grep` first for content search and candidate discovery

package/src/cli.js

@@ -4,7 +4,7 @@ import { handleConfig } from './commands/config.js';
 import { handleDoctor } from './commands/doctor.js';
 import { handleSkill } from './commands/skill.js';
 
-const VERSION = '0.2.2';
+const VERSION = '0.2.3';
 
 function printHelp() {
   console.log(`codemini ${VERSION}

package/src/commands/run.js

@@ -35,7 +35,7 @@ export async function handleRun(args) {
   }
 
   const config = await loadConfig();
-  const { definitions, handlers } = getBuiltinTools({
+  const { definitions, handlers, formatters, deferredDefinitions } = getBuiltinTools({
     workspaceRoot: process.cwd(),
     config
   });
@@ -47,6 +47,8 @@ export async function handleRun(args) {
     model: parsed.model || config.model.name,
     toolDefinitions: definitions,
     toolHandlers: handlers,
+    toolFormatters: formatters,
+    deferredDefinitions,
     maxSteps: parsed.maxSteps,
     requestCompletion: async ({ messages, tools, model }) =>
       createChatCompletion({

package/src/core/agent-loop.js

@@ -1,3 +1,7 @@
+import os from 'node:os';
+import path from 'node:path';
+import fs from 'node:fs/promises';
+
 function safeJsonParse(raw) {
   if (!raw || typeof raw !== 'string') return {};
   try {
@@ -13,7 +17,198 @@ function clipToolResult(result, maxChars = 12000) {
   return `${raw.slice(0, maxChars)}\n... [tool result truncated ${raw.length - maxChars} chars]`;
 }
 
-function summarizeToolResult(result) {
+function compactToolResult(result, toolName, args, maxChars = 12000) {
+  if (result === null || result === undefined) return 'no output';
+  if (typeof result === 'string') {
+    if (result.length <= maxChars) return result;
+    return `${result.slice(0, maxChars)}\n... [tool result truncated ${result.length - maxChars} chars, original: ${result.length}]`;
+  }
+  if (typeof result !== 'object') return String(result);
+
+  const obj = result;
+  const rawLen = JSON.stringify(obj).length;
+
+  // Read file result: { path, phase, content, ... }
+  if ('path' in obj && 'phase' in obj && obj.phase === 'content') {
+    const header = `[File: ${obj.path}, lines ${obj.start_line || 1}-${obj.end_line || '?'}${obj.total_lines ? ` of ${obj.total_lines}` : ''}${obj.truncated ? ', truncated' : ''}]`;
+    const content = obj.content || obj.text || '';
+    if (typeof content !== 'string' || content.length <= maxChars) {
+      const body = typeof content === 'string' ? content : JSON.stringify(content);
+      return body.length <= maxChars ? `${header}\n${body}` : `${header}\n${body.slice(0, maxChars)}\n... [omitted ${body.length - maxChars} chars, original: ${rawLen}]`;
+    }
+    // Keep head + tail
+    const headLen = Math.floor(maxChars * 0.6);
+    const tailLen = Math.floor(maxChars * 0.3);
+    return `${header}\n${content.slice(0, headLen)}\n... [omitted ${content.length - headLen - tailLen} chars] ...\n${content.slice(-tailLen)}\n[original: ${rawLen} chars]`;
+  }
+
+  // File edit/write result: { path, action, ... }
+  if ('path' in obj && 'action' in obj) {
+    const summary = summarizeToolResult(obj);
+    const diff = obj.diff || obj.patch || obj.content_preview || '';
+    if (diff && typeof diff === 'string' && diff.length <= 800) {
+      return `${summary}\n${diff}`;
+    }
+    if (diff) {
+      return `${summary}\n${diff.slice(0, 800)}\n... [diff truncated, original: ${rawLen}]`;
+    }
+    return `${summary} [original: ${rawLen} chars]`;
+  }
+
+  // Shell command result: { stdout, stderr, code, ... }
+  if ('stdout' in obj || 'stderr' in obj || 'code' in obj) {
+    const command = String(obj.command || '').slice(0, 200);
+    const stdout = String(obj.stdout || '').slice(0, 500);
+    const stderr = String(obj.stderr || '').slice(0, 500);
+    const code = obj.code ?? 0;
+    const parts = [`[exit: ${code}]`];
+    if (command) parts.push(`command: ${command}`);
+    if (stdout) parts.push(`stdout:\n${stdout}`);
+    if (stderr) parts.push(`stderr:\n${stderr}`);
+    if (rawLen > 2000) parts.push(`[original: ${rawLen} chars]`);
+    return parts.join('\n');
+  }
+
+  // Array results (file lists, grep results, etc.)
+  if (Array.isArray(obj)) {
+    const maxItems = 50;
+    if (obj.length <= maxItems) {
+      const serialized = JSON.stringify(obj);
+      return serialized.length <= maxChars ? serialized : clipToolResult(obj, maxChars);
+    }
+    const kept = obj.slice(0, maxItems);
+    const items = typeof kept[0] === 'string'
+      ? kept.join('\n')
+      : kept.map((item) => JSON.stringify(item)).join('\n');
+    return `${items}\n... and ${obj.length - maxItems} more items [total: ${obj.length}, original: ${rawLen} chars]`;
+  }
+
+  // Patch result: { files: [...] }
+  if ('files' in obj && Array.isArray(obj.files)) {
+    return `patched ${obj.files.length} file(s): ${obj.files.slice(0, 10).join(', ')}${obj.files.length > 10 ? ` ... and ${obj.files.length - 10} more` : ''} [original: ${rawLen}]`;
+  }
+
+  // Task results
+  if ('created' in obj && Array.isArray(obj.created)) {
+    return `created ${obj.created.length} task(s)`;
+  }
+  if ('tasks' in obj && Array.isArray(obj.tasks)) {
+    return `${obj.tasks.length} task(s)`;
+  }
+
+  // Fallback: clip with reduced limit
+  return clipToolResult(obj, Math.min(maxChars, 4000));
+}
+
+// ─── P0: Large result disk store ─────────────────────────────────────
+
+const TOOL_RESULT_DISK_THRESHOLD = 6000;
+const PREVIEW_SIZE_BYTES = 2000;
+const TOOL_RESULTS_SUBDIR = 'tool-results';
+
+let currentResultDir = null;
+let resultDirReady = false;
+const storedResults = new Map(); // callId -> { filePath, summary }
+const readCache = new Map();     // "path:startLine:endLine:mtimeMs" -> true
+
+function generatePreview(content) {
+  if (content.length <= PREVIEW_SIZE_BYTES) {
+    return { preview: content, hasMore: false };
+  }
+  const truncated = content.slice(0, PREVIEW_SIZE_BYTES);
+  const lastNewline = truncated.lastIndexOf('\n');
+  const cutPoint = lastNewline > PREVIEW_SIZE_BYTES * 0.5 ? lastNewline : PREVIEW_SIZE_BYTES;
+  return { preview: content.slice(0, cutPoint), hasMore: true };
+}
+
+function formatFileSize(chars) {
+  if (chars < 1024) return `${chars} B`;
+  return `${(chars / 1024).toFixed(1)} KB`;
+}
+
+export function setResultDir(dir) {
+  currentResultDir = dir ? path.join(dir, TOOL_RESULTS_SUBDIR) : null;
+  resultDirReady = false;
+}
+
+async function ensureResultDir() {
+  if (!currentResultDir) return false;
+  if (!resultDirReady) {
+    await fs.mkdir(currentResultDir, { recursive: true });
+    resultDirReady = true;
+  }
+  return true;
+}
+
+async function storeResultIfNeeded(callId, formattedContent, rawResult) {
+  if (formattedContent.length <= TOOL_RESULT_DISK_THRESHOLD) {
+    return formattedContent;
+  }
+  try {
+    const ready = await ensureResultDir();
+    const dir = ready ? currentResultDir : path.join(os.tmpdir(), 'codemini-results');
+    if (!resultDirReady && dir === currentResultDir) {
+      await fs.mkdir(dir, { recursive: true });
+    } else if (!resultDirReady) {
+      await fs.mkdir(dir, { recursive: true });
+    }
+    const filePath = path.join(dir, `${callId}.txt`);
+    const payload = typeof rawResult === 'string' ? rawResult : JSON.stringify(rawResult, null, 2);
+    await fs.writeFile(filePath, payload, 'utf-8');
+    const summary = summarizeToolResult(rawResult);
+    const { preview, hasMore } = generatePreview(payload);
+    storedResults.set(callId, { filePath, summary });
+
+    return `<persisted-output>
+Output too large (${formatFileSize(payload.length)}). Full output saved to: ${filePath}
+
+Preview (first ${formatFileSize(PREVIEW_SIZE_BYTES)}):
+${preview}${hasMore ? '\n...' : ''}
+
+Summary: ${summary}
+</persisted-output>`;
+  } catch {
+    return formattedContent;
+  }
+}
+
+export function clearResultStore() {
+  const files = [];
+  for (const [, val] of storedResults) {
+    files.push(val.filePath);
+  }
+  storedResults.clear();
+  readCache.clear();
+  return Promise.allSettled(files.map((f) => fs.unlink(f).catch(() => {})));
+}
+
+// ─── Read deduplication ─────────────────────────────────────────────
+
+export function checkReadDedup(filePath, startLine, endLine, mtimeMs) {
+  const key = `${filePath}:${startLine || 0}:${endLine || 0}:${mtimeMs}`;
+  if (readCache.has(key)) {
+    return true;
+  }
+  readCache.set(key, true);
+  // Keep cache bounded
+  if (readCache.size > 100) {
+    const firstKey = readCache.keys().next().value;
+    readCache.delete(firstKey);
+  }
+  return false;
+}
+
+// ─── P1a: Read-only tool classification ──────────────────────────────
+
+const READ_ONLY_TOOLS = new Set([
+  'read', 'grep', 'glob', 'list',
+  'ast_query', 'read_ast_node', 'generate_diff',
+  'list_services', 'get_service_status', 'get_service_logs'
+]);
+
+// ─── Exported helpers ────────────────────────────────────────────────
+
+export function summarizeToolResult(result) {
   if (result === null || result === undefined) return 'no output';
   if (typeof result === 'string') {
     const oneLine = result.replace(/\s+/g, ' ').trim();
@@ -106,7 +301,7 @@ function summarizeToolResult(result) {
   return String(result);
 }
 
-function trimInline(value, maxLen = 72) {
+export function trimInline(value, maxLen = 72) {
   const s = String(value || '').replace(/\s+/g, ' ').trim();
   if (!s) return '';
   if (s.length <= maxLen) return s;
@@ -171,6 +366,18 @@ function formatToolDisplayName(name, args) {
   return name;
 }
 
+// ─── Format a single tool result using per-tool formatter or fallback ──
+
+function formatToolResult(toolResult, toolName, args, toolFormatters, toolResultMaxChars) {
+  if (toolFormatters && typeof toolFormatters[toolName] === 'function') {
+    const formatted = toolFormatters[toolName](toolResult, args);
+    if (typeof formatted === 'string') return formatted;
+  }
+  return compactToolResult(toolResult, toolName, args, toolResultMaxChars);
+}
+
+// ─── Main agent loop ────────────────────────────────────────────────
+
 export async function runAgentLoop({
   systemPrompt,
   userPrompt,
@@ -184,7 +391,9 @@ export async function runAgentLoop({
   executionMode = 'auto',
   alwaysAllowTools = [],
   requestToolApproval,
-  toolResultMaxChars = 12000
+  toolResultMaxChars = 12000,
+  toolFormatters = {},
+  deferredDefinitions = {}
 }) {
   const messages = [];
   if (systemPrompt) {
@@ -201,12 +410,15 @@ export async function runAgentLoop({
   let lastAssistantText = '';
   const alwaysAllowSet = new Set((Array.isArray(alwaysAllowTools) ? alwaysAllowTools : []).map((t) => String(t)));
 
+  // Mutable tool list — grows as tool_search loads deferred tools
+  const activeTools = [...toolDefinitions];
+
   for (let step = 0; step < maxSteps; step += 1) {
     if (onEvent) onEvent({ type: 'step:start', step: step + 1 });
     const completion = await requestCompletion({
       model,
       messages,
-      tools: toolDefinitions
+      tools: activeTools
     });
 
     const toolCalls = Array.isArray(completion.toolCalls) ? completion.toolCalls : [];
@@ -242,11 +454,19 @@ export async function runAgentLoop({
       return { text: finalText.trim(), messages, steps: step + 1 };
     }
 
-    for (const call of toolCalls) {
+    // ─── P1a: Partition into read-only (parallel) and write (serial) ──
+
+    const callsWithMeta = toolCalls.map((call) => {
       const args = safeJsonParse(call.arguments);
       const toolName = normalizeToolCallName(call.name);
       const displayName = formatToolDisplayName(toolName, args);
-      const startedAt = Date.now();
+      const isReadOnly = READ_ONLY_TOOLS.has(toolName);
+      return { call, args, toolName, displayName, isReadOnly };
+    });
+
+    // Approval checks first — must be done synchronously before any execution
+    const approvalResults = new Map();
+    for (const { call, toolName, displayName, args } of callsWithMeta) {
       let approved = true;
       if (executionMode === 'normal' && !alwaysAllowSet.has(toolName)) {
         approved = false;
@@ -260,26 +480,23 @@ export async function runAgentLoop({
           approved = Boolean(decision?.approved);
         }
       }
+      approvalResults.set(call.id, approved);
+    }
+
+    // Collect results keyed by call.id, then write to messages in original order
+    const resultEntries = new Map(); // call.id -> { content, error? }
+
+    // Helper to execute a single tool call
+    async function executeOne({ call, args, toolName, displayName, isReadOnly }) {
+      const startedAt = Date.now();
 
-      if (!approved) {
+      if (!approvalResults.get(call.id)) {
         if (onEvent) onEvent({ type: 'tool:blocked', name: displayName, id: call.id, arguments: args });
-        const blockedMessage = {
-          role: 'tool',
-          tool_call_id: call.id,
-          content: JSON.stringify({ blocked: true, reason: 'Tool call requires approval in normal mode' })
+        return {
+          callId: call.id,
+          content: JSON.stringify({ blocked: true, reason: 'Tool call requires approval in normal mode' }),
+          blocked: true
         };
-        messages.push(blockedMessage);
-        if (onEvent) {
-          onEvent({
-            type: 'tool:result',
-            name: displayName,
-            id: call.id,
-            arguments: args,
-            content: blockedMessage.content,
-            blocked: true
-          });
-        }
-        continue;
       }
 
       if (onEvent) onEvent({ type: 'tool:start', name: displayName, id: call.id, arguments: args });
@@ -287,6 +504,7 @@ export async function runAgentLoop({
       if (!handler) {
         throw new Error(`Unknown tool: ${call.name}`);
       }
+
       let toolResult;
       try {
         toolResult = await handler(args);
@@ -294,58 +512,81 @@ export async function runAgentLoop({
         const durationMs = Date.now() - startedAt;
         const message = error instanceof Error ? error.message : String(error);
         if (onEvent) {
-          onEvent({
-            type: 'tool:error',
-            name: displayName,
-            id: call.id,
-            arguments: args,
-            durationMs,
-            summary: trimInline(message, 120)
-          });
+          onEvent({ type: 'tool:error', name: displayName, id: call.id, arguments: args, durationMs, summary: trimInline(message, 120) });
         }
-        const toolMessage = {
-          role: 'tool',
-          tool_call_id: call.id,
-          content: clipToolResult({ error: message }, toolResultMaxChars)
+        return {
+          callId: call.id,
+          content: clipToolResult({ error: message }, toolResultMaxChars),
+          error: true
         };
-        messages.push(toolMessage);
+      }
+
+      const durationMs = Date.now() - startedAt;
+      if (onEvent) {
+        onEvent({ type: 'tool:end', name: displayName, id: call.id, arguments: args, durationMs, summary: summarizeToolResult(toolResult) });
+      }
+
+      // P1b: Use per-tool formatter if available, else fallback
+      let formatted = formatToolResult(toolResult, toolName, args, toolFormatters, toolResultMaxChars);
+
+      // P2: If tool_search loaded deferred tools, inject their schemas into activeTools
+      if (toolName === 'tool_search' && toolResult && Array.isArray(toolResult.schemas)) {
+        for (const schema of toolResult.schemas) {
+          const name = schema?.function?.name;
+          if (name && !activeTools.some((t) => t?.function?.name === name)) {
+            activeTools.push(schema);
+          }
+        }
+      }
+
+      // P0: Persist to disk if still large
+      formatted = await storeResultIfNeeded(call.id, formatted, toolResult);
+
+      return { callId: call.id, content: formatted };
+    }
+
+    // Separate read-only and write calls, preserving order
+    const readOnlyCalls = callsWithMeta.filter((c) => c.isReadOnly && approvalResults.get(c.call.id));
+    const writeCalls = callsWithMeta.filter((c) => !c.isReadOnly || !approvalResults.get(c.call.id));
+
+    // Execute read-only calls in parallel
+    if (readOnlyCalls.length > 0) {
+      const readOnlyResults = await Promise.all(readOnlyCalls.map((c) => executeOne(c)));
+      for (const r of readOnlyResults) {
+        resultEntries.set(r.callId, r);
+      }
+    }
+
+    // Execute write calls serially
+    for (const c of writeCalls) {
+      const r = await executeOne(c);
+      resultEntries.set(r.callId, r);
+    }
+
+    // Write results to messages in original tool call order
+    for (const { call, displayName, args } of callsWithMeta) {
+      const entry = resultEntries.get(call.id);
+      if (!entry) continue;
+
+      if (entry.blocked) {
+        messages.push({ role: 'tool', tool_call_id: call.id, content: entry.content });
         if (onEvent) {
-          onEvent({
-            type: 'tool:result',
-            name: displayName,
-            id: call.id,
-            arguments: args,
-            content: toolMessage.content,
-            error: true
-          });
+          onEvent({ type: 'tool:result', name: displayName, id: call.id, arguments: args, content: entry.content, blocked: true });
         }
         continue;
       }
-      const durationMs = Date.now() - startedAt;
-      if (onEvent) {
-        onEvent({
-          type: 'tool:end',
-          name: displayName,
-          id: call.id,
-          arguments: args,
-          durationMs,
-          summary: summarizeToolResult(toolResult)
-        });
+
+      if (entry.error) {
+        messages.push({ role: 'tool', tool_call_id: call.id, content: entry.content });
+        if (onEvent) {
+          onEvent({ type: 'tool:result', name: displayName, id: call.id, arguments: args, content: entry.content, error: true });
+        }
+        continue;
       }
-      const toolMessage = {
-        role: 'tool',
-        tool_call_id: call.id,
-        content: clipToolResult(toolResult, toolResultMaxChars)
-      };
-      messages.push(toolMessage);
+
+      messages.push({ role: 'tool', tool_call_id: call.id, content: entry.content });
       if (onEvent) {
-        onEvent({
-          type: 'tool:result',
-          name: displayName,
-          id: call.id,
-          arguments: args,
-          content: toolMessage.content
-        });
+        onEvent({ type: 'tool:result', name: displayName, id: call.id, arguments: args, content: entry.content });
       }
     }
   }

package/src/core/chat-runtime.js

@@ -1,6 +1,6 @@
 import { parseInput } from './input-parser.js';
 import { loadCommandsAndSkills, renderCommandPrompt } from './command-loader.js';
-import { runAgentLoop } from './agent-loop.js';
+import { runAgentLoop, setResultDir, clearResultStore } from './agent-loop.js';
 import fs from 'node:fs/promises';
 import path from 'node:path';
 import {
@@ -28,7 +28,7 @@ import {
 } from './context-compact.js';
 import { buildSystemPromptWithReplyLanguage } from './reply-language.js';
 import { buildSystemPromptWithSoul } from './soul.js';
-import { getProjectPlansDir, getProjectSpecsDir, getProjectWorkspaceDir } from './paths.js';
+import { getProjectPlansDir, getProjectSpecsDir, getProjectWorkspaceDir, getSessionsDir } from './paths.js';
 import { buildProjectContextSnippet, initializeProjectIndex } from './project-index.js';
 
 function toOpenAIMessages(sessionMessages) {
@@ -1314,7 +1314,7 @@ async function askModel({
     ? `${systemPrompt}\n\n${projectContextSnippet}\n\nUse this project context as lightweight guidance. Prefer tools for fresh verification before assuming details.`
     : systemPrompt;
 
-  const { definitions, handlers } = getBuiltinTools({
+  const { definitions, handlers, formatters, deferredDefinitions } = getBuiltinTools({
     workspaceRoot: process.cwd(),
     config,
     sessionId: session.id,
@@ -1376,6 +1376,8 @@ async function askModel({
     alwaysAllowTools:
       alwaysAllowTools || config.execution?.always_allow_tools || ['run', 'read', 'write'],
     toolResultMaxChars: config.context?.tool_result_max_chars || 12000,
+    toolFormatters: formatters,
+    deferredDefinitions,
     requestCompletion: async ({ messages, tools, model: selectedModel }) => {
       if (onAgentEvent) onAgentEvent({ type: 'assistant:start' });
       return createChatCompletionStream({
@@ -1727,6 +1729,10 @@ export async function createChatRuntime({
   const baseSystemPrompt = systemPrompt;
   let executionMode = config.execution?.mode || 'auto';
   const commands = await loadCommandsAndSkills();
+
+  // Set up tool result store under session directory
+  const sessionResultsDir = path.join(getSessionsDir(), String(currentSession.id));
+  setResultDir(sessionResultsDir);
   const compactState = {
     backupMessages: null,
     autoEnabled: true,
@@ -2492,6 +2498,7 @@ export async function createChatRuntime({
           if (!targetId) return { type: 'system', text: 'Usage: /history resume <session_id>' };
           const loaded = await loadSession(targetId);
           currentSession = loaded;
+          setResultDir(path.join(getSessionsDir(), String(targetId)));
           if (!historyIdCache.includes(targetId)) historyIdCache.unshift(targetId);
           historySessionCache = [
             { id: targetId, messageCount: Array.isArray(loaded.messages) ? loaded.messages.length : 0 },

package/src/core/context-compact.js

@@ -1,3 +1,5 @@
+import { summarizeToolResult, trimInline } from './agent-loop.js';
+
 function textFromContent(content) {
   if (typeof content === 'string') return content;
   if (Array.isArray(content)) {
@@ -30,11 +32,39 @@ function modeToKeepRecent(mode) {
 
 function buildLocalSummary(messages) {
   const lines = [];
-  const limit = 12;
+  const limit = 16;
   for (const msg of messages.slice(-limit)) {
+    if (msg.role === 'tool') {
+      // Try to parse tool result as JSON for semantic summary
+      const text = textFromContent(msg.content);
+      let parsed;
+      try { parsed = JSON.parse(text); } catch { parsed = null; }
+      if (parsed && typeof parsed === 'object') {
+        const summary = summarizeToolResult(parsed);
+        lines.push(`- tool_result: ${summary}`);
+      } else {
+        const clipped = text.length > 120 ? `${text.slice(0, 117)}...` : text;
+        lines.push(`- tool_result: ${clipped}`);
+      }
+      continue;
+    }
+    if (msg.role === 'assistant') {
+      const text = textFromContent(msg.content).replace(/\s+/g, ' ').trim();
+      const toolCallCount = Array.isArray(msg.tool_calls) ? msg.tool_calls.length : 0;
+      const toolInfo = toolCallCount > 0 ? ` [called ${toolCallCount} tool(s)]` : '';
+      const clipped = text.length > 300 ? `${text.slice(0, 297)}...` : text;
+      lines.push(`- assistant: ${clipped}${toolInfo}`);
+      continue;
+    }
+    if (msg.role === 'user') {
+      const text = textFromContent(msg.content).replace(/\s+/g, ' ').trim();
+      const clipped = text.length > 200 ? `${text.slice(0, 197)}...` : text;
+      lines.push(`- user: ${clipped}`);
+      continue;
+    }
     const text = textFromContent(msg.content).replace(/\s+/g, ' ').trim();
     if (!text) continue;
-    const clipped = text.length > 160 ? `${text.slice(0, 160)}...` : text;
+    const clipped = text.length > 160 ? `${text.slice(0, 157)}...` : text;
     lines.push(`- ${msg.role}: ${clipped}`);
   }
   return `Context Summary\n${lines.join('\n')}`.trim();

package/src/core/default-system-prompt.js

@@ -1,5 +1,26 @@
+import os from 'node:os';
+import fs from 'node:fs';
 import { getShellSystemPrompt } from './shell-profile.js';
 
+function getEnvBlock() {
+  const cwd = process.cwd();
+  let isGitRepo = false;
+  try {
+    fs.accessSync(`${cwd}/.git`);
+    isGitRepo = true;
+  } catch {}
+
+  return `<env>
+Working directory: ${cwd}
+Is directory a git repo: ${isGitRepo ? 'Yes' : 'No'}
+Platform: ${process.platform}
+Shell: ${os.userInfo().shell || 'unknown'}
+OS Version: ${os.version || os.release()}
+</env>`;
+}
+
 export function buildDefaultSystemPrompt(config = {}) {
-  return `${getShellSystemPrompt(config?.shell?.default)} If a command or tool is blocked or fails, inspect the error and retry with allowed commands or tools. For AST-scoped edits, if edit rejects a call because kind=replace_block or ast_target is missing or stale, fix the tool arguments and retry instead of switching to a broader text edit. Do not claim filesystem access is impossible unless the allowed search/read tools also fail.`;
+  return `${getShellSystemPrompt(config?.shell?.default)}
+
+${getEnvBlock()}`;
 }

package/src/core/shell-profile.js

@@ -118,5 +118,41 @@ export function getEffectivePolicy(config) {
 
 export function getShellSystemPrompt(value) {
   const profile = getShellProfile(value);
-  return `You are CodeMini CLI working in a ${profile.label} shell environment. Prefer OpenCode-style primary tools first: use read to inspect files, grep to search file contents, glob to find files by pattern, list to inspect directories, edit to modify existing files, write to create or fully rewrite files when appropriate, patch to apply unified diffs, and run for one-shot shell commands like install, build, test, or other finite tasks. For structural code edits such as changing a function, method, or class, prefer the AST-first workflow: use ast_query to select the syntax node, use read_ast_node to inspect that node, then use edit with ast_target and kind=replace_block so the write stays constrained to the selected node. Fall back to plain grep/read/edit only when AST selection is not appropriate. Classify frontend, backend, database, and Docker work carefully: use run for finite commands, and use start_service, list_services, get_service_status, get_service_logs, and stop_service for long-running servers, watchers, and dev processes. Treat edit as the default editing path for existing code. Internal low-level edit strategies such as target resolution, block replacement, exact text replacement, and anchored inserts are handled inside edit rather than exposed as separate tools. Use generate_diff when you need a structured preview of a proposed file change. For existing code files, prefer grep/read/edit and only use write with full_file_rewrite=true when a whole-file rewrite is truly intended. Avoid unnecessary tool calls.`;
+  return `You are CodeMini CLI, an AI coding assistant running in a ${profile.label} shell environment.
+
+# Using your tools
+
+ALWAYS prefer dedicated tools over raw shell commands:
+- Use read to inspect files — NEVER use cat, head, or tail via run
+- Use grep to search file contents — NEVER use grep or rg via run
+- Use glob to find files by pattern — NEVER use find via run
+- Use edit to modify existing files — this is the DEFAULT path for code changes
+- Use write only for creating new files or complete rewrites (set full_file_rewrite=true for existing code files)
+- Use patch to apply unified diffs
+- Use run for one-shot shell commands: install, build, test, or other finite tasks
+- For long-running processes (dev servers, watchers), use start_service instead of run
+
+For structural code edits (functions, classes, methods), use the AST-first workflow:
+ast_query → read_ast_node → edit with ast_target and kind=replace_block.
+Fall back to plain grep/read/edit only when AST is not appropriate.
+
+For services: use start_service to launch, list_services/get_service_status/get_service_logs to monitor, stop_service to stop.
+
+Some tools are loaded on demand. If a needed tool is not listed, call tool_search first to load it.
+
+# Doing tasks
+
+- If a command or tool is blocked or fails, inspect the error and retry with allowed commands or tools
+- For AST-scoped edits, if edit rejects due to missing or stale ast_target, fix arguments and retry
+- Do not claim filesystem access is impossible unless search/read tools also fail
+- Prefer editing existing files over creating new ones
+- Do not add comments, docstrings, or type annotations to code you did not change
+- Do not add features or refactor code beyond what was asked
+
+# Tone and style
+
+- Be concise. Go straight to the point
+- Do not restate what the user said
+- When referencing code, use file_path:line_number format
+- Only use emojis if the user explicitly requests it`;
 }

package/src/core/tools.js

@@ -15,6 +15,7 @@ import {
 import { evaluateCommandPolicy } from './command-policy.js';
 import { queryAst, readAstNode, resolveAstTarget } from './ast.js';
 import { initializeProjectIndex, refreshIndexedFile } from './project-index.js';
+import { checkReadDedup } from './agent-loop.js';
 
 const SKIP_DIRS = new Set(['.git', 'node_modules', '.codemini', '.codemini-global', 'dist', 'coverage']);
 const TEXT_EXTENSIONS = new Set([
@@ -722,6 +723,26 @@ async function readFile(root, args) {
     truncated = true;
   }
 
+  // Read deduplication: if same path+range+mtime was read before, return a short stub
+  const isDuplicate = checkReadDedup(
+    args?.path,
+    startLine,
+    endLine,
+    stat.mtimeMs
+  );
+  if (isDuplicate) {
+    return {
+      path: args?.path,
+      phase: 'content',
+      start_line: startLine,
+      end_line: endLine,
+      total_lines: totalLines,
+      truncated: false,
+      unchanged: true,
+      content: `File unchanged since last read. The content from the earlier read tool_result in this conversation is still current -- refer to that instead of re-reading.`
+    };
+  }
+
   return {
     path: args?.path,
     phase: 'content',
@@ -1711,22 +1732,22 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       return null;
     }
   };
-  const definitions = [
+  const primaryDefinitions = [
     {
       type: 'function',
       function: {
         name: 'read',
         description:
-          'Primary read tool. First call returns metadata+read_token, second call with include_content=true and matching read_token returns content',
+          'Read a file. Call once for metadata and a read_token, then again with include_content=true and the same token to get content. Use this before editing.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string' },
-            start_line: { type: 'number' },
-            end_line: { type: 'number' },
-            max_chars: { type: 'number' },
-            include_content: { type: 'boolean' },
-            read_token: { type: 'string' }
+            path: { type: 'string', description: 'File path to read' },
+            start_line: { type: 'number', description: '1-based start line' },
+            end_line: { type: 'number', description: 'Inclusive end line' },
+            max_chars: { type: 'number', description: 'Max chars to return' },
+            include_content: { type: 'boolean', description: 'Set true on the second call' },
+            read_token: { type: 'string', description: 'Token from the first call' }
           },
           required: ['path']
         }
@@ -1736,18 +1757,19 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'grep',
-        description: 'Search file contents using a plain string or regex pattern and return compact matches',
+        description:
+          'Search file contents. Use this for code search instead of grep or rg in run.',
         parameters: {
           type: 'object',
           properties: {
-            pattern: { type: 'string' },
-            query: { type: 'string' },
-            path: { type: 'string' },
-            regex: { type: 'boolean' },
-            case_sensitive: { type: 'boolean' },
-            max_results: { type: 'number' },
-            language: { type: 'string' },
-            file_types: { type: 'array', items: { type: 'string' } }
+            pattern: { type: 'string', description: 'Search pattern' },
+            query: { type: 'string', description: 'Alias for pattern' },
+            path: { type: 'string', description: 'Directory or file to search' },
+            regex: { type: 'boolean', description: 'Treat pattern as regex' },
+            case_sensitive: { type: 'boolean', description: 'Case-sensitive matching' },
+            max_results: { type: 'number', description: 'Max matches to return' },
+            language: { type: 'string', description: 'Filter by language' },
+            file_types: { type: 'array', items: { type: 'string' }, description: 'Filter by file glob' }
           },
           required: ['pattern']
         }
@@ -1757,14 +1779,15 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'glob',
-        description: 'Find files by glob pattern such as **/*.ts or src/**/*.tsx',
+        description:
+          'Find files by glob pattern. Use this for file discovery instead of find in run.',
         parameters: {
           type: 'object',
           properties: {
-            pattern: { type: 'string' },
-            path: { type: 'string' },
-            include_hidden: { type: 'boolean' },
-            max_results: { type: 'number' }
+            pattern: { type: 'string', description: 'Glob pattern' },
+            path: { type: 'string', description: 'Directory to search' },
+            include_hidden: { type: 'boolean', description: 'Include dotfiles' },
+            max_results: { type: 'number', description: 'Max results' }
           },
           required: ['pattern']
         }
@@ -1774,12 +1797,12 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       type: 'function',
       function: {
         name: 'list',
-        description: 'List files and directories in a workspace path',
+        description: 'List files and directories in a workspace path.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string' },
-            include_hidden: { type: 'boolean' }
+            path: { type: 'string', description: 'Directory path to list' },
+            include_hidden: { type: 'boolean', description: 'Include dotfiles' }
           }
         }
       }
@@ -1789,24 +1812,24 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
       function: {
         name: 'edit',
         description:
-          'Preferred edit tool for existing files. Accepts natural forms such as file + new_content for whole-file rewrites, file + symbol/line + new_content for block edits, file + old_text + new_text for exact replacements, and file + anchor_text + content for anchored inserts. When ast_target is provided, only replace_block is allowed and the write is constrained to that exact syntax node. If a file has just been selected via ast_query, the cached ast_target may be reused when omitted.',
+          'Edit existing files. Use block edits, exact replacements, or anchored inserts. When ast_target is provided, keep the edit constrained to that node. Prefer this over write for code changes.',
         parameters: {
           type: 'object',
           properties: {
-            file: { type: 'string' },
-            path: { type: 'string' },
-            new_content: { type: 'string' },
-            old_text: { type: 'string' },
-            new_text: { type: 'string' },
-            anchor_text: { type: 'string' },
-            content: { type: 'string' },
-            position: { type: 'string' },
-            kind: { type: 'string' },
-            target: { type: 'object' },
-            ast_target: { type: 'object' },
-            symbol: { type: 'string' },
-            line: { type: 'number' },
-            edit: { type: 'object' },
+            file: { type: 'string', description: 'File path to edit' },
+            path: { type: 'string', description: 'Alias for file' },
+            new_content: { type: 'string', description: 'Replacement content' },
+            old_text: { type: 'string', description: 'Exact text to replace' },
+            new_text: { type: 'string', description: 'Replacement text' },
+            anchor_text: { type: 'string', description: 'Anchor text for inserts' },
+            content: { type: 'string', description: 'Content to insert or append' },
+            position: { type: 'string', description: 'before or after' },
+            kind: { type: 'string', description: 'replace_block, replace_text, insert_before, insert_after, or rewrite_file' },
+            target: { type: 'object', description: 'Location object with symbol or line info' },
+            ast_target: { type: 'object', description: 'AST target from ast_query' },
+            symbol: { type: 'string', description: 'Symbol to target' },
+            line: { type: 'number', description: 'Line to target' },
+            edit: { type: 'object', description: 'Structured edit input' }
           },
           required: ['file']
         }
@@ -1815,77 +1838,96 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
     {
       type: 'function',
       function: {
-        name: 'ast_query',
+        name: 'write',
         description:
-          'Run a Tree-sitter query against a code file and return explicit ast_target objects that can be passed into read_ast_node or edit for node-scoped changes. Prefer the returned ast_target verbatim in the next read_ast_node or edit call.',
+          'Create a new file or overwrite a file. Use this for new files or full rewrites. Prefer edit for existing code.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string' },
-            language: { type: 'string' },
-            query: { type: 'string' },
-            capture_name: { type: 'string' },
-            max_results: { type: 'number' }
+            path: { type: 'string', description: 'File path to create or overwrite' },
+            content: { type: 'string', description: 'Content to write' },
+            append: { type: 'boolean', description: 'Append instead of overwrite' },
+            full_file_rewrite: { type: 'boolean', description: 'Set true for whole-file rewrites' }
           },
-          required: ['path', 'query']
+          required: ['path', 'content']
         }
       }
     },
     {
       type: 'function',
       function: {
-        name: 'read_ast_node',
+        name: 'run',
         description:
-          'Read the current source and compact structural context for a previously selected AST node using ast_target. If omitted, the most recent ast_query selection for the same file may be reused.',
+          'Run a one-shot shell command such as install, build, or test. Do not use for long-running services or file search.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string' },
-            language: { type: 'string' },
-            ast_target: { type: 'object' }
+            command: { type: 'string', description: 'Shell command to execute' },
+            timeout: { type: 'number', description: 'Timeout in milliseconds' }
           },
-          required: ['path', 'ast_target']
+          required: ['command']
         }
       }
     },
     {
       type: 'function',
       function: {
-        name: 'write',
+        name: 'tool_search',
+        description:
+          'Load one deferred tool schema by name. Use this when a needed tool is not in the current tool list.',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Tool name to load, or "all"' }
+          },
+          required: ['query']
+        }
+      }
+    }
+  ];
+
+  const deferredDefinitions = {
+    ast_query: {
+      type: 'function',
+      function: {
+        name: 'ast_query',
         description:
-          'Primary write tool. Create a UTF-8 text file or overwrite an existing file. Existing code files require full_file_rewrite=true for whole-file overwrites.',
+          'Run a Tree-sitter query on a code file and return ast_target objects for node-scoped reads or edits.',
         parameters: {
           type: 'object',
           properties: {
             path: { type: 'string' },
-            content: { type: 'string' },
-            append: { type: 'boolean' },
-            full_file_rewrite: { type: 'boolean' }
+            language: { type: 'string' },
+            query: { type: 'string' },
+            capture_name: { type: 'string' },
+            max_results: { type: 'number' }
           },
-          required: ['path', 'content']
+          required: ['path', 'query']
         }
       }
     },
-    {
+    read_ast_node: {
       type: 'function',
       function: {
-        name: 'run',
+        name: 'read_ast_node',
         description:
-          'Primary run tool. Execute a one-shot shell command in workspace such as install, build, test, or other finite tasks. Do not use for long-running services or watchers.',
+          'Read a previously selected AST node with compact structural context.',
         parameters: {
           type: 'object',
           properties: {
-            command: { type: 'string' }
+            path: { type: 'string' },
+            language: { type: 'string' },
+            ast_target: { type: 'object' }
           },
-          required: ['command']
+          required: ['path', 'ast_target']
         }
       }
     },
-    {
+    generate_diff: {
       type: 'function',
       function: {
         name: 'generate_diff',
-        description: 'Generate a unified diff between the current file and proposed content',
+        description: 'Generate a unified diff for proposed content',
         parameters: {
           type: 'object',
           properties: {
@@ -1896,11 +1938,11 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
-    {
+    patch: {
       type: 'function',
       function: {
         name: 'patch',
-        description: 'Apply one or more unified diff hunks to files in the workspace',
+        description: 'Apply one or more unified diff hunks to workspace files',
         parameters: {
           type: 'object',
           properties: {
@@ -1911,12 +1953,12 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
-    {
+    start_service: {
       type: 'function',
       function: {
         name: 'start_service',
         description:
-          'Start a long-running local service, such as a frontend, backend, database, or dev watcher, and return a compact service handle instead of blocking on process exit.',
+          'Start a long-running local service and return a compact handle.',
         parameters: {
           type: 'object',
           properties: {
@@ -1939,22 +1981,22 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
-    {
+    list_services: {
       type: 'function',
       function: {
         name: 'list_services',
-        description: 'List all tracked local services and their compact current status.',
+        description: 'List tracked local services and their current status.',
         parameters: {
           type: 'object',
           properties: {}
         }
       }
     },
-    {
+    get_service_status: {
       type: 'function',
       function: {
         name: 'get_service_status',
-        description: 'Get the current status of a previously started service.',
+        description: 'Get the status of a started service.',
         parameters: {
           type: 'object',
           properties: {
@@ -1964,11 +2006,11 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
-    {
+    get_service_logs: {
       type: 'function',
       function: {
         name: 'get_service_logs',
-        description: 'Read recent logs from a previously started service.',
+        description: 'Read recent logs from a started service.',
         parameters: {
           type: 'object',
           properties: {
@@ -1980,11 +2022,11 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     },
-    {
+    stop_service: {
       type: 'function',
       function: {
         name: 'stop_service',
-        description: 'Stop a previously started service.',
+        description: 'Stop a started service.',
         parameters: {
           type: 'object',
           properties: {
@@ -1994,7 +2036,9 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
         }
       }
     }
-  ].filter(Boolean);
+  };
+
+  const definitions = [...primaryDefinitions];
 
   const handlers = {
     read: (args) =>
@@ -2052,8 +2096,205 @@ export function getBuiltinTools({ workspaceRoot = process.cwd(), config, onSyste
     list_services: () => listServices(workspaceRoot),
     get_service_status: (args) => getServiceStatus(workspaceRoot, args),
     get_service_logs: (args) => getServiceLogs(workspaceRoot, args),
-    stop_service: (args) => stopService(workspaceRoot, args)
+    stop_service: (args) => stopService(workspaceRoot, args),
+    tool_search: (args) => {
+      const query = String(args?.query || '').trim().toLowerCase();
+      if (query === 'all') {
+        const all = Object.values(deferredDefinitions);
+        return {
+          loaded: Object.keys(deferredDefinitions),
+          schemas: all,
+          message: `Loaded all ${all.length} deferred tools. You can now call them directly.`
+        };
+      }
+      const match = Object.entries(deferredDefinitions).find(([name]) => name === query);
+      if (!match) {
+        const available = Object.keys(deferredDefinitions).join(', ');
+        return { error: `Unknown tool: "${query}". Available deferred tools: ${available}` };
+      }
+      return {
+        loaded: [match[0]],
+        schemas: [match[1]],
+        message: `Loaded tool "${match[0]}". You can now call it in your next response.`
+      };
+    }
+  };
+
+  const formatters = {
+    read(result) {
+      if (typeof result === 'string') return result;
+      if (!result || typeof result !== 'object') return String(result);
+      // Phase 1 metadata: small, return as-is
+      if (result.phase === 'metadata') {
+        return JSON.stringify(result);
+      }
+      // Phase 2 content: structured header + head/tail content
+      if (result.phase === 'content') {
+        const header = `[File: ${result.path}, lines ${result.start_line || 1}-${result.end_line || '?'}${result.total_lines ? ` of ${result.total_lines}` : ''}${result.truncated ? ', truncated' : ''}]`;
+        const content = result.content || '';
+        if (typeof content !== 'string' || content.length <= 3000) {
+          return `${header}\n${content}`;
+        }
+        const headLen = 1800;
+        const tailLen = 800;
+        return `${header}\n${content.slice(0, headLen)}\n... [omitted ${content.length - headLen - tailLen} chars] ...\n${content.slice(-tailLen)}`;
+      }
+      return JSON.stringify(result);
+    },
+
+    grep(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const { pattern, matches, truncated } = result;
+      const header = pattern ? `[grep: "${pattern}"]` : '';
+      if (!Array.isArray(matches) || matches.length === 0) return `${header}\nNo matches found.`;
+      if (matches.length <= 30) {
+        const lines = matches.map((m) => `${m.path}:${m.line}: ${String(m.preview || '').slice(0, 120)}`);
+        return `${header}\n${lines.join('\n')}`;
+      }
+      const shown = matches.slice(0, 30).map((m) => `${m.path}:${m.line}: ${String(m.preview || '').slice(0, 120)}`);
+      return `${header}\n${shown.join('\n')}\n... and ${matches.length - 30} more matches [total: ${matches.length}${truncated ? ', results were truncated' : ''}]`;
+    },
+
+    glob(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const { pattern, matches, truncated } = result;
+      const header = pattern ? `[glob: "${pattern}"]` : '';
+      if (!Array.isArray(matches) || matches.length === 0) return `${header}\nNo files found.`;
+      if (matches.length <= 50) {
+        return `${header}\n${matches.join('\n')}`;
+      }
+      const shown = matches.slice(0, 50);
+      return `${header}\n${shown.join('\n')}\n... and ${matches.length - 50} more files [total: ${matches.length}${truncated ? ', results were truncated' : ''}]`;
+    },
+
+    list(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      if (!Array.isArray(result.items)) return JSON.stringify(result);
+      const header = result.path ? `[${result.path}]` : '';
+      const dirs = result.items.filter((i) => i.type === 'dir').map((i) => `${i.name}/`);
+      const files = result.items.filter((i) => i.type === 'file').map((i) => i.name);
+      return `${header}\n${dirs.join('\n')}${dirs.length && files.length ? '\n' : ''}${files.join('\n')}`;
+    },
+
+    edit(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const p = result.path || '';
+      const action = result.action || '';
+      const line = result.changed_line || 0;
+      const summary = `${action} ${p}${line > 0 ? ` @L${line}` : ''}`;
+      const diffPreview = result.diff_preview || '';
+      if (diffPreview) {
+        const trimmed = diffPreview.length > 600 ? `${diffPreview.slice(0, 597)}...` : diffPreview;
+        return `${summary}\n${trimmed}`;
+      }
+      return summary + (result.ok !== false ? '' : ` [FAILED: ${result.error || 'unknown'}]`);
+    },
+
+    write(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const p = result.path || '';
+      const action = result.action || 'write';
+      const line = result.changed_line || 0;
+      const summary = `${action} ${p}${line > 0 ? ` @L${line}` : ''}`;
+      const diffPreview = result.diff_preview || '';
+      if (diffPreview) {
+        const trimmed = diffPreview.length > 600 ? `${diffPreview.slice(0, 597)}...` : diffPreview;
+        return `${summary}\n${trimmed}`;
+      }
+      return summary;
+    },
+
+    run(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const command = String(result.command || '').slice(0, 200);
+      const stdout = String(result.stdout || '').slice(0, 500);
+      const stderr = String(result.stderr || '').slice(0, 500);
+      const code = result.code ?? 0;
+      const parts = [`[exit: ${code}]`];
+      if (command) parts.push(`command: ${command}`);
+      if (stdout) parts.push(`stdout:\n${stdout}`);
+      if (stderr) parts.push(`stderr:\n${stderr}`);
+      return parts.join('\n');
+    },
+
+    generate_diff(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const p = result.path || '';
+      const diff = result.diff || '';
+      if (diff.length <= 2000) return `${p ? `[${p}]\n` : ''}${diff}`;
+      return `${p ? `[${p}]\n` : ''}${diff.slice(0, 1997)}...\n[diff truncated: ${diff.length} chars total]`;
+    },
+
+    patch(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      if (Array.isArray(result.files)) {
+        const names = result.files.slice(0, 10).map((f) => typeof f === 'string' ? f : f.path || '?');
+        return `patched ${result.files.length} file(s): ${names.join(', ')}${result.files.length > 10 ? ` ... +${result.files.length - 10} more` : ''}`;
+      }
+      const p = result.path || '';
+      const line = result.changed_line || 0;
+      return `patched ${p}${line > 0 ? ` @L${line}` : ''}${result.ok === false ? ` [FAILED: ${result.error || ''}]` : ''}`;
+    },
+
+    ast_query(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      if (!Array.isArray(result.matches)) return JSON.stringify(result);
+      const header = `[ast_query: ${result.matches.length} match(es)]`;
+      const lines = result.matches.slice(0, 20).map((m) => {
+        const name = m.name || m.ast_target?.name || '?';
+        const kind = m.kind || m.ast_target?.kind || '?';
+        return `  ${kind} ${name}`;
+      });
+      return `${header}\n${lines.join('\n')}${result.matches.length > 20 ? `\n... +${result.matches.length - 20} more` : ''}`;
+    },
+
+    read_ast_node(result) {
+      if (typeof result === 'string') return result;
+      if (!result || typeof result !== 'object') return String(result);
+      const name = result.name || '';
+      const kind = result.kind || '';
+      const content = result.content || result.source || '';
+      const header = `${kind} ${name}`;
+      if (typeof content !== 'string' || content.length <= 2000) return `${header}\n${content}`;
+      return `${header}\n${content.slice(0, 1200)}\n... [omitted ${content.length - 1600} chars] ...\n${content.slice(-400)}`;
+    },
+
+    start_service(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const tid = result.task_id || '';
+      const status = result.status || 'unknown';
+      const confirmed = result.startup_confirmed ? 'ready' : 'starting';
+      const url = result.url || '';
+      return `${tid} ${status} (${confirmed})${url ? ` -> ${url}` : ''}`;
+    },
+
+    list_services(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      if (!Array.isArray(result.services)) return JSON.stringify(result);
+      if (result.services.length === 0) return 'No services running.';
+      return result.services.map((s) => `${s.task_id || '?'} ${s.status || 'unknown'}${s.command ? ` (${s.command.slice(0, 60)})` : ''}`).join('\n');
+    },
+
+    get_service_status(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const tid = result.task_id || '';
+      const status = result.status || 'unknown';
+      const url = result.url || '';
+      const logs = Array.isArray(result.recent_logs) ? result.recent_logs.slice(-3).join('\n') : '';
+      return `${tid} ${status}${url ? ` -> ${url}` : ''}${logs ? `\n${logs}` : ''}`;
+    },
+
+    get_service_logs(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      const logs = Array.isArray(result.recent_logs) ? result.recent_logs.join('\n') : '';
+      return logs || 'No recent logs.';
+    },
+
+    stop_service(result) {
+      if (!result || typeof result !== 'object') return String(result);
+      return `${result.task_id || '?'} stopped${result.exit_code != null ? ` (exit ${result.exit_code})` : ''}`;
+    }
   };
 
-  return { definitions, handlers };
+  return { definitions, handlers, formatters, deferredDefinitions };
 }