sapper-iq 1.1.37 → 1.1.39

package/sapper.mjs

@@ -6,9 +6,10 @@ import chalk from 'chalk';
 import ora from 'ora';
 import readline from 'readline';
 import { fileURLToPath } from 'url';
-import { dirname, join } from 'path';
+import { dirname, join, isAbsolute, resolve as pathResolve } from 'path';
 import { marked } from 'marked';
 import { markedTerminal } from 'marked-terminal';
+import { highlight as highlightCode } from 'cli-highlight';
 import * as acorn from 'acorn';
 
 const __filename = fileURLToPath(import.meta.url);
@@ -44,7 +45,7 @@ process.on('SIGINT', () => {
   
   // Reset terminal immediately
   resetTerminal();
-  setTimeout(() => { ctrlCCount = 0; }, 2000); // Reset after 2 seconds
+  setTimeout(() => { ctrlCCount = 0; }, LIMITS.CTRL_C_RESET_MS);
 });
 
 // Reset terminal state - fixes "ghost input" after shell commands or AI streaming
@@ -82,6 +83,60 @@ const SKILLS_DIR = `${SAPPER_DIR}/skills`;
 const LOGS_DIR = `${SAPPER_DIR}/logs`;
 const SAPPERIGNORE_FILE = '.sapperignore';
 
+// ═══════════════════════════════════════════════════════════════
+// CENTRALIZED LIMITS & THRESHOLDS
+// ═══════════════════════════════════════════════════════════════
+const LIMITS = Object.freeze({
+  // Timeouts (milliseconds)
+  CTRL_C_RESET_MS:        2000,
+  FETCH_URL_TIMEOUT_MS:   15000,
+
+  // Context & summarization
+  CONTEXT_BYTE_FALLBACK:  32000,    // Byte threshold when token count unavailable
+  SUMMARY_RECENT_MSGS:    4,        // Recent messages preserved during summarization
+  MSG_TRUNCATION_CHARS:   1500,     // Max chars per message when building summary text
+  SUMMARY_MAX_WORDS:      800,      // Target word count for summary output
+
+  // Embeddings
+  EMBEDDINGS_MAX_TEXT:     2000,     // Max chars stored per embedding chunk
+  EMBEDDINGS_MAX_CHUNKS:  100,      // Max chunks kept in embeddings file
+  EMBEDDING_SIMILARITY:   0.5,      // Cosine similarity threshold for recall
+  EMBEDDING_TOP_K:        3,        // Default top-K results from memory search
+  EMBEDDING_MIN_TEXT:     50,       // Minimum text length to bother embedding
+
+  // Streaming & response
+  MAX_RESPONSE_LENGTH:    100000,   // 100KB hard cap on AI response size
+  REPETITION_WINDOW:      500,      // Chars to compare for loop detection
+  REPETITION_THRESHOLD:   10000,    // Min response length before checking for loops
+  REPETITION_COUNT:       3,        // Repeats before stopping
+
+  // Display
+  LOG_PREVIEW_CHARS:      500,      // Max chars in activity log preview
+  LOG_AI_PREVIEW_CHARS:   800,      // Max chars in AI response log preview
+  INPUT_PREVIEW_CHARS:    120,      // Max chars shown for user input preview
+  TERMINAL_WIDTH_MAX:     90,       // Max width for activity log box
+  SYMBOL_RESULTS_MAX:     15,       // Max results before "and N more" in /symbol
+  LOG_FILES_DISPLAY_MAX:  10,       // Max log files shown in /log list
+  MEMORY_PREVIEW_CHARS:   300,      // Chars shown in /recall results
+  DEBUG_TOOL_PREVIEW:     150,      // Chars shown in debug tool attempt
+
+  // Content limits
+  WEB_CONTENT_MAX_CHARS:  50000,    // Max chars from fetched web content
+  TOOL_WARN_THRESHOLD:    30,       // Tool calls per round before warning
+
+  // Shell
+  SHELL_MIN_BG_SECONDS:   2,       // Min seconds for background shell config
+  SHELL_MAX_BG_SECONDS:   120,     // Max seconds for background shell config
+  SHELL_MIN_CHUNK_CHARS:  400,     // Min chars for shell output chunk config
+  SHELL_MAX_CHUNK_CHARS:  12000,   // Max chars for shell output chunk config
+  SHELL_MAX_BUFFER:       50000,   // Max buffered shell output chars
+
+  // Workspace & scanning
+  WORKSPACE_FILES_PER_DIR: 10,     // Files shown per directory in workspace summary
+  WORKSPACE_RELATED_DEPTH: 5,      // Max related files from dependency graph
+  FILE_SUMMARY_PREVIEW:    150,    // Chars for file content summary
+});
+
 // ═══════════════════════════════════════════════════════════════
 // COMPREHENSIVE ACTIVITY LOGGER
 // ═══════════════════════════════════════════════════════════════
@@ -145,7 +200,7 @@ function appendLogToFile(entry) {
         break;
       case 'user':
         line += `### 💬 User Input \`${time}\` _(+${elapsed})_\n`;
-        line += `\`\`\`\n${entry.message?.substring(0, 500)}${entry.message?.length > 500 ? '\n...' : ''}\n\`\`\`\n`;
+        line += `\`\`\`\n${entry.message?.substring(0, LIMITS.LOG_PREVIEW_CHARS)}${entry.message?.length > LIMITS.LOG_PREVIEW_CHARS ? '\n...' : ''}\n\`\`\`\n`;
         if (entry.attachments?.length > 0) {
           line += `📎 **Attached:** ${entry.attachments.join(', ')}\n`;
         }
@@ -159,7 +214,7 @@ function appendLogToFile(entry) {
         if (entry.interrupted) line += `- ⚠️ **Interrupted**\n`;
         if (entry.repetitionStopped) line += `- ⚠️ **Stopped: repetitive output**\n`;
         line += `\n<details><summary>Response preview</summary>\n\n`;
-        line += `${entry.preview?.substring(0, 800)}${entry.preview?.length > 800 ? '\n...' : ''}\n`;
+        line += `${entry.preview?.substring(0, LIMITS.LOG_AI_PREVIEW_CHARS)}${entry.preview?.length > LIMITS.LOG_AI_PREVIEW_CHARS ? '\n...' : ''}\n`;
         line += `\n</details>\n\n`;
         break;
       case 'tool':
@@ -531,23 +586,107 @@ const TOOL_NAME_MAP = {
   'edit': 'PATCH',
   'patch': 'PATCH',
   'list': 'LIST',
+  'ls': 'LS',
   'search': 'SEARCH',
+  'grep': 'GREP',
+  'find': 'FIND',
   'shell': 'SHELL',
   'mkdir': 'MKDIR',
+  'rmdir': 'RMDIR',
+  'cd': 'CD',
+  'pwd': 'PWD',
+  'cat': 'CAT',
+  'head': 'HEAD',
+  'tail': 'TAIL',
+  'changes': 'CHANGES',
+  'diff': 'CHANGES',
+  'git_changes': 'CHANGES',
+  'fetch': 'FETCH',
+  'web': 'FETCH',
+  'fetch_web': 'FETCH',
+  'memory': 'MEMORY',
+  'recall': 'MEMORY',
+  'recall_memory': 'MEMORY',
+  'open': 'OPEN',
+  'browser': 'OPEN',
+  'open_url': 'OPEN',
   'todo': 'LIST',   // alias — list tasks
 };
 
+const TOOL_ALLOWED_BY = {
+  READ: ['READ', 'CAT', 'HEAD', 'TAIL'],
+  CAT: ['READ', 'CAT', 'HEAD', 'TAIL'],
+  HEAD: ['READ', 'CAT', 'HEAD', 'TAIL'],
+  TAIL: ['READ', 'CAT', 'HEAD', 'TAIL'],
+  LIST: ['LIST', 'LS'],
+  LS: ['LIST', 'LS'],
+  SEARCH: ['SEARCH', 'GREP'],
+  GREP: ['SEARCH', 'GREP'],
+  FIND: ['FIND'],
+  WRITE: ['WRITE'],
+  PATCH: ['PATCH'],
+  MKDIR: ['MKDIR'],
+  RMDIR: ['RMDIR', 'SHELL'],
+  PWD: ['PWD', 'SHELL'],
+  CD: ['CD', 'SHELL'],
+  CHANGES: ['CHANGES', 'SHELL'],
+  FETCH: ['FETCH', 'SHELL'],
+  MEMORY: ['MEMORY'],
+  OPEN: ['OPEN', 'SHELL'],
+  SHELL: ['SHELL'],
+};
+
+function normalizeToolName(toolName = '') {
+  const normalized = String(toolName ?? '').trim();
+  if (!normalized) return '';
+  return TOOL_NAME_MAP[normalized.toLowerCase()] || normalized.toUpperCase();
+}
+
 function normalizeToolList(toolsValue) {
   if (!toolsValue) return null; // null = all tools allowed
   if (typeof toolsValue === 'string') {
     toolsValue = toolsValue.split(',').map(s => s.trim());
   }
   if (!Array.isArray(toolsValue)) return null;
-  return toolsValue.map(t => TOOL_NAME_MAP[t.toLowerCase()] || t.toUpperCase()).filter(Boolean);
+  return Array.from(new Set(toolsValue.map(normalizeToolName).filter(Boolean)));
 }
 
-// Load all agents from .sapper/agents/*.md (with frontmatter support)
+function isToolAllowedForAgent(allowedTools, toolName) {
+  if (!allowedTools || allowedTools.length === 0) return true;
+  const normalized = normalizeToolName(toolName);
+  const allowedBy = TOOL_ALLOWED_BY[normalized] || [normalized];
+  return allowedBy.some(candidate => allowedTools.includes(candidate));
+}
+
+// ── Memoized loaders (avoid re-scanning filesystem every prompt turn) ──
+const _loaderCache = { agents: null, agentsAt: 0, skills: null, skillsAt: 0 };
+const LOADER_CACHE_TTL = 5000; // 5s TTL — balances freshness vs disk I/O
+
 function loadAgents() {
+  const now = Date.now();
+  if (_loaderCache.agents && now - _loaderCache.agentsAt < LOADER_CACHE_TTL) return _loaderCache.agents;
+  const result = _loadAgentsFromDisk();
+  _loaderCache.agents = result;
+  _loaderCache.agentsAt = now;
+  return result;
+}
+
+function loadSkills() {
+  const now = Date.now();
+  if (_loaderCache.skills && now - _loaderCache.skillsAt < LOADER_CACHE_TTL) return _loaderCache.skills;
+  const result = _loadSkillsFromDisk();
+  _loaderCache.skills = result;
+  _loaderCache.skillsAt = now;
+  return result;
+}
+
+function invalidateLoaderCache(which = 'both') {
+  if (which === 'both' || which === 'agents') { _loaderCache.agents = null; _loaderCache.agentsAt = 0; }
+  if (which === 'both' || which === 'skills') { _loaderCache.skills = null; _loaderCache.skillsAt = 0; }
+}
+
+// Load all agents from .sapper/agents/*.md (with frontmatter support)
+function _loadAgentsFromDisk() {
   ensureAgentsDirs();
   const agents = {};
   try {
@@ -573,7 +712,7 @@ function loadAgents() {
 }
 
 // Load all skills from .sapper/skills/*.md (with frontmatter support)
-function loadSkills() {
+function _loadSkillsFromDisk() {
   ensureAgentsDirs();
   const skills = {};
   try {
@@ -604,27 +743,48 @@ function createDefaultAgentsAndSkills() {
   const defaultAgents = {
     'sapper-it': `---
 name: "Sapper IT"
-description: "Expert full-stack coding agent — handles web dev, architecture, debugging, DevOps, databases, APIs, and performance. Use for any coding task."
-tools: [read, edit, write, list, search, shell]
+description: "General software development agent — implementation, debugging, refactoring, architecture, testing, tooling, automation, and release workflows across languages and stacks. Use for coding or technical problem-solving."
+argument-hint: "Describe the feature, bug, refactor, architecture, or development task to work on."
 ---
 
-# Sapper IT - Coding Agent
+# Sapper IT - Development Agent
 
-You are Sapper IT, an expert full-stack coding agent working within Sapper.
+You are Sapper IT, a senior software development agent working within Sapper.
 
-## Your Expertise
-- Full-stack web development (frontend + backend)
-- System architecture and design patterns
-- Debugging, refactoring, and code review
-- DevOps, CI/CD, and deployment
-- Database design and optimization
-- API development (REST, GraphQL)
-- Performance optimization and security best practices
+  You have access to all available Sapper tools unless the session applies a separate restriction.
 
-## Behavior
-When the user asks for help, dive into the codebase using Sapper's tools. Read files, understand the structure, then make precise changes.
+## Mission
+
+Help users move software projects forward across different languages, frameworks, and codebases.
+Do not assume a specific stack, architecture, or workflow before inspecting the repository.
 
-Be technical, thorough, and code-first. Always verify your changes work by running tests or builds.`,
+Adapt to the project that exists, not a hard-coded template of technologies.
+
+## What You Handle
+
+- Feature implementation and bug fixing
+- Refactoring and code cleanup
+- Architecture and system design decisions
+- Tooling, build, automation, and developer workflow improvements
+- Tests, validation, and release-readiness checks
+- Performance, reliability, and maintainability problems
+- APIs, data flow, storage, and integration work when the codebase requires it
+
+## Working Style
+
+- Understand the request and inspect the relevant code before proposing or making changes.
+- Prefer the smallest change that solves the root problem cleanly.
+- Match the repository's existing conventions, abstractions, and naming.
+- Use tools proactively: read code, search broadly, edit precisely, and run shell commands when they help verify behavior.
+- Verify work proportionally with checks, builds, tests, or direct inspection when feasible.
+- Be concise, technical, and practical. Explain tradeoffs only when they matter.
+
+## Decision Rules
+
+- If the task is ambiguous, gather context first instead of guessing.
+- If multiple approaches are possible, choose the one with the best balance of correctness, simplicity, and fit for the current codebase.
+- If asked for a review, prioritize bugs, risks, regressions, and missing validation ahead of style commentary.
+- If a request spans unfamiliar technologies, infer behavior from the actual project files rather than generic assumptions.`,
 
     'writer': `---
 name: "Technical Writer"
@@ -818,7 +978,10 @@ function buildSystemPrompt(agentContent = null, skillContents = []) {
   const now = new Date();
   const dateStr = now.toLocaleDateString('en-US', { weekday: 'long', year: 'numeric', month: 'long', day: 'numeric' });
   const timeStr = now.toLocaleTimeString('en-US', { hour: '2-digit', minute: '2-digit' });
-  let prompt = `You are Sapper, an intelligent AI assistant with access to the local filesystem and shell.
+  const promptConfig = getPromptConfig();
+  const promptPrepend = promptConfig.prepend.trim();
+  const promptAppend = promptConfig.append.trim();
+  const corePrompt = promptConfig.coreOverride.trim() || `You are Sapper, an intelligent AI assistant with access to the local filesystem and shell.
 You can help with ANY task - coding, writing, research, planning, analysis, and more.
 Adapt your personality and expertise based on the active agent role and loaded skills.
 
@@ -830,28 +993,60 @@ RULES:
 3. BE PRECISE: When using patch, ensure the 'old_text' matches exactly.
 4. VERIFY: After making changes, verify they work (run tests, check output, etc).
 5. NO HALLUCINATIONS: If a file doesn't exist, don't guess its content. List the directory instead.`;
+  let prompt = promptPrepend
+    ? `${wrapPromptCustomizationBlock('CUSTOM PROMPT PREPEND', promptPrepend, false)}\n\n${corePrompt}`
+    : corePrompt;
 
   if (_useNativeToolsFlag) {
     prompt += `
 
 TOOLS:
 You have function-calling tools available. Call them directly — do NOT use [TOOL:...] text markers.
-Available tools: list_directory, read_file, search_files, write_file, patch_file, create_directory, run_shell.
+Available tools: list_directory, read_file, search_files, write_file, patch_file, create_directory, ls, cat, head, tail, grep, find, pwd, cd, rmdir, changes, fetch_web, recall_memory, open_url, run_shell.
 
 PATCH TIPS:
 - For patch_file, set old_text to "LINE:<number>" to replace a specific line by number (most reliable).
 - Always read_file first to see exact content before using patch_file.
-- If a patch fails, do NOT retry with slight variations. Switch to LINE:number mode or use write_file instead.`;
+- If a patch fails, do NOT retry with slight variations. Switch to LINE:number mode or use write_file instead.
+
+EXTRA TOOL TIPS:
+- ls lists directory contents using the current tool working directory when path is omitted.
+- cat reads a full file, while head and tail read the first or last N lines.
+- grep searches file contents, and find searches file or directory names.
+- pwd shows the current tool working directory, and cd changes it for later tool calls.
+- rmdir removes a directory recursively and always asks for approval.
+- changes shows git status and diff output for the current repository or an optional path.
+- fetch_web fetches a web page and returns readable text content.
+- recall_memory searches Sapper's saved conversation memory.
+- open_url opens a URL in the default browser and always asks for approval.
+
+SHELL TIPS:
+- run_shell may keep long-running commands in a background session depending on config.
+- If a shell result returns a session id, inspect more output with run_shell command "__shell_read__ <session_id>".
+- Use run_shell command "__shell_list__" to list sessions and "__shell_stop__ <session_id>" to stop one.`;
   } else {
     prompt += `
 
 TOOL SYNTAX (use these to interact with files and system):
 - [TOOL:LIST]dir[/TOOL] - List directory contents
+- [TOOL:LS]dir[/TOOL] - Alias for LIST
 - [TOOL:READ]file_path[/TOOL] - Read file contents
+- [TOOL:CAT]file_path[/TOOL] - Alias for READ
+- [TOOL:HEAD]file_path:::20[/TOOL] - Read the first N lines of a file (default 20)
+- [TOOL:TAIL]file_path:::20[/TOOL] - Read the last N lines of a file (default 20)
 - [TOOL:SEARCH]pattern[/TOOL] - Search files for pattern
+- [TOOL:GREP]pattern[/TOOL] - Alias for SEARCH
+- [TOOL:FIND]name_or_fragment[/TOOL] - Find files and directories by name
 - [TOOL:WRITE]path:::content[/TOOL] - Create/overwrite file
 - [TOOL:PATCH]path:::old|||new[/TOOL] - Edit existing file (exact match, trimmed, or fuzzy)
 - [TOOL:PATCH]path:::LINE:number|||new text[/TOOL] - Replace a specific line by number (PREFERRED — more reliable)
+- [TOOL:PWD][/TOOL] - Show the current tool working directory
+- [TOOL:CD]dir[/TOOL] - Change the tool working directory for later tool calls
+- [TOOL:RMDIR]dir[/TOOL] - Remove a directory recursively (asks for approval)
+- [TOOL:CHANGES]path[/TOOL] - Show git status and diffs for the repository or a path
+- [TOOL:FETCH]https://example.com[/TOOL] - Fetch a web page and return readable content
+- [TOOL:MEMORY]query[/TOOL] - Search saved conversation memory
+- [TOOL:OPEN]https://example.com[/TOOL] - Open a URL in the default browser (asks for approval)
 - [TOOL:SHELL]command[/TOOL] - Run shell command
 
 PATCH TIPS:
@@ -859,6 +1054,11 @@ PATCH TIPS:
 - Always READ the file first to see exact content before using PATCH.
 - If a PATCH fails, do NOT retry with slight variations. Switch to LINE:number mode or use WRITE instead.
 
+SHELL TIPS:
+- Long-running commands may be moved to a background shell session depending on config.
+- If shell output mentions a session id, inspect more output with [TOOL:SHELL]__shell_read__ <session_id>[/TOOL].
+- Use [TOOL:SHELL]__shell_list__[/TOOL] to list sessions and [TOOL:SHELL]__shell_stop__ <session_id>[/TOOL] to stop one.
+
 You MUST use the [TOOL:...][/TOOL] syntax above to perform actions. This is how you interact with the filesystem and shell - there is no other way. When you want to read a file, output [TOOL:READ]path[/TOOL] in your response. When you want to list a directory, output [TOOL:LIST].[/TOOL]. Always actually use the tools - do not just describe what you would do.
 Do NOT show tool syntax as examples or documentation to the user. Only use them to perform real actions.`;
   }
@@ -894,6 +1094,10 @@ FORBIDDEN TOOLS (DO NOT USE): ${forbidden.join(', ')}. You MUST NOT attempt to u
     prompt += `\n═══ END SKILLS ═══\n\nUse the knowledge from the loaded skills above when relevant to the user's request.`;
   }
 
+  if (promptAppend) {
+    prompt += wrapPromptCustomizationBlock('CUSTOM PROMPT APPEND', promptAppend);
+  }
+
   return prompt;
 }
 
@@ -902,20 +1106,218 @@ let currentAgent = null; // null = default Sapper, or agent name string
 let currentAgentTools = null; // null = all tools allowed, or array of allowed tool names
 let loadedSkills = []; // array of skill names currently loaded
 
-// Load config (settings like autoAttach)
+const DEFAULT_CONFIG = Object.freeze({
+  defaultModel: null,
+  defaultAgent: null,
+  autoAttach: true,
+  debug: false,
+  contextLimit: null,
+  toolRoundLimit: 40,
+  patchRetries: 3,
+  maxFileSize: 100000,
+  maxScanSize: 1000000,
+  maxUrlSize: 200000,
+  summaryPhases: true,
+  summarizeTriggerPercent: 65,
+  shell: Object.freeze({
+    streamToModel: true,
+    backgroundMode: 'auto',
+    backgroundAfterSeconds: 8,
+    outputChunkChars: 4000,
+  }),
+  streaming: Object.freeze({
+    showPhaseStatus: true,
+    showHeartbeat: true,
+    idleNoticeSeconds: 4,
+  }),
+  thinking: Object.freeze({
+    mode: 'auto',
+  }),
+  prompt: Object.freeze({
+    prepend: '',
+    append: '',
+    coreOverride: '',
+  }),
+});
+
+function normalizeBoolean(value, fallback) {
+  if (typeof value === 'boolean') return value;
+  if (typeof value === 'string') {
+    const normalized = value.trim().toLowerCase();
+    if (['true', '1', 'yes', 'on'].includes(normalized)) return true;
+    if (['false', '0', 'no', 'off'].includes(normalized)) return false;
+  }
+  return fallback;
+}
+
+function normalizeContextLimit(value) {
+  const parsed = Number(value);
+  return Number.isFinite(parsed) && parsed > 0 ? Math.round(parsed) : null;
+}
+
+function normalizeSummarizeTriggerPercent(value) {
+  let parsed = Number(value);
+  if (!Number.isFinite(parsed)) return DEFAULT_CONFIG.summarizeTriggerPercent;
+  if (parsed > 0 && parsed <= 1) parsed *= 100;
+  return Math.max(40, Math.min(90, Math.round(parsed)));
+}
+
+function normalizeToolRoundLimit(value) {
+  return normalizeIntegerInRange(value, DEFAULT_CONFIG.toolRoundLimit, 1, 200);
+}
+
+function normalizeThinkingMode(value) {
+  if (typeof value === 'boolean') return value ? 'on' : 'off';
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (['on', 'true', '1', 'yes', 'enable', 'enabled', 'always'].includes(normalized)) return 'on';
+  if (['off', 'false', '0', 'no', 'disable', 'disabled', 'never'].includes(normalized)) return 'off';
+  return 'auto';
+}
+
+function normalizeShellBackgroundMode(value) {
+  if (typeof value === 'boolean') return value ? 'on' : 'off';
+  const normalized = String(value ?? '').trim().toLowerCase();
+  if (['on', 'true', '1', 'yes', 'enable', 'enabled', 'always'].includes(normalized)) return 'on';
+  if (['off', 'false', '0', 'no', 'disable', 'disabled', 'never'].includes(normalized)) return 'off';
+  return 'auto';
+}
+
+function normalizeThinkingConfig(thinkingConfig = {}) {
+  if (typeof thinkingConfig === 'boolean' || typeof thinkingConfig === 'string') {
+    return { mode: normalizeThinkingMode(thinkingConfig) };
+  }
+
+  if (!thinkingConfig || typeof thinkingConfig !== 'object' || Array.isArray(thinkingConfig)) {
+    return { ...DEFAULT_CONFIG.thinking };
+  }
+
+  return {
+    mode: normalizeThinkingMode(thinkingConfig.mode),
+  };
+}
+
+function normalizeShellConfig(shellConfig = {}) {
+  if (typeof shellConfig === 'boolean' || typeof shellConfig === 'string') {
+    return {
+      ...DEFAULT_CONFIG.shell,
+      backgroundMode: normalizeShellBackgroundMode(shellConfig),
+    };
+  }
+
+  if (!shellConfig || typeof shellConfig !== 'object' || Array.isArray(shellConfig)) {
+    return { ...DEFAULT_CONFIG.shell };
+  }
+
+  return {
+    streamToModel: normalizeBoolean(shellConfig.streamToModel, DEFAULT_CONFIG.shell.streamToModel),
+    backgroundMode: normalizeShellBackgroundMode(shellConfig.backgroundMode),
+    backgroundAfterSeconds: normalizeIntegerInRange(shellConfig.backgroundAfterSeconds, DEFAULT_CONFIG.shell.backgroundAfterSeconds, 2, 120),
+    outputChunkChars: normalizeIntegerInRange(shellConfig.outputChunkChars, DEFAULT_CONFIG.shell.outputChunkChars, 400, 12000),
+  };
+}
+
+function normalizeIntegerInRange(value, fallback, min, max) {
+  const parsed = Number(value);
+  if (!Number.isFinite(parsed)) return fallback;
+  return Math.max(min, Math.min(max, Math.round(parsed)));
+}
+
+function normalizeStreamingConfig(streamingConfig = {}) {
+  if (typeof streamingConfig === 'boolean') {
+    return {
+      ...DEFAULT_CONFIG.streaming,
+      showPhaseStatus: streamingConfig,
+      showHeartbeat: streamingConfig,
+    };
+  }
+
+  if (!streamingConfig || typeof streamingConfig !== 'object' || Array.isArray(streamingConfig)) {
+    return { ...DEFAULT_CONFIG.streaming };
+  }
+
+  return {
+    showPhaseStatus: normalizeBoolean(streamingConfig.showPhaseStatus, DEFAULT_CONFIG.streaming.showPhaseStatus),
+    showHeartbeat: normalizeBoolean(streamingConfig.showHeartbeat, DEFAULT_CONFIG.streaming.showHeartbeat),
+    idleNoticeSeconds: normalizeIntegerInRange(streamingConfig.idleNoticeSeconds, DEFAULT_CONFIG.streaming.idleNoticeSeconds, 2, 60),
+  };
+}
+
+function normalizePromptText(value) {
+  if (typeof value === 'string') return value;
+  if (value === null || value === undefined) return '';
+  return String(value);
+}
+
+function normalizePromptConfig(promptConfig = {}) {
+  if (!promptConfig || typeof promptConfig !== 'object' || Array.isArray(promptConfig)) {
+    return {
+      ...DEFAULT_CONFIG.prompt,
+      append: normalizePromptText(promptConfig),
+    };
+  }
+
+  const coreOverride = promptConfig.coreOverride !== undefined
+    ? promptConfig.coreOverride
+    : promptConfig.override;
+
+  return {
+    prepend: normalizePromptText(promptConfig.prepend),
+    append: normalizePromptText(promptConfig.append),
+    coreOverride: normalizePromptText(coreOverride),
+  };
+}
+
+function normalizeConfig(config = {}) {
+  return {
+    ...config,
+    defaultModel: typeof config.defaultModel === 'string' && config.defaultModel.trim() ? config.defaultModel.trim() : null,
+    defaultAgent: typeof config.defaultAgent === 'string' && config.defaultAgent.trim() ? config.defaultAgent.trim() : null,
+    autoAttach: normalizeBoolean(config.autoAttach, DEFAULT_CONFIG.autoAttach),
+    debug: normalizeBoolean(config.debug, DEFAULT_CONFIG.debug),
+    contextLimit: normalizeContextLimit(config.contextLimit),
+    toolRoundLimit: normalizeToolRoundLimit(config.toolRoundLimit),
+    patchRetries: normalizeIntegerInRange(config.patchRetries, DEFAULT_CONFIG.patchRetries, 1, 20),
+    maxFileSize: normalizeIntegerInRange(config.maxFileSize, DEFAULT_CONFIG.maxFileSize, 10000, 10000000),
+    maxScanSize: normalizeIntegerInRange(config.maxScanSize, DEFAULT_CONFIG.maxScanSize, 100000, 50000000),
+    maxUrlSize: normalizeIntegerInRange(config.maxUrlSize, DEFAULT_CONFIG.maxUrlSize, 10000, 10000000),
+    summaryPhases: normalizeBoolean(config.summaryPhases, DEFAULT_CONFIG.summaryPhases),
+    summarizeTriggerPercent: normalizeSummarizeTriggerPercent(config.summarizeTriggerPercent),
+    shell: normalizeShellConfig(config.shell),
+    streaming: normalizeStreamingConfig(config.streaming),
+    thinking: normalizeThinkingConfig(config.thinking),
+    prompt: normalizePromptConfig(config.prompt),
+  };
+}
+
+// Load config (settings like autoAttach and context summarization)
 function loadConfig() {
   try {
     ensureSapperDir();
     if (fs.existsSync(CONFIG_FILE)) {
-      return JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+      const rawConfig = JSON.parse(fs.readFileSync(CONFIG_FILE, 'utf8'));
+      const normalizedConfig = normalizeConfig(rawConfig);
+      if (JSON.stringify(rawConfig) !== JSON.stringify(normalizedConfig)) {
+        fs.writeFileSync(CONFIG_FILE, JSON.stringify(normalizedConfig, null, 2));
+      }
+      return normalizedConfig;
+    }
+  } catch (e) {}
+
+  const defaultConfig = normalizeConfig();
+  try {
+    ensureSapperDir();
+    if (!fs.existsSync(CONFIG_FILE)) {
+      fs.writeFileSync(CONFIG_FILE, JSON.stringify(defaultConfig, null, 2));
     }
   } catch (e) {}
-  return { autoAttach: true, contextLimit: null }; // Default: auto-attach ON, no custom context limit
+  return defaultConfig;
 }
 
 function saveConfig(config) {
   ensureSapperDir();
-  fs.writeFileSync(CONFIG_FILE, JSON.stringify(config, null, 2));
+  const normalizedConfig = normalizeConfig(config);
+  fs.writeFileSync(CONFIG_FILE, JSON.stringify(normalizedConfig, null, 2));
+  sapperConfig = normalizedConfig;
 }
 
 // Global config
@@ -929,6 +1331,264 @@ function effectiveContextLength() {
   return modelContextLength;
 }
 
+const SUMMARY_PHASES = [
+  'Prepare summary request',
+  'Summarize older messages',
+  'Save compressed context',
+  'Resume your prompt',
+];
+
+function summaryPhasesEnabled() {
+  return sapperConfig.summaryPhases !== false;
+}
+
+function toolRoundLimit() {
+  return normalizeToolRoundLimit(sapperConfig.toolRoundLimit);
+}
+
+function getShellConfig() {
+  return normalizeShellConfig(sapperConfig.shell);
+}
+
+function shellStreamToModelEnabled() {
+  return getShellConfig().streamToModel;
+}
+
+function shellBackgroundMode() {
+  return getShellConfig().backgroundMode;
+}
+
+function shellBackgroundAfterSeconds() {
+  return getShellConfig().backgroundAfterSeconds;
+}
+
+function shellOutputChunkChars() {
+  return getShellConfig().outputChunkChars;
+}
+
+function summaryTriggerPercent() {
+  return normalizeSummarizeTriggerPercent(sapperConfig.summarizeTriggerPercent);
+}
+
+function summaryTokenThreshold(ctxLen) {
+  return ctxLen ? Math.floor(ctxLen * (summaryTriggerPercent() / 100)) : 8000;
+}
+
+function parseSummaryTriggerInput(value) {
+  if (value === undefined || value === null) return null;
+  const normalized = String(value).trim().replace(/%$/, '');
+  if (!normalized) return null;
+
+  let parsed = Number(normalized);
+  if (!Number.isFinite(parsed)) return null;
+  if (parsed > 0 && parsed <= 1) parsed *= 100;
+
+  return Math.max(40, Math.min(90, Math.round(parsed)));
+}
+
+function summaryPhaseText(stepNumber, detail = '') {
+  const fallback = SUMMARY_PHASES[stepNumber - 1] || 'Context summarization';
+  if (!summaryPhasesEnabled()) {
+    return detail || fallback;
+  }
+  return detail
+    ? `Step ${stepNumber}/${SUMMARY_PHASES.length} ${detail}`
+    : `Step ${stepNumber}/${SUMMARY_PHASES.length} ${fallback}`;
+}
+
+function renderSummaryPhaseList(activeStep = null) {
+  return SUMMARY_PHASES
+    .map((label, index) => {
+      const stepNumber = index + 1;
+      const line = `Step ${stepNumber}/${SUMMARY_PHASES.length} ${label}`;
+      return activeStep === stepNumber ? chalk.cyan(line) : UI.slate(line);
+    })
+    .join('\n');
+}
+
+function getPromptConfig() {
+  return normalizePromptConfig(sapperConfig.prompt);
+}
+
+function getThinkingConfig() {
+  return normalizeThinkingConfig(sapperConfig.thinking);
+}
+
+function getStreamingConfig() {
+  return normalizeStreamingConfig(sapperConfig.streaming);
+}
+
+function streamPhaseStatusEnabled() {
+  return getStreamingConfig().showPhaseStatus;
+}
+
+function streamHeartbeatEnabled() {
+  return getStreamingConfig().showHeartbeat;
+}
+
+function streamIdleNoticeSeconds() {
+  return getStreamingConfig().idleNoticeSeconds;
+}
+
+function thinkingMode() {
+  return getThinkingConfig().mode;
+}
+
+function normalizeThinkingInput(input = '') {
+  let normalized = String(input ?? '').trim();
+  if (normalized.startsWith('/') && normalized.includes(' ')) {
+    normalized = normalized.substring(normalized.indexOf(' ') + 1).trim();
+  }
+  return normalized;
+}
+
+function isSimplePrompt(input = '') {
+  const normalized = normalizeThinkingInput(input).toLowerCase();
+  if (!normalized) return true;
+  if (normalized.includes('\n')) return false;
+  if (/@|https?:\/\//.test(normalized)) return false;
+  if (/[`{}[\]();<>]/.test(normalized)) return false;
+  if (/^(hi|hello|hey|thanks|thank you|ok|okay|continue|go on|proceed|yes|no|y|n|cool|nice|bye|good morning|good evening)$/.test(normalized)) {
+    return true;
+  }
+  if (/\b(analyze|debug|fix|implement|refactor|design|plan|optimi[sz]e|architect|investigate|review|build|create|generate|search|find|error|bug|test|compare|explain deeply)\b/.test(normalized)) {
+    return false;
+  }
+  if (normalized.length <= 32) return true;
+  return normalized.length <= 60 && normalized.split(/\s+/).length <= 8;
+}
+
+function shouldUseThinkingForInput(input = '') {
+  const mode = thinkingMode();
+  if (mode === 'on') return true;
+  if (mode === 'off') return false;
+  return !isSimplePrompt(input);
+}
+
+function isLikelyLongRunningCommand(command = '') {
+  const normalized = String(command ?? '').trim().toLowerCase();
+  if (!normalized) return false;
+
+  const patterns = [
+    /\buvicorn\b/,
+    /\bnpm\s+run\s+(dev|start|watch)\b/,
+    /\bpnpm\s+(dev|start|watch)\b/,
+    /\byarn\s+(dev|start|watch)\b/,
+    /\bnext\s+dev\b/,
+    /\bvite\b/,
+    /\bnodemon\b/,
+    /\bdocker\s+compose\s+up\b/,
+    /\bwebpack(?:\s+serve|\s+--watch)?\b/,
+    /\bpython\s+-m\s+http\.server\b/,
+    /\btail\s+-f\b/,
+    /\bserve\b/,
+    /--reload\b/,
+    /--watch\b/
+  ];
+
+  return patterns.some(pattern => pattern.test(normalized));
+}
+
+function shouldBackgroundShellCommand(command = '') {
+  const mode = shellBackgroundMode();
+  if (mode === 'off') return false;
+  if (mode === 'on') return true;
+  return isLikelyLongRunningCommand(command);
+}
+
+function hasCustomPromptConfig() {
+  const promptConfig = getPromptConfig();
+  return Boolean(promptConfig.prepend.trim() || promptConfig.append.trim() || promptConfig.coreOverride.trim());
+}
+
+function wrapPromptCustomizationBlock(title, content, leadingNewline = true) {
+  const normalized = String(content ?? '').trim();
+  if (!normalized) return '';
+  const prefix = leadingNewline ? '\n\n' : '';
+  return `${prefix}═══ ${title} ═══\n${normalized}\n═══ END ${title} ═══`;
+}
+
+function resolveLoadedSkillContents() {
+  const allSkills = loadSkills();
+  return loadedSkills.map(skillName => allSkills[skillName]?.content || '').filter(Boolean);
+}
+
+function resolveActiveAgentContent() {
+  if (!currentAgent) return null;
+  const allAgents = loadAgents();
+  return allAgents[currentAgent]?.content || null;
+}
+
+function getActiveAgentMeta() {
+  if (!currentAgent) return null;
+  const allAgents = loadAgents();
+  const agent = allAgents[currentAgent];
+  return {
+    key: currentAgent,
+    name: agent?.name || currentAgent,
+    description: agent?.description || '',
+    tools: agent?.tools || currentAgentTools,
+  };
+}
+
+function getLoadedSkillMetaList() {
+  const allSkills = loadSkills();
+  return loadedSkills.map(skillName => {
+    const skill = allSkills[skillName];
+    return {
+      key: skillName,
+      name: skill?.name || skillName,
+      description: skill?.description || '',
+    };
+  });
+}
+
+function summarizeModeNames(names = [], maxVisible = 3) {
+  const normalized = names.map(name => String(name ?? '').trim()).filter(Boolean);
+  if (normalized.length === 0) return '';
+  if (normalized.length <= maxVisible) return normalized.join(', ');
+  return `${normalized.slice(0, maxVisible).join(', ')}, +${normalized.length - maxVisible} more`;
+}
+
+function activeModeSummary({ includeAgent = true, maxSkills = 3 } = {}) {
+  const parts = [];
+  const activeAgent = getActiveAgentMeta();
+  const activeSkills = getLoadedSkillMetaList();
+
+  if (includeAgent && activeAgent) {
+    const agentName = activeAgent.name || currentAgent;
+    const agentSuffix = currentAgent && agentName !== currentAgent ? ` (/${currentAgent})` : currentAgent ? ` /${currentAgent}` : '';
+    parts.push(`agent ${agentName}${agentSuffix}`);
+  }
+
+  if (activeSkills.length > 0) {
+    parts.push(`skills ${summarizeModeNames(activeSkills.map(skill => skill.name || skill.key), maxSkills)}`);
+  }
+
+  return parts.join(' · ');
+}
+
+function activeAgentPromptBadge() {
+  const activeAgent = getActiveAgentMeta();
+  if (!activeAgent) return statusBadge('default', 'neutral');
+  return statusBadge(`agent:${ellipsis(activeAgent.name || currentAgent, 20)}`, 'info');
+}
+
+function activeSkillsPromptBadge() {
+  const activeSkills = getLoadedSkillMetaList();
+  if (activeSkills.length === 0) return null;
+  const prefix = activeSkills.length === 1 ? 'skill:' : 'skills:';
+  return statusBadge(`${prefix}${ellipsis(summarizeModeNames(activeSkills.map(skill => skill.name || skill.key), 2), 22)}`, 'success');
+}
+
+function refreshSystemPrompt(messages) {
+  if (!Array.isArray(messages) || messages.length === 0) return;
+  messages[0] = {
+    role: 'system',
+    content: buildSystemPrompt(resolveActiveAgentContent(), resolveLoadedSkillContents())
+  };
+}
+
 // ═══════════════════════════════════════════════════════════════
 // WORKSPACE GRAPH - Track file relationships and summaries
 // ═══════════════════════════════════════════════════════════════
@@ -1048,7 +1708,7 @@ async function buildWorkspaceGraph(showProgress = true) {
           
           try {
             const stats = fs.statSync(fullPath);
-            if (stats.size > MAX_FILE_SIZE) continue;
+            if (stats.size > getMaxFileSize()) continue;
             
             const content = fs.readFileSync(fullPath, 'utf8');
             const deps = extractDependencies(content, fullPath);
@@ -1130,12 +1790,12 @@ function formatWorkspaceSummary(workspace) {
   
   for (const [dir, files] of Object.entries(byDir)) {
     output += `📁 ${dir}/\n`;
-    for (const f of files.slice(0, 10)) { // Limit per directory
+    for (const f of files.slice(0, LIMITS.WORKSPACE_FILES_PER_DIR)) { // Limit per directory
       const name = f.path.split('/').pop();
       const exportList = f.exports?.length ? ` [${f.exports.slice(0, 3).join(', ')}${f.exports.length > 3 ? '...' : ''}]` : '';
       output += `   📄 ${name}${exportList}\n`;
     }
-    if (files.length > 10) output += `   ... and ${files.length - 10} more\n`;
+    if (files.length > LIMITS.WORKSPACE_FILES_PER_DIR) output += `   ... and ${files.length - LIMITS.WORKSPACE_FILES_PER_DIR} more\n`;
     output += '\n';
   }
   
@@ -1446,13 +2106,13 @@ async function addToEmbeddings(text, embeddings) {
   const embedding = await getEmbedding(text);
   if (embedding) {
     embeddings.chunks.push({
-      text: text.substring(0, 2000), // Limit stored text
+      text: text.substring(0, LIMITS.EMBEDDINGS_MAX_TEXT), // Limit stored text
       embedding,
       timestamp: Date.now()
     });
-    // Keep only last 100 chunks
-    if (embeddings.chunks.length > 100) {
-      embeddings.chunks = embeddings.chunks.slice(-100);
+    // Keep only last N chunks
+    if (embeddings.chunks.length > LIMITS.EMBEDDINGS_MAX_CHUNKS) {
+      embeddings.chunks = embeddings.chunks.slice(-LIMITS.EMBEDDINGS_MAX_CHUNKS);
     }
     saveEmbeddings(embeddings);
   }
@@ -1462,37 +2122,76 @@ async function addToEmbeddings(text, embeddings) {
 // SMART CONTEXT SUMMARIZATION
 // ═══════════════════════════════════════════════════════════════
 
-async function autoSummarizeContext(messages, model, force = false) {
-  // Use real token-based threshold if we know the model's context length
+// Check whether context is large enough to need summarization
+function needsSummarize(messages) {
   const estimatedTokens = estimateMessagesTokens(messages);
   const contextSize = JSON.stringify(messages).length;
-  
-  // Summarize when we hit 75% of effective context window (leave room for response)
   const ctxLen = effectiveContextLength();
-  const tokenThreshold = ctxLen ? Math.floor(ctxLen * 0.75) : 8000;
-  // Also keep the old byte-based check as a fallback
+  const tokenThreshold = summaryTokenThreshold(ctxLen);
   const shouldSummarize = (ctxLen && estimatedTokens > tokenThreshold) || 
-                          (!ctxLen && contextSize > 32000);
+                          (!ctxLen && contextSize > LIMITS.CONTEXT_BYTE_FALLBACK);
+  return { shouldSummarize, estimatedTokens, contextSize, ctxLen, tokenThreshold };
+}
+
+// Save old messages into the embedding store for later recall
+async function saveOldMessagesToEmbeddings(oldMessages) {
+  const embeddings = loadEmbeddings();
+  const textToEmbed = oldMessages
+    .filter(m => m.role !== 'system')
+    .map(m => m.content.substring(0, LIMITS.LOG_PREVIEW_CHARS))
+    .join('\n---\n');
+
+  if (textToEmbed.length > LIMITS.EMBEDDING_MIN_TEXT) {
+    try {
+      const embedding = await getEmbedding(textToEmbed);
+      if (embedding) {
+        embeddings.chunks.push({
+          text: textToEmbed.substring(0, LIMITS.EMBEDDINGS_MAX_TEXT),
+          embedding,
+          timestamp: Date.now()
+        });
+        if (embeddings.chunks.length > LIMITS.EMBEDDINGS_MAX_CHUNKS) {
+          embeddings.chunks = embeddings.chunks.slice(-LIMITS.EMBEDDINGS_MAX_CHUNKS);
+        }
+        saveEmbeddings(embeddings);
+      }
+    } catch (e) {
+      // Silently skip embedding if model not available
+    }
+  }
+  return embeddings;
+}
+
+async function autoSummarizeContext(messages, model, force = false) {
+  const { shouldSummarize, estimatedTokens, contextSize, ctxLen, tokenThreshold } = needsSummarize(messages);
   
   if ((!force && !shouldSummarize) || messages.length <= 5) return messages;
 
   const usagePercent = ctxLen 
     ? Math.round((estimatedTokens / ctxLen) * 100)
-    : Math.round((contextSize / 32000) * 100);
+    : Math.round((contextSize / LIMITS.CONTEXT_BYTE_FALLBACK) * 100);
 
   console.log();
-  console.log(box(
-    `Context: ~${chalk.red.bold(estimatedTokens.toLocaleString())} tokens / ${chalk.white(ctxLen ? ctxLen.toLocaleString() : '?')} max (${chalk.red.bold(usagePercent + '%')})\n` +
-    `${chalk.gray(`${messages.length} messages, ${Math.round(contextSize / 1024)}KB raw`)}\n` +
-    `${chalk.cyan('Auto-summarizing to stay within context window...')}`,
-    '🧠 Context Window Management', 'cyan'
-  ));
+  const summaryIntroLines = [
+    `Context: ~${chalk.red.bold(estimatedTokens.toLocaleString())} tokens / ${chalk.white(ctxLen ? ctxLen.toLocaleString() : '?')} max (${chalk.red.bold(usagePercent + '%')})`,
+    chalk.gray(`${messages.length} messages, ${Math.round(contextSize / 1024)}KB raw`),
+    chalk.cyan('Auto-summarizing to stay within context window before answering your prompt...'),
+    chalk.gray(`Trigger: ${summaryTriggerPercent()}% of the active context window (${tokenThreshold.toLocaleString()} tokens)`),
+    chalk.gray('This is an extra model call, so large contexts can pause here for a while.'),
+  ];
+  if (summaryPhasesEnabled()) {
+    summaryIntroLines.push('');
+    summaryIntroLines.push(renderSummaryPhaseList(1));
+  }
+  console.log(box(summaryIntroLines.join('\n'), '🧠 Context Window Management', 'cyan'));
 
-  const summarySpinner = ora('Summarizing conversation...').start();
+  const summaryStart = Date.now();
+  const elapsedSummaryTime = () => `${Math.max(0, Math.round((Date.now() - summaryStart) / 1000))}s`;
+  const summarySpinner = ora(summaryPhaseText(1, 'Preparing summary request...')).start();
 
   // Separate: system prompt, messages to summarize, recent messages to keep
   const systemPrompt = messages[0];
-  const recentCount = 4;
+  const recentCount = LIMITS.SUMMARY_RECENT_MSGS;
   let recentMessages = messages.slice(-recentCount);
   let oldMessages = messages.slice(1, -recentCount);
 
@@ -1535,33 +2234,45 @@ async function autoSummarizeContext(messages, model, force = false) {
     .map(m => {
       const role = m.role === 'user' ? 'User' : 'Assistant';
       // Truncate very long messages (file contents, scan results, etc.)
-      const text = m.content.length > 1500
-        ? m.content.substring(0, 1500) + '\n... [truncated]'
+      const text = m.content.length > LIMITS.MSG_TRUNCATION_CHARS
+        ? m.content.substring(0, LIMITS.MSG_TRUNCATION_CHARS) + '\n... [truncated]'
         : m.content;
       return `${role}: ${text}`;
     })
     .join('\n\n');
 
+  const conversationTokens = estimateTokens(conversationText);
+  const conversationBytes = Buffer.byteLength(conversationText, 'utf8');
+  summarySpinner.text = summaryPhaseText(1, `Preparing summary request from ${oldMessages.length} older messages (~${conversationTokens.toLocaleString()} tokens, ${formatBytes(conversationBytes)})`);
+  let spinnerInterval = null;
+
   try {
-    const summaryResponse = await ollama.chat({
-      model,
-      ...(effectiveContextLength() ? { options: { num_ctx: effectiveContextLength() } } : {}),
-      messages: [
-        {
-          role: 'system',
-          content: `You are a conversation summarizer for an AI coding agent called Sapper. Produce a concise but thorough summary of the conversation below. Include:
+    const summaryInstruction = `You are a conversation summarizer for an AI coding agent called Sapper. Produce a concise but thorough summary of the conversation below. Include:
 - Key topics discussed and decisions made
 - Files that were read, created, or modified (with paths)
 - Important code changes or bugs found
 - Any pending tasks or open questions
 - Technical details that would be needed to continue the conversation
-- Which tools were used (LIST, READ, WRITE, PATCH, SHELL, SEARCH) and on what files
+- Which tools were used (LIST, READ, WRITE, PATCH, SHELL, SEARCH, CHANGES, FETCH, MEMORY, OPEN) and on what files or URLs
 - The active agent role (if any) and loaded skills
 - Any tool usage patterns or workflows that were established
 
 CRITICAL: The AI assistant uses tools with syntax like [TOOL:READ]path[/TOOL]. Make sure to note which tools were used so the assistant remembers to keep using them after this summary.
 
-Output ONLY the summary, no preamble. Keep it under 800 words. Use bullet points.`
+Output ONLY the summary, no preamble. Keep it under 800 words. Use bullet points.`;
+    const summaryInputTokens = estimateTokens(summaryInstruction) + estimateTokens(`Summarize this conversation:\n\n${conversationText}`);
+    summarySpinner.text = summaryPhaseText(2, `Waiting for ${model} to summarize (~${summaryInputTokens.toLocaleString()} tokens, ${elapsedSummaryTime()} elapsed)`);
+    spinnerInterval = setInterval(() => {
+      summarySpinner.text = summaryPhaseText(2, `Waiting for ${model} to summarize (~${summaryInputTokens.toLocaleString()} tokens, ${elapsedSummaryTime()} elapsed)`);
+    }, 1000);
+
+    const summaryResponse = await ollama.chat({
+      model,
+      ...(effectiveContextLength() ? { options: { num_ctx: effectiveContextLength() } } : {}),
+      messages: [
+        {
+          role: 'system',
+          content: summaryInstruction
         },
         {
           role: 'user',
@@ -1570,34 +2281,14 @@ Output ONLY the summary, no preamble. Keep it under 800 words. Use bullet points
       ],
       stream: false
     });
+    clearInterval(spinnerInterval);
+    spinnerInterval = null;
 
     const summary = summaryResponse.message.content;
 
     // Save old messages to embeddings before discarding
-    const embeddings = loadEmbeddings();
-    const textToEmbed = oldMessages
-      .filter(m => m.role !== 'system')
-      .map(m => m.content.substring(0, 500))
-      .join('\n---\n');
-
-    if (textToEmbed.length > 50) {
-      try {
-        const embedding = await getEmbedding(textToEmbed);
-        if (embedding) {
-          embeddings.chunks.push({
-            text: textToEmbed.substring(0, 2000),
-            embedding,
-            timestamp: Date.now()
-          });
-          if (embeddings.chunks.length > 100) {
-            embeddings.chunks = embeddings.chunks.slice(-100);
-          }
-          saveEmbeddings(embeddings);
-        }
-      } catch (e) {
-        // Silently skip embedding if model not available
-      }
-    }
+    summarySpinner.text = summaryPhaseText(3, `Saving compressed context and memory (${elapsedSummaryTime()} elapsed)`);
+    const embeddings = await saveOldMessagesToEmbeddings(oldMessages);
 
     // Build agent role reminder if an agent is active
     const agentReminder = currentAgent ? `\nNote: You are currently operating as the "${currentAgent}" agent. Stay in character.` : '';
@@ -1608,13 +2299,13 @@ Output ONLY the summary, no preamble. Keep it under 800 words. Use bullet points
       systemPrompt,
       {
         role: 'user',
-        content: `[CONVERSATION SUMMARY - auto-generated]\n${summary}\n[END SUMMARY]\n\nUse this summary as context for our ongoing conversation. Continue using your tools (LIST, READ, WRITE, PATCH, SHELL, SEARCH) as needed.${agentReminder}${skillReminder}`
+        content: `[CONVERSATION SUMMARY - auto-generated]\n${summary}\n[END SUMMARY]\n\nUse this summary as context for our ongoing conversation. Continue using your tools (LIST, READ, WRITE, PATCH, SHELL, SEARCH, CHANGES, FETCH, MEMORY, OPEN) as needed.${agentReminder}${skillReminder}`
       },
       {
         role: 'assistant',
         content: _useNativeToolsFlag
-          ? `Understood. I have the conversation summary and will continue helping you. I'll use my tools (list_directory, read_file, write_file, patch_file, search_files, run_shell) as needed.\n\nWhat would you like me to do next?`
-          : `Understood. I have the conversation summary and will continue helping you. I'll keep using my tools to explore files, make changes, and run commands as needed:\n- [TOOL:LIST] to browse directories\n- [TOOL:READ] to read files\n- [TOOL:WRITE] to create/overwrite files\n- [TOOL:PATCH] to edit existing files\n- [TOOL:SEARCH] to find patterns\n- [TOOL:SHELL] to run commands\n\nWhat would you like me to do next?`
+          ? `Understood. I have the conversation summary and will continue helping you. I'll use my tools (list_directory, read_file, write_file, patch_file, search_files, changes, fetch_web, recall_memory, open_url, run_shell) as needed.\n\nWhat would you like me to do next?`
+          : `Understood. I have the conversation summary and will continue helping you. I'll keep using my tools to explore files, inspect changes, fetch references, recall memory, open URLs when needed, make edits, and run commands as needed:\n- [TOOL:LIST] to browse directories\n- [TOOL:READ] to read files\n- [TOOL:WRITE] to create/overwrite files\n- [TOOL:PATCH] to edit existing files\n- [TOOL:SEARCH] to find patterns\n- [TOOL:CHANGES] to inspect git changes\n- [TOOL:FETCH] to read web pages\n- [TOOL:MEMORY] to search saved memory\n- [TOOL:OPEN] to open URLs with approval\n- [TOOL:SHELL] to run commands\n\nWhat would you like me to do next?`
       },
       ...recentMessages
     ];
@@ -1626,10 +2317,16 @@ Output ONLY the summary, no preamble. Keep it under 800 words. Use bullet points
     const newSize = JSON.stringify(newMessages).length;
     const newTokens = estimateMessagesTokens(newMessages);
     summarySpinner.stop();
+    if (summaryPhasesEnabled()) {
+      console.log(chalk.gray(`   ${summaryPhaseText(4, 'Context ready. Returning to chat...')}`));
+    }
     console.log(chalk.green(`✅ Summarized! ~${chalk.white(estimatedTokens.toLocaleString())} → ~${chalk.white(newTokens.toLocaleString())} tokens (${messages.length} → ${newMessages.length} messages)`));
     if (ctxLen) {
       const newPercent = Math.round((newTokens / ctxLen) * 100);
       console.log(chalk.gray(`   📊 Context window usage: ${newPercent}% of ${ctxLen.toLocaleString()} tokens`));
+      if (newPercent >= 80) {
+        console.log(chalk.yellow('   ⚠️  Context is still dense, so the next reply may still be slower than usual.'));
+      }
     }
     if (embeddings.chunks.length > 0) {
       console.log(chalk.gray(`   🧠 Old context saved to memory (${embeddings.chunks.length} memories)`));
@@ -1642,6 +2339,7 @@ Output ONLY the summary, no preamble. Keep it under 800 words. Use bullet points
 
     return newMessages;
   } catch (e) {
+    if (spinnerInterval) clearInterval(spinnerInterval);
     summarySpinner.stop();
     console.log(chalk.yellow(`⚠️  Auto-summary failed: ${e.message}`));
     console.log(chalk.gray('   Tip: Use /prune to manually reduce context.\n'));
@@ -1769,6 +2467,22 @@ function commandRow(command, description, width = 18) {
   return `${padAnsi(UI.accent(command), width)} ${UI.slate('—')} ${UI.ink(description)}`;
 }
 
+function renderViewport(content, { verticalAlign = 'top', minTopPadding = 0 } = {}) {
+  const text = String(content ?? '').replace(/\n+$/, '');
+  const rows = Math.max(12, process.stdout.rows || 24);
+  const lineCount = text ? text.split('\n').length : 0;
+  const centeredPadding = verticalAlign === 'center'
+    ? Math.max(0, Math.floor((rows - lineCount) / 2))
+    : 0;
+  const topPadding = Math.max(minTopPadding, centeredPadding);
+
+  console.clear();
+  if (topPadding > 0) {
+    process.stdout.write('\n'.repeat(topPadding));
+  }
+  process.stdout.write(`${text}\n`);
+}
+
 function meter(current = 0, total = 0, width = 20) {
   if (!total || total <= 0) return UI.slate('░'.repeat(width));
 
@@ -1788,7 +2502,54 @@ function promptShell(label, detail = '') {
   return `${UI.slate(label)}${detail ? `\n${detail}` : ''}\n${UI.accent('› ')} `;
 }
 
-function confirmPrompt(label, type = 'warning') {
+function renderedTerminalLineCount(text = '', width = process.stdout.columns || 80) {
+  const terminalColumns = Math.max(1, width || 80);
+  return String(text ?? '')
+    .split('\n')
+    .reduce((count, line) => count + Math.max(1, Math.ceil(Math.max(1, visibleLength(line)) / terminalColumns)), 0);
+}
+
+function clearPromptEcho(promptText, inputText = '') {
+  const totalLines = renderedTerminalLineCount(`${promptText}${inputText}`);
+  for (let index = 0; index < totalLines; index++) {
+    process.stdout.write('\x1B[1A\x1B[2K');
+  }
+  process.stdout.write('\r');
+}
+
+function streamPhaseMessage(message, type = 'neutral') {
+  const colorFn = BADGE_STYLES[type] || UI.slate;
+  return `${colorFn('[status]')} ${UI.slate(message)}`;
+}
+
+function showStreamPhase(message, type = 'neutral') {
+  if (!streamPhaseStatusEnabled()) return;
+  console.log(streamPhaseMessage(message, type));
+}
+
+function renderStreamingHeartbeat({
+  genTokenCount = 0,
+  genStartTime,
+  lastVisibleActivityAt,
+  stage = 'generating',
+}) {
+  const elapsedSeconds = Math.max((Date.now() - genStartTime) / 1000, 0.1);
+  const elapsed = elapsedSeconds.toFixed(1);
+  const idleSeconds = Math.max(0, Math.floor((Date.now() - lastVisibleActivityAt) / 1000));
+  const idleThreshold = streamIdleNoticeSeconds();
+
+  if (stage === 'waiting-first') {
+    const waitNote = idleSeconds >= idleThreshold ? ` · waiting ${idleSeconds}s` : '';
+    process.stdout.write(`\r  ${UI.slate(`Waiting for first model chunk... ${elapsed}s elapsed${waitNote}`)}  ${UI.slate.italic('Ctrl+C to stop')}`);
+    return;
+  }
+
+  const tps = genTokenCount / elapsedSeconds;
+  const waitNote = idleSeconds >= idleThreshold ? ` · waiting ${idleSeconds}s for next chunk` : '';
+  process.stdout.write(`\r  ${UI.slate(`Generating... ${genTokenCount} tokens · ${elapsed}s · ${tps.toFixed(1)} t/s${waitNote}`)}  ${UI.slate.italic('Ctrl+C to stop')}`);
+}
+
+function confirmPrompt(label, type = 'warning', optionsLabel = '[y/N] ') {
   const colors = {
     info: UI.accent,
     success: UI.mint,
@@ -1798,16 +2559,273 @@ function confirmPrompt(label, type = 'warning') {
     neutral: UI.slate,
   };
   const colorFn = colors[type] || UI.gold;
-  return colorFn(`\n${label}? `) + UI.slate('[y/N] ');
+  return colorFn(`\n${label}? `) + UI.slate(optionsLabel);
 }
 
-// Configure marked with terminal renderer
-marked.use(markedTerminal({
-    code: chalk.cyan,
-    blockquote: chalk.gray.italic,
-    html: chalk.gray,
-    heading: chalk.bold.cyan,
-    firstHeading: chalk.bold.cyan,
+function parseApprovalShortcut(input = '') {
+  const trimmed = String(input ?? '').trim();
+  if (!trimmed) return null;
+
+  const match = trimmed.match(/^(f|feedback|e|edit)\b(?:\s*[:=-]?\s*(.*))?$/i);
+  if (!match) return null;
+
+  const command = match[1].toLowerCase();
+  return {
+    type: command.startsWith('e') ? 'edit' : 'feedback',
+    detail: String(match[2] ?? '').trim(),
+  };
+}
+
+async function resolveApprovalInstruction(input, {
+  feedbackPrompt = 'Feedback for Sapper: ',
+  editPrompt = 'Edit instruction for Sapper: ',
+} = {}) {
+  const shortcut = parseApprovalShortcut(input);
+  if (!shortcut) return null;
+
+  let detail = shortcut.detail;
+  if (!detail) {
+    const promptLabel = shortcut.type === 'edit' ? editPrompt : feedbackPrompt;
+    detail = String(await safeQuestion(chalk.cyan(promptLabel))).trim();
+  }
+
+  return {
+    type: shortcut.type,
+    detail,
+  };
+}
+
+const shellSessions = new Map();
+let shellSessionCounter = 0;
+const SHELL_OUTPUT_BUFFER_MAX_CHARS = 50000;
+
+function createShellSession(command, cwd, proc) {
+  const id = `shell-${++shellSessionCounter}`;
+  const session = {
+    id,
+    command,
+    cwd,
+    proc,
+    startedAt: Date.now(),
+    output: '',
+    reportedOffset: 0,
+    completed: false,
+    backgrounded: false,
+    exitCode: null,
+    signal: null,
+    error: null,
+    liveEchoEnabled: true,
+  };
+  shellSessions.set(id, session);
+  return session;
+}
+
+// Prune completed shell sessions to prevent memory leaks (keep last 20)
+function pruneCompletedShellSessions() {
+  const completed = Array.from(shellSessions.entries()).filter(([, s]) => s.completed);
+  const MAX_COMPLETED = 20;
+  if (completed.length > MAX_COMPLETED) {
+    completed
+      .sort((a, b) => a[1].startedAt - b[1].startedAt)
+      .slice(0, completed.length - MAX_COMPLETED)
+      .forEach(([id]) => shellSessions.delete(id));
+  }
+}
+
+function activeShellSessionCount() {
+  return Array.from(shellSessions.values()).filter(session => !session.completed).length;
+}
+
+function appendShellSessionOutput(session, text) {
+  if (!session || !text) return;
+  session.output += text;
+  if (session.output.length > SHELL_OUTPUT_BUFFER_MAX_CHARS) {
+    const overflow = session.output.length - SHELL_OUTPUT_BUFFER_MAX_CHARS;
+    session.output = session.output.slice(overflow);
+    session.reportedOffset = Math.max(0, session.reportedOffset - overflow);
+  }
+}
+
+function formatShellOutputChunk(text = '', emptyLabel = '(no output yet)') {
+  const normalized = String(text ?? '').trim();
+  if (!normalized) return emptyLabel;
+  const maxChars = shellOutputChunkChars();
+  if (normalized.length <= maxChars) return normalized;
+  return `... (showing last ${maxChars.toLocaleString()} chars)\n${normalized.slice(-maxChars)}`;
+}
+
+function shellSessionUsageHint(sessionId) {
+  return `Use run_shell with command \"__shell_read__ ${sessionId}\" to inspect more output, \"__shell_list__\" to list sessions, or \"__shell_stop__ ${sessionId}\" to stop it.`;
+}
+
+function buildShellSessionResult(session, {
+  includeOutput = true,
+  onlyNewOutput = false,
+  markReported = false,
+  backgroundHandoff = false,
+} = {}) {
+  const relevantOutput = onlyNewOutput
+    ? session.output.slice(session.reportedOffset)
+    : session.output;
+
+  if (markReported) {
+    session.reportedOffset = session.output.length;
+  }
+
+  const elapsedSeconds = Math.max(1, Math.round((Date.now() - session.startedAt) / 1000));
+  const statusLine = session.completed
+    ? `Shell session ${session.id} completed in ${elapsedSeconds}s with exit code ${session.exitCode ?? 'unknown'}.`
+    : `Shell session ${session.id} is still running in background after ${elapsedSeconds}s.`;
+
+  const lines = [
+    statusLine,
+    `Command: ${session.command}`,
+    `Directory: ${session.cwd}`,
+  ];
+
+  if (session.error) {
+    lines.push(`Error: ${session.error}`);
+  }
+
+  if (!session.completed || backgroundHandoff) {
+    lines.push(shellSessionUsageHint(session.id));
+  }
+
+  if (includeOutput) {
+    lines.push('');
+    lines.push(onlyNewOutput ? 'Output since last check:' : backgroundHandoff ? 'Initial streamed output:' : 'Captured output:');
+    lines.push(formatShellOutputChunk(relevantOutput, onlyNewOutput ? '(no new output since last check)' : '(no output yet)'));
+  }
+
+  return lines.join('\n');
+}
+
+function parseShellSessionCommand(command = '') {
+  const trimmed = String(command ?? '').trim();
+  if (!trimmed.startsWith('__shell_')) return null;
+
+  const [directive, ...rest] = trimmed.split(/\s+/);
+  const sessionId = rest.join(' ').trim();
+
+  if (directive === '__shell_list__') return { action: 'list' };
+  if (directive === '__shell_read__') return { action: 'read', sessionId };
+  if (directive === '__shell_stop__') return { action: 'stop', sessionId };
+  return { action: 'unknown', directive };
+}
+
+async function handleShellSessionCommand(command = '') {
+  const parsed = parseShellSessionCommand(command);
+  if (!parsed) return null;
+
+  if (parsed.action === 'unknown') {
+    return `Unknown shell session command: ${parsed.directive}. Use __shell_list__, __shell_read__ <session_id>, or __shell_stop__ <session_id>.`;
+  }
+
+  if (parsed.action === 'list') {
+    const sessions = Array.from(shellSessions.values());
+    if (sessions.length === 0) return 'No shell sessions are currently tracked.';
+    return sessions.map(session => {
+      const state = session.completed ? `done (exit ${session.exitCode ?? 'unknown'})` : 'running';
+      return `${session.id} · ${state} · ${session.command}`;
+    }).join('\n');
+  }
+
+  if (!parsed.sessionId) {
+    return 'Missing shell session id. Use __shell_read__ <session_id> or __shell_stop__ <session_id>.';
+  }
+
+  const session = shellSessions.get(parsed.sessionId);
+  if (!session) {
+    return `Shell session not found: ${parsed.sessionId}. Use __shell_list__ to see available sessions.`;
+  }
+
+  if (parsed.action === 'read') {
+    return buildShellSessionResult(session, {
+      includeOutput: true,
+      onlyNewOutput: true,
+      markReported: true,
+      backgroundHandoff: !session.completed,
+    });
+  }
+
+  if (parsed.action === 'stop') {
+    if (session.completed) {
+      return buildShellSessionResult(session, {
+        includeOutput: true,
+        onlyNewOutput: false,
+        markReported: true,
+      });
+    }
+
+    console.log();
+    const confirmation = await safeQuestion(confirmPrompt(`Stop background shell session ${session.id}`, 'error', '[y/N] '));
+    if (!['y', 'yes'].includes(String(confirmation ?? '').trim().toLowerCase())) {
+      return `Stop request cancelled for shell session ${session.id}.`;
+    }
+
+    try {
+      session.proc.kill('SIGTERM');
+      return `Sent SIGTERM to shell session ${session.id}. ${shellSessionUsageHint(session.id)}`;
+    } catch (error) {
+      return `Could not stop shell session ${session.id}: ${error.message}`;
+    }
+  }
+
+  return null;
+}
+
+function getTrackedShellSessions() {
+  return Array.from(shellSessions.values()).sort((left, right) => right.startedAt - left.startedAt);
+}
+
+function shellSessionStatusLabel(session) {
+  if (!session) return 'unknown';
+  if (!session.completed) return 'running';
+  if (session.signal) return `stopped (${session.signal})`;
+  return `done (${session.exitCode ?? 'unknown'})`;
+}
+
+function renderShellSessionsPanel() {
+  const sessions = getTrackedShellSessions();
+  const activeCount = sessions.filter(session => !session.completed).length;
+  const completedCount = sessions.length - activeCount;
+  const lines = [
+    `config        ${chalk.white(shellStreamToModelEnabled() ? 'stream on' : 'stream off')} ${UI.slate('·')} ${chalk.white(`bg ${shellBackgroundMode()}`)} ${UI.slate('·')} ${chalk.white(`after ${shellBackgroundAfterSeconds()}s`)} ${UI.slate('·')} ${chalk.white(`chunk ${shellOutputChunkChars()}`)}`,
+    UI.slate(`visibility    bg off keeps long shell commands fully attached and visible in the terminal`),
+    `sessions      ${chalk.white(`${activeCount} active`)} ${UI.slate('·')} ${chalk.white(`${completedCount} completed`)}`,
+  ];
+
+  if (sessions.length === 0) {
+    lines.push(UI.slate('No background shell sessions are currently tracked.'));
+  } else {
+    for (const session of sessions.slice(0, 8)) {
+      const elapsed = formatElapsed(Date.now() - session.startedAt);
+      const lastOutputLine = String(session.output || '').trim().split('\n').filter(Boolean).slice(-1)[0] || '(no output yet)';
+      lines.push(`${chalk.white(session.id)} ${UI.slate('·')} ${chalk.white(shellSessionStatusLabel(session))} ${UI.slate('·')} ${UI.slate(elapsed)}`);
+      lines.push(`  ${UI.ink(ellipsis(session.command, 90))}`);
+      lines.push(`  ${UI.slate(ellipsis(lastOutputLine, 90))}`);
+    }
+    if (sessions.length > 8) {
+      lines.push(UI.slate(`Showing 8 of ${sessions.length} tracked sessions.`));
+    }
+  }
+
+  return box(lines.join('\n'), 'Shell Sessions', 'cyan');
+}
+
+// ─── Markdown terminal rendering ───────────────────────────────────
+// Dynamic width helper (recalculated on every render)
+function mdWidth() {
+  return Math.min(process.stdout.columns || 80, 120);
+}
+
+// Base marked-terminal config (tables, emoji, reflow, text styles)
+marked.use(markedTerminal({
+    code: chalk.cyan,            // fallback when highlight fails
+    blockquote: chalk.gray.italic,
+    html: chalk.gray,
+    heading: chalk.bold.cyan,
+    firstHeading: chalk.bold.cyan,
     table: chalk.white,
     tableOptions: {
       chars: {
@@ -1825,11 +2843,152 @@ marked.use(markedTerminal({
     del: chalk.strikethrough,
     link: chalk.underline.blue,
     href: chalk.gray,
-    showSectionPrefix: true,
+    showSectionPrefix: false,
     reflowText: true,
-    width: Math.min(process.stdout.columns || 80, 120)
+    emoji: true,
+    tab: 2,
+    width: 120, // overridden dynamically below
 }));
 
+// ─── Enhanced renderers (override marked-terminal defaults) ────────
+const HEADING_STYLES = [
+  chalk.hex('#7cc4ff').bold.underline,   // h1 – bright cyan underline
+  chalk.hex('#7cc4ff').bold,             // h2 – bright cyan bold
+  chalk.hex('#9bbcff').bold,             // h3 – soft blue bold
+  chalk.hex('#b8d9ff'),                  // h4 – light blue
+  chalk.hex('#8a95a6').bold,             // h5 – slate bold
+  chalk.hex('#8a95a6'),                  // h6 – slate
+];
+const HEADING_PREFIX = ['◆', '◇', '▸', '▹', '·', '·'];
+
+function syntaxHighlight(code, lang) {
+  try {
+    if (!lang) return chalk.hex('#e6ebf2')(code);
+    return highlightCode(code, { language: lang, ignoreIllegals: true });
+  } catch {
+    return chalk.hex('#e6ebf2')(code);
+  }
+}
+
+function framedCodeBlock(code, lang) {
+  const width = mdWidth();
+  const innerWidth = Math.max(20, width - 6);  // "  │ " prefix = 4, " │" suffix = 2
+  const highlighted = syntaxHighlight(code, lang);
+  const lines = highlighted.split('\n');
+
+  // Top rule with optional language label
+  let topRule;
+  if (lang) {
+    const label = ` ${chalk.hex('#8a95a6').italic(lang)} `;
+    const labelLen = lang.length + 2;  // visible length of " lang "
+    const preDashes = 2;
+    const postDashes = Math.max(0, innerWidth + 2 - preDashes - labelLen);
+    topRule = chalk.hex('#3d4f5f')('  ┌' + '─'.repeat(preDashes)) + label + chalk.hex('#3d4f5f')('─'.repeat(postDashes) + '┐');
+  } else {
+    topRule = chalk.hex('#3d4f5f')('  ┌' + '─'.repeat(innerWidth + 2) + '┐');
+  }
+
+  // Code lines with left+right border
+  const framedLines = lines.map(line => {
+    const visLen = stripAnsi(line).length;
+    const pad = Math.max(0, innerWidth - visLen);
+    return chalk.hex('#3d4f5f')('  │ ') + line + ' '.repeat(pad) + chalk.hex('#3d4f5f')(' │');
+  });
+
+  // Bottom rule
+  const bottomRule = chalk.hex('#3d4f5f')('  └' + '─'.repeat(innerWidth + 2) + '┘');
+
+  return '\n' + topRule + '\n' + framedLines.join('\n') + '\n' + bottomRule + '\n';
+}
+
+const LIST_BULLETS = ['●', '○', '◦', '·'];
+
+marked.use({
+  renderer: {
+    // ── Fenced code blocks: framed box with syntax highlighting ──
+    code({ text, lang }) {
+      return framedCodeBlock(text, lang || '');
+    },
+
+    // ── Headings: level-aware icons + color gradient ──
+    heading({ tokens, depth }) {
+      const text = this.parser.parseInline(tokens);
+      const level = Math.max(0, Math.min(depth - 1, 5));
+      const style = HEADING_STYLES[level];
+      const prefix = HEADING_PREFIX[level];
+      const plain = stripAnsi(text);
+      const underChar = level === 0 ? '═' : level === 1 ? '─' : '';
+      const underline = underChar ? '\n  ' + chalk.hex('#3d4f5f')(underChar.repeat(Math.min(plain.length + 4, mdWidth() - 4))) : '';
+      return `\n  ${chalk.hex('#3d4f5f')(prefix)} ${style(plain)}${underline}\n`;
+    },
+
+    // ── Blockquotes: thick left bar with dimmed styling ──
+    blockquote({ tokens }) {
+      const body = this.parser.parse(tokens);
+      const lines = body.split('\n').filter(l => l.trim() !== '');
+      const bar = chalk.hex('#5a7a9a')('▌');
+      const textStyle = chalk.hex('#9aafcc').italic;
+      return '\n' + lines.map(line => {
+        const clean = stripAnsi(line).trim();
+        return `  ${bar} ${textStyle(clean)}`;
+      }).join('\n') + '\n';
+    },
+
+    // ── Lists: modern bullets ──
+    list({ items, ordered }) {
+      const result = items.map((item, i) => {
+        // Parse inline tokens to properly render codespan, strong, em, etc.
+        let body = '';
+        for (const tok of item.tokens) {
+          if (tok.tokens) {
+            body += this.parser.parseInline(tok.tokens);
+          } else if (tok.type === 'space') {
+            body += '';
+          } else {
+            body += tok.text || '';
+          }
+        }
+        body = body.replace(/\n+$/, '');
+        const lines = body.split('\n');
+        if (ordered) {
+          const num = chalk.hex('#7cc4ff')(`${i + 1}.`);
+          const prefix = `  ${num} `;
+          return lines.map((line, li) => {
+            return li === 0 ? `${prefix}${line.trim()}` : `     ${line.trim()}`;
+          }).join('\n');
+        }
+        const bullet = chalk.hex('#5a7a9a')(LIST_BULLETS[Math.min(item.depth || 0, LIST_BULLETS.length - 1)] || '●');
+        const prefix = `  ${bullet} `;
+        return lines.map((line, li) => {
+          return li === 0 ? `${prefix}${line.trim()}` : `    ${line.trim()}`;
+        }).join('\n');
+      }).join('\n');
+      return '\n' + result + '\n';
+    },
+
+    // ── Horizontal rules: themed divider ──
+    hr() {
+      const w = Math.max(20, mdWidth() - 4);
+      return '\n  ' + chalk.hex('#3d4f5f')('─'.repeat(w)) + '\n';
+    },
+
+    // ── Inline code: highlighted background effect ──
+    codespan({ text }) {
+      return chalk.bgHex('#1a2733').hex('#7cc4ff')(` ${text} `);
+    },
+
+    // ── Links: visible URL with icon ──
+    link({ href, tokens }) {
+      const text = this.parser.parseInline(tokens);
+      const plain = stripAnsi(text);
+      if (plain === href) {
+        return chalk.hex('#7cc4ff').underline(href);
+      }
+      return `${chalk.hex('#7cc4ff').underline(plain)} ${chalk.hex('#8a95a6')('→')} ${chalk.hex('#5a7a9a').underline(href)}`;
+    },
+  }
+});
+
 // Render markdown to terminal
 function renderMarkdown(text) {
   try {
@@ -1840,7 +2999,7 @@ function renderMarkdown(text) {
 }
 
 let stepMode = false;
-let debugMode = false; // Toggle with /debug command
+let debugMode = sapperConfig.debug || false; // Toggle with /debug command, or set in config
 let abortStream = false; // Flag to interrupt AI response
 
 // ═══════════════════════════════════════════════════════════════
@@ -1901,6 +3060,181 @@ async function safeQuestion(query) {
   });
 }
 
+function countLines(text = '') {
+  if (!text) return 0;
+  return String(text).split('\n').length;
+}
+
+function formatPreviewLine(line = '', maxWidth = Math.max(32, terminalWidth(82) - 12)) {
+  return ellipsis(String(line).replace(/\t/g, '  '), maxWidth);
+}
+
+function buildPreviewBlock(lines, startIdx, endIdx, changeStart, changeEnd, marker, colorFn, maxLines = 14) {
+  if (lines.length === 0) {
+    return colorFn(`${marker}   | (empty)`);
+  }
+
+  const indexes = [];
+  for (let index = startIdx; index <= endIdx; index++) {
+    indexes.push(index);
+  }
+
+  const clipped = indexes.length > maxLines;
+  const visibleIndexes = clipped
+    ? [
+        ...indexes.slice(0, Math.ceil(maxLines / 2)),
+        -1,
+        ...indexes.slice(-(Math.floor(maxLines / 2)))
+      ]
+    : indexes;
+  const numberWidth = String(Math.max(endIdx + 1, 1)).length;
+  const rows = [];
+
+  if (startIdx > 0) {
+    rows.push(UI.slate('  ...'));
+  }
+
+  for (const index of visibleIndexes) {
+    if (index === -1) {
+      rows.push(UI.slate('  ...'));
+      continue;
+    }
+
+    const prefix = index >= changeStart && index <= changeEnd ? marker : ' ';
+    const row = `${prefix} ${String(index + 1).padStart(numberWidth)} | ${formatPreviewLine(lines[index])}`;
+    rows.push(prefix === marker ? colorFn(row) : UI.slate(row));
+  }
+
+  if (clipped || endIdx < lines.length - 1) {
+    rows.push(UI.slate('  ...'));
+  }
+
+  return rows.join('\n');
+}
+
+function buildFileChangePreview(oldContent = '', newContent = '') {
+  const before = String(oldContent ?? '');
+  const after = String(newContent ?? '');
+
+  if (before === after) {
+    return UI.slate('No visible text changes.');
+  }
+
+  const oldLines = before ? before.split('\n') : [];
+  const newLines = after ? after.split('\n') : [];
+
+  if (oldLines.length === 0) {
+    return [
+      chalk.green('New file content'),
+      buildPreviewBlock(newLines, 0, Math.max(0, Math.min(newLines.length - 1, 13)), 0, Math.max(0, Math.min(newLines.length - 1, 13)), '+', chalk.green)
+    ].join('\n');
+  }
+
+  let start = 0;
+  while (start < oldLines.length && start < newLines.length && oldLines[start] === newLines[start]) {
+    start++;
+  }
+
+  let oldEnd = oldLines.length - 1;
+  let newEnd = newLines.length - 1;
+  while (oldEnd >= start && newEnd >= start && oldLines[oldEnd] === newLines[newEnd]) {
+    oldEnd--;
+    newEnd--;
+  }
+
+  const contextLines = 3;
+  const oldStart = Math.max(0, start - contextLines);
+  const newStart = Math.max(0, start - contextLines);
+  const oldPreviewEnd = Math.min(oldLines.length - 1, Math.max(oldEnd, start - 1) + contextLines);
+  const newPreviewEnd = Math.min(newLines.length - 1, Math.max(newEnd, start - 1) + contextLines);
+
+  return [
+    chalk.red('Before'),
+    buildPreviewBlock(oldLines, oldStart, oldPreviewEnd, start, oldEnd, '-', chalk.red),
+    '',
+    chalk.green('After'),
+    buildPreviewBlock(newLines, newStart, newPreviewEnd, start, newEnd, '+', chalk.green),
+  ].join('\n');
+}
+
+function ensureParentDirectory(filePath) {
+  const parentDir = dirname(filePath);
+  if (parentDir && parentDir !== '.' && !fs.existsSync(parentDir)) {
+    fs.mkdirSync(parentDir, { recursive: true });
+  }
+}
+
+function restoreFileSnapshot(filePath, originalContent, existedBefore) {
+  if (existedBefore) {
+    fs.writeFileSync(filePath, originalContent);
+  } else if (fs.existsSync(filePath)) {
+    fs.unlinkSync(filePath);
+  }
+}
+
+async function reviewCandidateFile({ filePath, originalContent = '', newContent = '', title = 'File Review', successMessage }) {
+  const existedBefore = fs.existsSync(filePath);
+
+  ensureParentDirectory(filePath);
+  fs.writeFileSync(filePath, newContent);
+
+  while (true) {
+    console.log();
+    console.log(box(
+      `${keyValue('File', chalk.white(filePath), 8)}\n` +
+      `${keyValue('Status', chalk.white(existedBefore ? 'modified' : 'new file'), 8)}\n` +
+      `${keyValue('Lines', chalk.white(`${countLines(originalContent)} -> ${countLines(newContent)}`), 8)}\n` +
+      `${UI.slate('Candidate change written to disk. Review it in your editor now.')}\n` +
+      `${UI.slate('Choose keep to accept it, ignore to revert it, diff to inspect, f for feedback, or e for edit instructions.')}`,
+      title, 'yellow'
+    ));
+
+    const decisionInput = await safeQuestion(chalk.yellow('Review change ') + chalk.gray('[k]eep/[i]gnore/[d]iff/[f]eedback/[e]dit: '));
+    const decisionRaw = String(decisionInput ?? '').trim();
+    const decision = decisionRaw.toLowerCase();
+
+    if (['k', 'keep', 'y', 'yes'].includes(decision)) {
+      return successMessage || `Successfully saved changes to ${filePath}`;
+    }
+
+    if (['i', 'ignore', 'n', 'no'].includes(decision)) {
+      restoreFileSnapshot(filePath, originalContent, existedBefore);
+      return existedBefore
+        ? `Ignored change and restored ${filePath}`
+        : `Ignored change and removed ${filePath}`;
+    }
+
+    if (decision === '' || decision === 'd' || decision === 'diff') {
+      console.log();
+      console.log(box(buildFileChangePreview(originalContent, newContent), 'Change Diff', 'yellow'));
+      continue;
+    }
+
+    const approvalInstruction = await resolveApprovalInstruction(decisionRaw, {
+      feedbackPrompt: 'Feedback for this change: ',
+      editPrompt: 'Edit instruction for this change: ',
+    });
+
+    if (approvalInstruction) {
+      if (!approvalInstruction.detail) {
+        console.log(UI.slate('Enter feedback or edit instructions for Sapper, or choose keep/ignore/diff.'));
+        continue;
+      }
+
+      restoreFileSnapshot(filePath, originalContent, existedBefore);
+      const label = approvalInstruction.type === 'edit' ? 'User edit instruction' : 'User feedback';
+      return `Change rejected by user for ${filePath}.\n${label}: ${approvalInstruction.detail}\nThe original file was restored. Revise the change and try again.`;
+    }
+
+    if (decisionRaw) {
+      restoreFileSnapshot(filePath, originalContent, existedBefore);
+      return `Change rejected by user for ${filePath}.\nUser feedback: ${decisionRaw}\nThe original file was restored. Revise the change and try again.`;
+    }
+
+    console.log(UI.slate('Type k to keep, i to ignore, d to view the diff, f for feedback, e for edit instructions, or write feedback directly.'));
+  }
+}
+
 // Directories to ignore when listing files
 const IGNORE_DIRS = new Set([
   'node_modules', '.git', '.svn', '.hg', 'dist', 'build', 
@@ -1919,9 +3253,11 @@ const CODE_EXTENSIONS = new Set([
 ]);
 
 // Max file size to include (skip large files like bundled/minified)
-const MAX_FILE_SIZE = 100000; // 100KB per file
-const MAX_TOTAL_SCAN_SIZE = 1000000; // 1000KB total scan limit
-const MAX_URL_SIZE = 200000; // 200KB max for fetched web pages
+// File limits — configurable via .sapper/config.json
+function getMaxFileSize() { return sapperConfig.maxFileSize || DEFAULT_CONFIG.maxFileSize; }
+function getMaxScanSize() { return sapperConfig.maxScanSize || DEFAULT_CONFIG.maxScanSize; }
+function getMaxUrlSize() { return sapperConfig.maxUrlSize || DEFAULT_CONFIG.maxUrlSize; }
+function getPatchRetries() { return sapperConfig.patchRetries || DEFAULT_CONFIG.patchRetries; }
 
 // ═══════════════════════════════════════════════════════════════
 // URL FETCHING — Read web pages and learn from them
@@ -1930,7 +3266,7 @@ import https from 'https';
 import http from 'http';
 
 // Fetch a URL and return extracted text content
-function fetchUrl(url, timeout = 15000) {
+function fetchUrl(url, timeout = LIMITS.FETCH_URL_TIMEOUT_MS) {
   return new Promise((resolve, reject) => {
     const lib = url.startsWith('https') ? https : http;
     const req = lib.get(url, { 
@@ -1955,9 +3291,9 @@ function fetchUrl(url, timeout = 15000) {
       let size = 0;
       res.on('data', (chunk) => {
         size += chunk.length;
-        if (size > MAX_URL_SIZE) {
+        if (size > getMaxUrlSize()) {
           res.destroy();
-          reject(new Error(`Page too large (>${Math.round(MAX_URL_SIZE/1024)}KB)`));
+          reject(new Error(`Page too large (>${Math.round(getMaxUrlSize()/1024)}KB)`));
           return;
         }
         data += chunk;
@@ -1992,8 +3328,8 @@ function htmlToText(html) {
   text = text.replace(/\n\s*\n/g, '\n\n');
   text = text.trim();
   // Limit to reasonable size
-  if (text.length > 50000) {
-    text = text.substring(0, 50000) + '\n\n[... content truncated at 50KB ...]';
+  if (text.length > LIMITS.WEB_CONTENT_MAX_CHARS) {
+    text = text.substring(0, LIMITS.WEB_CONTENT_MAX_CHARS) + '\n\n[... content truncated at 50KB ...]';
   }
   return text;
 }
@@ -2073,6 +3409,20 @@ function shouldIgnore(nameOrPath) {
   return ignored;
 }
 
+// Format file attachments into a decorated string block for context messages
+function formatFileAttachments(fileAttachments) {
+  let s = '\n\n══════════════════════════════════════\n';
+  s += `📎 ATTACHED FILES (${fileAttachments.length})\n`;
+  s += '══════════════════════════════════════\n\n';
+  for (const file of fileAttachments) {
+    s += `┌─── ${file.path} ───\n`;
+    s += file.content;
+    if (!file.content.endsWith('\n')) s += '\n';
+    s += `└─── END ${file.path} ───\n\n`;
+  }
+  return s;
+}
+
 // Scan entire codebase and return summary
 function scanCodebase(dir = '.', depth = 0, maxDepth = 5) {
   if (depth > maxDepth) return { files: [], totalSize: 0 };
@@ -2102,11 +3452,11 @@ function scanCodebase(dir = '.', depth = 0, maxDepth = 5) {
         
         try {
           const stats = fs.statSync(fullPath);
-          if (stats.size > MAX_FILE_SIZE) {
+          if (stats.size > getMaxFileSize()) {
             files.push({ path: fullPath, size: stats.size, skipped: true, reason: 'too large' });
             continue;
           }
-          if (totalSize + stats.size > MAX_TOTAL_SCAN_SIZE) {
+          if (totalSize + stats.size > getMaxScanSize()) {
             files.push({ path: fullPath, size: stats.size, skipped: true, reason: 'total limit reached' });
             continue;
           }
@@ -2327,18 +3677,19 @@ async function pickModel(models) {
 
   const render = () => {
     const current = models[cursor];
-    console.clear();
-    console.log(BANNER);
-    console.log(`${UI.slate(process.cwd())} ${UI.slate('·')} ${UI.slate(`v${CURRENT_VERSION}`)}`);
-    console.log(divider());
-    console.log(sectionTitle('Model selection', 'use ↑↓ or j/k, enter to confirm', 'cyan'));
-    console.log();
+    const lines = [
+      BANNER,
+      `${UI.slate(process.cwd())} ${UI.slate('·')} ${UI.slate(`v${CURRENT_VERSION}`)}`,
+      divider(),
+      sectionTitle('Model selection', 'use ↑↓ or j/k, enter to confirm', 'cyan'),
+      ''
+    ];
 
     const startIdx = Math.max(0, Math.min(cursor - Math.floor(pageSize / 2), models.length - pageSize));
     const endIdx = Math.min(startIdx + pageSize, models.length);
 
     if (startIdx > 0) {
-      console.log(UI.slate('  ↑ more models'));
+      lines.push(UI.slate('  ↑ more models'));
     }
 
     for (let i = startIdx; i < endIdx; i++) {
@@ -2353,20 +3704,20 @@ async function pickModel(models) {
         model.details?.parameter_size || null,
       ].filter(Boolean).join(' · ');
 
-      console.log(`${marker} ${index}  ${name}`);
+      lines.push(`${marker} ${index}  ${name}`);
       if (meta) {
-        console.log(`     ${UI.slate(meta)}`);
+        lines.push(`     ${UI.slate(meta)}`);
       }
     }
 
     if (endIdx < models.length) {
-      console.log(UI.slate('  ↓ more models'));
+      lines.push(UI.slate('  ↓ more models'));
     }
 
     const family = current.details?.family || current.details?.format || current.details?.parameter_size || 'local model';
     const quant = current.details?.quantization_level || current.details?.quantization || 'default';
-    console.log();
-    console.log(box(
+    lines.push('');
+    lines.push(box(
       `${keyValue('Selected', chalk.white.bold(current.name), 10)}\n` +
       `${keyValue('Footprint', UI.ink(current.size ? formatBytes(current.size) : 'unknown'), 10)}\n` +
       `${keyValue('Updated', UI.ink(current.modified_at ? formatRelativeTime(current.modified_at) : 'unknown'), 10)}\n` +
@@ -2374,6 +3725,8 @@ async function pickModel(models) {
       `${keyValue('Quant', UI.ink(quant), 10)}`,
       'Preview', 'gray'
     ));
+
+    renderViewport(lines.join('\n'), { verticalAlign: 'center' });
   };
 
   return new Promise((resolve) => {
@@ -2408,11 +3761,11 @@ async function pickModel(models) {
         render();
       } else if (key.name === 'return') {
         cleanup();
-        console.log(UI.slate(`\nUsing ${models[cursor].name}`));
+        console.clear();
         resolve(models[cursor].name);
       } else if (key.name === 'escape' || key.name === 'q' || (key.ctrl && key.name === 'c')) {
         cleanup();
-        console.log(UI.slate(`\nUsing ${models[cursor].name}`));
+        console.clear();
         resolve(models[cursor].name);
       }
     };
@@ -2421,48 +3774,289 @@ async function pickModel(models) {
   });
 }
 
-const tools = {
-  read: (path) => {
-    try { return fs.readFileSync(path.trim(), 'utf8'); } 
-    catch (error) { return `Error reading file: ${error.message}`; }
-  },
-  patch: async (path, oldText, newText) => {
-    const trimmedPath = path.trim();
+let toolWorkingDirectory = process.cwd();
+
+function getToolWorkingDirectory() {
+  return toolWorkingDirectory || process.cwd();
+}
+
+function resolveToolPath(pathValue = '.', { allowEmpty = false } = {}) {
+  let rawPath = typeof pathValue === 'string' ? pathValue.trim() : '';
+  // Strip surrounding quotes that models sometimes add
+  if ((rawPath.startsWith('"') && rawPath.endsWith('"')) || (rawPath.startsWith("'") && rawPath.endsWith("'"))) {
+    rawPath = rawPath.slice(1, -1).trim();
+  }
+  if (!rawPath) {
+    return allowEmpty ? '' : getToolWorkingDirectory();
+  }
+  if (rawPath === '/') {
+    return getToolWorkingDirectory();
+  }
+  const resolved = isAbsolute(rawPath) ? rawPath : pathResolve(getToolWorkingDirectory(), rawPath);
+  // Prevent path traversal outside the project directory
+  const projectRoot = process.cwd();
+  if (!resolved.startsWith(projectRoot + '/') && resolved !== projectRoot) {
+    return projectRoot; // Fall back to project root for paths that escape sandbox
+  }
+  return resolved;
+}
+
+function resolveLineWindowCount(value, fallback = 20) {
+  return normalizeIntegerInRange(value, fallback, 1, 400);
+}
+
+function readFileLineWindow(pathValue, mode = 'head', countValue = 20) {
+  const trimmedPath = typeof pathValue === 'string' ? pathValue.trim() : '';
+  if (!trimmedPath) return 'Error reading file: missing file path';
+
+  try {
+    const resolvedPath = resolveToolPath(trimmedPath);
+    const rawContent = fs.readFileSync(resolvedPath, 'utf8');
+    const lines = rawContent === '' ? [] : rawContent.split('\n');
+    const requestedCount = resolveLineWindowCount(countValue, 20);
+
+    if (lines.length === 0) {
+      return `${mode === 'tail' ? 'Last' : 'First'} 0 lines of ${trimmedPath}:\n(empty file)`;
+    }
+
+    const slice = mode === 'tail'
+      ? lines.slice(-requestedCount)
+      : lines.slice(0, requestedCount);
+    const shownCount = slice.length;
+    const lineLabel = shownCount === 1 ? 'line' : 'lines';
+    const descriptor = mode === 'tail' ? 'last' : 'first';
+
+    return `Showing the ${descriptor} ${shownCount} ${lineLabel} of ${trimmedPath}:\n${slice.join('\n')}`;
+  } catch (error) {
+    return `Error reading file: ${error.message}`;
+  }
+}
+
+function findPathsByName(patternValue, startPathValue = '.') {
+  const pattern = String(patternValue ?? '').trim();
+  const startPath = typeof startPathValue === 'string' ? startPathValue.trim() : '';
+  if (!pattern) return 'Error finding files: missing search pattern';
+
+  const resolvedStartPath = resolveToolPath(startPath || '.');
+  if (!fs.existsSync(resolvedStartPath)) {
+    return `Error finding files: ${startPath || '.'} does not exist`;
+  }
+
+  let startStats;
+  try {
+    startStats = fs.statSync(resolvedStartPath);
+  } catch (error) {
+    return `Error finding files: ${error.message}`;
+  }
+
+  if (!startStats.isDirectory()) {
+    return `Error finding files: ${startPath || '.'} is not a directory`;
+  }
+
+  const matches = [];
+  const maxResults = 100;
+  const patternLower = pattern.toLowerCase();
+
+  const visit = (dirPath, displayPrefix = '') => {
+    if (matches.length >= maxResults) return;
+
+    let entries = [];
     try {
-      const content = fs.readFileSync(trimmedPath, 'utf8');
+      entries = fs.readdirSync(dirPath, { withFileTypes: true });
+    } catch {
+      return;
+    }
 
-      // --- Line-number mode: LINE:15|||new text ---
-      const lineMatch = oldText.match(/^LINE:(\d+)$/);
-      if (lineMatch) {
-        const lineNum = parseInt(lineMatch[1], 10);
-        const lines = content.split('\n');
-        if (lineNum < 1 || lineNum > lines.length) {
-          return `Error: Line ${lineNum} out of range (file has ${lines.length} lines) in ${trimmedPath}`;
-        }
-        const oldLine = lines[lineNum - 1];
-        lines[lineNum - 1] = newText;
-        const newContent = lines.join('\n');
-        console.log();
-        const diffContent =
-          `${keyValue('File', chalk.white(trimmedPath), 8)}\n` +
-          `${keyValue('Line', chalk.white(String(lineNum)), 8)}\n` +
-          `${UI.slate('Preview')}\n` +
-          chalk.red('- ' + oldLine) + '\n' +
-          chalk.green('+ ' + newText);
-        console.log(box(diffContent, 'Patch Review', 'yellow'));
-        const confirm = await safeQuestion(confirmPrompt('Apply patch', 'warning'));
-        if (confirm.toLowerCase() === 'y') {
-          fs.writeFileSync(trimmedPath, newContent);
-          return `Successfully patched line ${lineNum} of ${trimmedPath}`;
-        }
-        return 'Patch rejected by user.';
+    for (const entry of entries) {
+      if (matches.length >= maxResults) return;
+      if (entry.name.startsWith('.')) continue;
+      if (shouldIgnore(entry.name)) continue;
+
+      const fullPath = join(dirPath, entry.name);
+      const relativePath = displayPrefix ? `${displayPrefix}/${entry.name}` : entry.name;
+      if (shouldIgnore(relativePath) || shouldIgnore(fullPath)) continue;
+
+      const displayPath = entry.isDirectory() ? `${relativePath}/` : relativePath;
+      if (entry.name.toLowerCase().includes(patternLower) || relativePath.toLowerCase().includes(patternLower)) {
+        matches.push(displayPath);
       }
 
-      // --- Exact match (try as-is first, then trimmed) ---
-      let matchedOld = oldText;
-      let newContent;
-      if (content.includes(oldText)) {
-        newContent = content.replace(oldText, newText);
+      if (entry.isDirectory()) {
+        visit(fullPath, relativePath);
+      }
+    }
+  };
+
+  visit(resolvedStartPath);
+
+  if (matches.length === 0) {
+    return `No files or directories found matching: ${pattern}`;
+  }
+
+  const header = `Found ${matches.length} matching path${matches.length === 1 ? '' : 's'} for: ${pattern}`;
+  const body = matches.join('\n');
+  const truncated = matches.length >= maxResults ? '\n... (results truncated)' : '';
+  return `${header}\n${body}${truncated}`;
+}
+
+function truncateToolText(textValue = '', maxChars = 24000) {
+  const text = String(textValue ?? '').trim();
+  if (!text) return '';
+  if (text.length <= maxChars) return text;
+  return `${text.slice(0, maxChars)}\n... (output truncated at ${maxChars.toLocaleString()} chars)`;
+}
+
+function shellQuote(value = '') {
+  return `'${String(value ?? '').replace(/'/g, `'\\''`)}'`;
+}
+
+function runCapturedCommand(command, { cwd = getToolWorkingDirectory(), timeoutMs = 12000, maxOutput = 24000 } = {}) {
+  return new Promise((resolve) => {
+    const proc = spawn('sh', ['-c', command], { cwd });
+    let stdout = '';
+    let stderr = '';
+    let stdoutTruncated = false;
+    let stderrTruncated = false;
+    let finished = false;
+
+    const appendLimited = (existing, chunkText, maxChars, setTruncated) => {
+      if (existing.length >= maxChars) {
+        setTruncated(true);
+        return existing;
+      }
+      const remaining = maxChars - existing.length;
+      if (chunkText.length > remaining) {
+        setTruncated(true);
+        return existing + chunkText.slice(0, remaining);
+      }
+      return existing + chunkText;
+    };
+
+    const finish = (result) => {
+      if (finished) return;
+      finished = true;
+      if (timer) clearTimeout(timer);
+      const finalStdout = stdoutTruncated
+        ? `${stdout}\n... (stdout truncated at ${maxOutput.toLocaleString()} chars)`
+        : stdout;
+      const finalStderr = stderrTruncated
+        ? `${stderr}\n... (stderr truncated at ${maxOutput.toLocaleString()} chars)`
+        : stderr;
+      resolve({ ...result, stdout: finalStdout, stderr: finalStderr });
+    };
+
+    const timer = timeoutMs > 0
+      ? setTimeout(() => {
+          try { proc.kill('SIGTERM'); } catch (e) {}
+          finish({ exitCode: 124, stdout, stderr: `${stderr}\nCommand timed out after ${timeoutMs}ms`.trim(), timedOut: true });
+        }, timeoutMs)
+      : null;
+
+    proc.stdout.on('data', (data) => {
+      stdout = appendLimited(stdout, data.toString(), maxOutput, (value) => { stdoutTruncated = value; });
+    });
+    proc.stderr.on('data', (data) => {
+      stderr = appendLimited(stderr, data.toString(), maxOutput, (value) => { stderrTruncated = value; });
+    });
+
+    proc.on('error', (error) => {
+      finish({ exitCode: 1, stdout, stderr: `${stderr}\n${error.message}`.trim(), timedOut: false });
+    });
+    proc.on('close', (code) => {
+      finish({ exitCode: code ?? 0, stdout, stderr, timedOut: false });
+    });
+  });
+}
+
+function normalizeFetchedWebContent(rawContent = '') {
+  const trimmed = String(rawContent ?? '').trim();
+  if (!trimmed) return '';
+
+  if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+    try {
+      return JSON.stringify(JSON.parse(trimmed), null, 2);
+    } catch (error) {
+      return trimmed;
+    }
+  }
+
+  if (trimmed.startsWith('<') || trimmed.toLowerCase().includes('<html')) {
+    return htmlToText(trimmed);
+  }
+
+  return trimmed;
+}
+
+function keywordRecallMemory(query, embeddings, topK = 3) {
+  const queryText = String(query ?? '').trim().toLowerCase();
+  if (!queryText || !embeddings?.chunks?.length) return [];
+
+  const queryWords = Array.from(new Set(
+    queryText.split(/[^a-z0-9_]+/i).map(word => word.trim()).filter(word => word.length >= 2)
+  ));
+  const maxScore = Math.max(1, 4 + queryWords.length);
+
+  return embeddings.chunks
+    .map((chunk) => {
+      const text = String(chunk?.text ?? '');
+      const lowered = text.toLowerCase();
+      let score = 0;
+      if (lowered.includes(queryText)) score += 4;
+      for (const word of queryWords) {
+        if (lowered.includes(word)) score += 1;
+      }
+      return { ...chunk, score: Math.min(1, score / maxScore) };
+    })
+    .filter(chunk => chunk.score > 0)
+    .sort((a, b) => b.score - a.score || (b.timestamp || 0) - (a.timestamp || 0))
+    .slice(0, topK);
+}
+
+const tools = {
+  read: (path) => {
+    const trimmedPath = typeof path === 'string' ? path.trim() : '';
+    if (!trimmedPath) return 'Error reading file: missing file path';
+    try { return fs.readFileSync(resolveToolPath(trimmedPath), 'utf8'); } 
+    catch (error) { return `Error reading file: ${error.message}`; }
+  },
+  patch: async (path, oldText, newText) => {
+    const trimmedPath = typeof path === 'string' ? path.trim() : '';
+    if (!trimmedPath) return 'Error patching file: missing file path';
+    if (typeof oldText !== 'string' || typeof newText !== 'string') {
+      return 'Error patching file: missing old_text or new_text';
+    }
+    try {
+      const resolvedPath = resolveToolPath(trimmedPath);
+      const content = fs.readFileSync(resolvedPath, 'utf8');
+
+      // --- Line-number mode: LINE:15|||new text ---
+      const lineMatch = oldText.match(/^LINE:(\d+)$/);
+      if (lineMatch) {
+        const lineNum = parseInt(lineMatch[1], 10);
+        const lines = content.split('\n');
+        if (lineNum < 1 || lineNum > lines.length) {
+          return `Error: Line ${lineNum} out of range (file has ${lines.length} lines) in ${trimmedPath}`;
+        }
+        lines[lineNum - 1] = newText;
+        const newContent = lines.join('\n');
+        if (newContent === content) {
+          return `No changes needed in ${trimmedPath}`;
+        }
+
+        return reviewCandidateFile({
+          filePath: resolvedPath,
+          originalContent: content,
+          newContent,
+          title: 'Patch Review',
+          successMessage: `Successfully patched line ${lineNum} of ${trimmedPath}`,
+        });
+      }
+
+      // --- Exact match (try as-is first, then trimmed) ---
+      let matchedOld = oldText;
+      let newContent;
+      if (content.includes(oldText)) {
+        newContent = content.replace(oldText, newText);
       } else if (content.includes(oldText.trim())) {
         // Trimmed fallback — match what's actually in the file
         matchedOld = oldText.trim();
@@ -2513,102 +4107,372 @@ const tools = {
             `Tip: Use LINE:number mode instead, e.g. [TOOL:PATCH]${trimmedPath}:::LINE:42|||replacement text[/TOOL]`;
         }
       }
-      
-      // Show diff preview
-      console.log();
-      const diffContent = 
-        `${keyValue('File', chalk.white(trimmedPath), 8)}\n` +
-        `${UI.slate('Preview')}\n` +
-        chalk.red('- ' + matchedOld.split('\n').join('\n- ')) + '\n' +
-        chalk.green('+ ' + (newContent === content.replace(matchedOld, newText.trim()) ? newText.trim() : newText).split('\n').join('\n+ '));
-      console.log(box(diffContent, 'Patch Review', 'yellow'));
-      
-      const confirm = await safeQuestion(confirmPrompt('Apply patch', 'warning'));
-      if (confirm.toLowerCase() === 'y') {
-        fs.writeFileSync(trimmedPath, newContent);
-        return `Successfully patched ${trimmedPath}`;
+
+      if (newContent === content) {
+        return `No changes needed in ${trimmedPath}`;
       }
-      return 'Patch rejected by user.';
+
+      return reviewCandidateFile({
+        filePath: resolvedPath,
+        originalContent: content,
+        newContent,
+        title: 'Patch Review',
+        successMessage: `Successfully patched ${trimmedPath}`,
+      });
     } catch (error) { return `Error patching file: ${error.message}`; }
   },
   write: async (path, content) => {
-    const trimmedPath = path.trim();
+    const trimmedPath = typeof path === 'string' ? path.trim() : '';
+    if (!trimmedPath) return 'Error writing file: missing file path';
+    try {
+      const resolvedPath = resolveToolPath(trimmedPath);
+      const fileExists = fs.existsSync(resolvedPath);
+      const existingContent = fileExists ? fs.readFileSync(resolvedPath, 'utf8') : '';
+      const nextContent = String(content ?? '');
+
+      if (fileExists && existingContent === nextContent) {
+        return `No changes needed in ${trimmedPath}`;
+      }
+
+      return reviewCandidateFile({
+        filePath: resolvedPath,
+        originalContent: existingContent,
+        newContent: nextContent,
+        title: 'Write Review',
+        successMessage: `Successfully saved changes to ${trimmedPath}`,
+      });
+    } catch (error) { return `Error writing file: ${error.message}`; }
+  },
+  mkdir: (path) => {
+    const trimmedPath = typeof path === 'string' ? path.trim() : '';
+    if (!trimmedPath) return 'Error creating directory: missing directory path';
+    try {
+      fs.mkdirSync(resolveToolPath(trimmedPath), { recursive: true });
+      return `Directory created: ${trimmedPath}`;
+    } catch (error) { return `Error creating directory: ${error.message}`; }
+  },
+  pwd: () => getToolWorkingDirectory(),
+  cd: (path) => {
+    const trimmedPath = typeof path === 'string' ? path.trim() : '';
+    if (!trimmedPath) return 'Error changing directory: missing directory path';
+    try {
+      const resolvedPath = resolveToolPath(trimmedPath);
+      const stats = fs.statSync(resolvedPath);
+      if (!stats.isDirectory()) {
+        return `Error changing directory: ${trimmedPath} is not a directory`;
+      }
+      toolWorkingDirectory = resolvedPath;
+      return `Working directory changed to ${toolWorkingDirectory}`;
+    } catch (error) {
+      return `Error changing directory: ${error.message}`;
+    }
+  },
+  rmdir: async (path) => {
+    const trimmedPath = typeof path === 'string' ? path.trim() : '';
+    if (!trimmedPath) return 'Error removing directory: missing directory path';
+    if (['.', '..', '/'].includes(trimmedPath)) {
+      return `Error removing directory: refusing to remove ${trimmedPath}`;
+    }
+
+    try {
+      const resolvedPath = resolveToolPath(trimmedPath);
+      if (!fs.existsSync(resolvedPath)) {
+        return `Error removing directory: ${trimmedPath} does not exist`;
+      }
+      const stats = fs.statSync(resolvedPath);
+      if (!stats.isDirectory()) {
+        return `Error removing directory: ${trimmedPath} is not a directory`;
+      }
+
+      console.log();
+      console.log(box(
+        `${keyValue('Directory', chalk.white(trimmedPath), 11)}\n` +
+        `${keyValue('Action', chalk.white('remove recursively'), 11)}\n` +
+        `${UI.slate('This will permanently delete the directory and its contents.')}`,
+        'Directory Removal', 'red'
+      ));
+      const confirm = await safeQuestion(confirmPrompt('Remove directory', 'error'));
+      if (!['y', 'yes'].includes(String(confirm ?? '').trim().toLowerCase())) {
+        return 'Directory removal blocked by user.';
+      }
+
+      fs.rmSync(resolvedPath, { recursive: true, force: false });
+      return `Directory removed: ${trimmedPath}`;
+    } catch (error) {
+      return `Error removing directory: ${error.message}`;
+    }
+  },
+  ls: (path) => tools.list(path),
+  cat: (path) => tools.read(path),
+  head: (path, lines) => readFileLineWindow(path, 'head', lines),
+  tail: (path, lines) => readFileLineWindow(path, 'tail', lines),
+  grep: (pattern) => tools.search(pattern),
+  find: (pattern, startPath) => findPathsByName(pattern, startPath),
+  changes: async (path) => {
+    const trimmedPath = typeof path === 'string' ? path.trim() : '';
+    const cwd = getToolWorkingDirectory();
+    const quotedPath = trimmedPath ? ` -- ${shellQuote(trimmedPath)}` : '';
+
+    const repoCheck = await runCapturedCommand('git rev-parse --show-toplevel', {
+      cwd,
+      timeoutMs: 5000,
+      maxOutput: 4000,
+    });
+    if (repoCheck.exitCode !== 0) {
+      return 'Error: current tool working directory is not inside a git repository';
+    }
+
+    const statusCmd = trimmedPath
+      ? `git --no-pager status --short ${quotedPath}`
+      : 'git --no-pager status --short --branch';
+    const [statusResult, unstagedResult, stagedResult] = await Promise.all([
+      runCapturedCommand(statusCmd, { cwd, timeoutMs: 8000, maxOutput: 12000 }),
+      runCapturedCommand(`git --no-pager diff --no-ext-diff --minimal${quotedPath}`, { cwd, timeoutMs: 8000, maxOutput: 20000 }),
+      runCapturedCommand(`git --no-pager diff --cached --no-ext-diff --minimal${quotedPath}`, { cwd, timeoutMs: 8000, maxOutput: 20000 }),
+    ]);
+
+    if (statusResult.exitCode !== 0) {
+      return `Error reading git changes: ${statusResult.stderr.trim() || 'git status failed'}`;
+    }
+
+    const parts = [];
+    const scopeLabel = trimmedPath ? ` for ${trimmedPath}` : '';
+    parts.push(`Git changes${scopeLabel}:`);
+    parts.push(statusResult.stdout.trim() || 'No changed files in working tree.');
+
+    const unstagedDiff = unstagedResult.stdout.trim();
+    const stagedDiff = stagedResult.stdout.trim();
+
+    if (unstagedDiff) {
+      parts.push(`Unstaged diff:\n${unstagedDiff}`);
+    }
+    if (stagedDiff) {
+      parts.push(`Staged diff:\n${stagedDiff}`);
+    }
+    if (!unstagedDiff && !stagedDiff) {
+      parts.push('No staged or unstaged diff output.');
+    }
+
+    return truncateToolText(parts.join('\n\n'), 28000);
+  },
+  fetch_web: async (url) => {
+    const trimmedUrl = String(url ?? '').trim();
+    if (!trimmedUrl) return 'Error fetching web page: missing URL';
+    if (!/^https?:\/\//i.test(trimmedUrl)) {
+      return 'Error fetching web page: URL must start with http:// or https://';
+    }
+
+    try {
+      const rawContent = await fetchUrl(trimmedUrl);
+      const text = normalizeFetchedWebContent(rawContent);
+      if (!text) return `No readable content found at ${trimmedUrl}`;
+      return `Fetched ${trimmedUrl}:\n\n${truncateToolText(text, 28000)}`;
+    } catch (error) {
+      return `Error fetching web page: ${error.message}`;
+    }
+  },
+  recall_memory: async (query) => {
+    const trimmedQuery = String(query ?? '').trim();
+    if (!trimmedQuery) return 'Error searching memory: missing query';
+
+    const embeddings = loadEmbeddings();
+    if (!embeddings.chunks.length) {
+      return 'No saved memory yet. Use /prune or continue working so Sapper can store conversation memory.';
+    }
+
+    let relevant = await findRelevantContext(trimmedQuery, embeddings, 3);
+    if (!relevant.length) {
+      relevant = keywordRecallMemory(trimmedQuery, embeddings, 3);
+    }
+    if (!relevant.length) {
+      return `No relevant memories found for: ${trimmedQuery}`;
+    }
+
+    const formatted = relevant.map((chunk, index) => {
+      const timestamp = chunk.timestamp ? new Date(chunk.timestamp).toISOString() : 'unknown time';
+      const score = typeof chunk.score === 'number'
+        ? `${Math.round(chunk.score * 100)}%`
+        : 'n/a';
+      const text = truncateToolText(chunk.text || '', 1200);
+      return `[${index + 1}] ${timestamp} · relevance ${score}\n${text}`;
+    }).join('\n\n');
+
+    return `Found ${relevant.length} memory match${relevant.length === 1 ? '' : 'es'} for: ${trimmedQuery}\n\n${formatted}`;
+  },
+  open_url: async (url) => {
+    const trimmedUrl = String(url ?? '').trim();
+    if (!trimmedUrl) return 'Error opening URL: missing URL';
+    if (!/^(https?:|file:)/i.test(trimmedUrl)) {
+      return 'Error opening URL: URL must start with http://, https://, or file:';
+    }
+
     console.log();
     console.log(box(
-      `${keyValue('File', chalk.white(trimmedPath), 8)}\n` +
-      `${keyValue('Size', chalk.white((content?.length || 0) + ' chars'), 8)}\n` +
-      `${UI.slate('Preview')}\n` +
-      chalk.gray(content?.substring(0, 300)?.split('\n').slice(0, 8).join('\n') + (content?.length > 300 ? '\n...' : '')),
-      'Write Review', 'yellow'
+      `${keyValue('URL', chalk.white(trimmedUrl), 11)}\n` +
+      `${UI.slate('This will open the URL in your default browser.')}`,
+      'Open URL', 'red'
     ));
-    const confirm = await safeQuestion(confirmPrompt('Allow file write', 'warning'));
-    if (confirm.toLowerCase() === 'y') {
-      try {
-        fs.writeFileSync(trimmedPath, content);
-        return `Successfully saved changes to ${trimmedPath}`;
-      } catch (error) { return `Error writing file: ${error.message}`; }
+    const confirm = await safeQuestion(confirmPrompt('Open URL in browser', 'error'));
+    if (!['y', 'yes'].includes(String(confirm ?? '').trim().toLowerCase())) {
+      return 'Open URL blocked by user.';
     }
-    return "Write blocked by user.";
-  },
-  mkdir: (path) => {
+
     try {
-      fs.mkdirSync(path.trim(), { recursive: true });
-      return `Directory created: ${path}`;
-    } catch (error) { return `Error creating directory: ${error.message}`; }
+      let command = 'open';
+      let args = [trimmedUrl];
+      if (process.platform === 'win32') {
+        command = 'cmd';
+        args = ['/c', 'start', '', trimmedUrl];
+      } else if (process.platform !== 'darwin') {
+        command = 'xdg-open';
+        args = [trimmedUrl];
+      }
+
+      const proc = spawn(command, args, {
+        detached: true,
+        stdio: 'ignore'
+      });
+      proc.unref();
+      return `Opened URL in default browser: ${trimmedUrl}`;
+    } catch (error) {
+      return `Error opening URL: ${error.message}`;
+    }
   },
   shell: async (cmd) => {
+    const trimmedCmd = String(cmd ?? '').trim();
+    if (!trimmedCmd) return 'Error executing shell: missing command';
+
+    const sessionCommandResult = await handleShellSessionCommand(trimmedCmd);
+    if (sessionCommandResult !== null) {
+      return sessionCommandResult;
+    }
+
+    const backgroundEligible = shouldBackgroundShellCommand(trimmedCmd);
     console.log();
     console.log(box(
-      `${keyValue('Directory', chalk.white(process.cwd()), 11)}\n` +
-      `${UI.slate('Command')}\n${chalk.white.bold(cmd)}`,
+      `${keyValue('Directory', chalk.white(getToolWorkingDirectory()), 11)}\n` +
+      `${UI.slate('Command')}\n${chalk.white.bold(trimmedCmd)}\n` +
+      `${UI.slate('Type y to run, n to block, f for feedback, e for edit instructions, or write feedback directly.')}\n` +
+      `${UI.slate(backgroundEligible ? `Background handoff ${shellBackgroundMode()} after ${shellBackgroundAfterSeconds()}s if still running.` : 'This command will stay attached unless it exits quickly.')}`,
       'Shell Approval', 'red'
     ));
-    const confirm = await safeQuestion(confirmPrompt('Run shell command', 'error'));
-    if (confirm.toLowerCase() === 'y') {
-      return new Promise((resolve) => {
-        const useShell = cmd.includes('&&') || cmd.includes('|') || cmd.includes('cd ') || cmd.includes('>') || cmd.includes('<');
-        console.log(chalk.cyan(`\n[RUNNING] ${cmd}\n`));
-        const proc = spawn('sh', ['-c', cmd], { 
-          cwd: process.cwd()
-        });
-        let output = '';
-        proc.stdout.on('data', (data) => { 
-          const text = data.toString();
-          output += text;
-          process.stdout.write(text); // Still show to user in real-time
-        });
-        proc.stderr.on('data', (data) => { 
-          const text = data.toString();
-          output += text;
-          process.stderr.write(text); // Still show errors to user
-        });
-        proc.on('close', (code) => {
-          // Crucial: give control back to Node
-          if (process.stdin.isTTY) {
-            try { process.stdin.setRawMode(false); } catch (e) {}
+    while (true) {
+      const confirmInput = await safeQuestion(confirmPrompt('Run shell command', 'error', '[y/N/f/e or text] '));
+      const confirmRaw = String(confirmInput ?? '').trim();
+      const confirm = confirmRaw.toLowerCase();
+
+      if (['y', 'yes'].includes(confirm)) {
+        return new Promise((resolve) => {
+          console.log(chalk.cyan(`\n[RUNNING] ${trimmedCmd}\n`));
+          const proc = spawn('sh', ['-c', trimmedCmd], {
+            cwd: getToolWorkingDirectory()
+          });
+          const session = createShellSession(trimmedCmd, getToolWorkingDirectory(), proc);
+          let resolved = false;
+          let backgroundTimer = null;
+
+          const finish = (result) => {
+            if (resolved) return;
+            resolved = true;
+            if (backgroundTimer) {
+              clearTimeout(backgroundTimer);
+              backgroundTimer = null;
+            }
+            resolve(result);
+          };
+
+          if (backgroundEligible) {
+            backgroundTimer = setTimeout(() => {
+              if (resolved || session.completed) return;
+              session.backgrounded = true;
+              session.liveEchoEnabled = false;
+              showStreamPhase(`Shell command still running. Background session ${session.id} is active...`, 'warning');
+              finish(buildShellSessionResult(session, {
+                includeOutput: shellStreamToModelEnabled(),
+                onlyNewOutput: false,
+                markReported: shellStreamToModelEnabled(),
+                backgroundHandoff: true,
+              }));
+            }, shellBackgroundAfterSeconds() * 1000);
           }
-          // Delay slightly to let terminal settle
-          setTimeout(() => {
-            recreateReadline();
-            // Return actual output to AI, truncated if too long
-            const maxOutput = 10000;
-            let result = output.trim();
-            if (result.length > maxOutput) {
-              result = result.substring(0, maxOutput) + '\n... (output truncated)';
+
+          proc.stdout.on('data', (data) => { 
+            const text = data.toString();
+            appendShellSessionOutput(session, text);
+            if (session.liveEchoEnabled) {
+              process.stdout.write(text);
+            }
+          });
+          proc.stderr.on('data', (data) => { 
+            const text = data.toString();
+            appendShellSessionOutput(session, text);
+            if (session.liveEchoEnabled) {
+              process.stderr.write(text);
+            }
+          });
+          proc.on('error', (error) => {
+            session.completed = true;
+            session.error = error.message;
+            session.exitCode = 1;
+            pruneCompletedShellSessions();
+            finish(`Shell command failed to start: ${error.message}`);
+          });
+          proc.on('close', (code, signal) => {
+            session.completed = true;
+            session.exitCode = code;
+            session.signal = signal;
+            pruneCompletedShellSessions();
+
+            if (resolved) {
+              return;
+            }
+
+            if (process.stdin.isTTY) {
+              try { process.stdin.setRawMode(false); } catch (e) {}
             }
-            resolve(result || `Command completed with exit code ${code}`);
-          }, 200);
+
+            setTimeout(() => {
+              recreateReadline();
+              const maxOutput = 10000;
+              let result = session.output.trim();
+              if (result.length > maxOutput) {
+                result = result.substring(0, maxOutput) + '\n... (output truncated)';
+              }
+              finish(result || `Command completed with exit code ${code}`);
+            }, 200);
+          });
         });
+      }
+
+      if (['', 'n', 'no'].includes(confirm)) {
+        return "Command blocked by user.";
+      }
+
+      const approvalInstruction = await resolveApprovalInstruction(confirmRaw, {
+        feedbackPrompt: 'Feedback for this command: ',
+        editPrompt: 'Edit instruction for this command: ',
       });
+
+      if (approvalInstruction) {
+        if (!approvalInstruction.detail) {
+          console.log(UI.slate('Enter feedback or edit instructions for Sapper, or choose y/n.'));
+          continue;
+        }
+
+        const label = approvalInstruction.type === 'edit' ? 'User edit instruction' : 'User feedback';
+        return `Command blocked by user.\n${label}: ${approvalInstruction.detail}\nNo command was executed. Revise the command and ask again if needed.`;
+      }
+
+      return `Command blocked by user.\nUser feedback: ${confirmRaw}\nNo command was executed. Revise the command and ask again if needed.`;
     }
-    return "Command blocked by user.";
   },
   list: (path) => {
     try {
-      let dir = path.trim() || '.';
+      let dir = typeof path === 'string' ? path.trim() : '';
+      if (!dir) dir = '.';
       // If AI sends "/" (root), treat as current directory "."
       if (dir === '/') dir = '.';
-      const entries = fs.readdirSync(dir);
+      const entries = fs.readdirSync(resolveToolPath(dir));
       // Filter out ignored files/directories (respects .sapperignore)
       const filtered = entries.filter(entry => {
         if (shouldIgnore(entry)) return false;
@@ -2626,16 +4490,35 @@ const tools = {
       for (const { pattern: p, negate } of getSapperIgnorePatterns()) {
         if (!negate && p.endsWith('/')) allIgnoreDirs.add(p.replace(/\/+$/, ''));
       }
-      const excludeDirs = Array.from(allIgnoreDirs).join(',');
-      // Use grep to search for pattern, excluding ignored directories
-      const cmd = `grep -rEin "${pattern.replace(/"/g, '\\"')}" . --exclude-dir={${excludeDirs}} --include="*.{js,ts,jsx,tsx,py,java,go,rs,rb,php,c,cpp,h,css,scss,html,json,md,txt,yml,yaml,toml,sh}" 2>/dev/null | head -50`;
+      // Use grep with args array to avoid command injection
+      const args = ['-rEin', pattern, '.'];
+      for (const dir of allIgnoreDirs) {
+        args.push(`--exclude-dir=${dir}`);
+      }
+      args.push('--include=*.js', '--include=*.ts', '--include=*.jsx', '--include=*.tsx',
+        '--include=*.py', '--include=*.java', '--include=*.go', '--include=*.rs',
+        '--include=*.rb', '--include=*.php', '--include=*.c', '--include=*.cpp',
+        '--include=*.h', '--include=*.css', '--include=*.scss', '--include=*.html',
+        '--include=*.json', '--include=*.md', '--include=*.txt', '--include=*.yml',
+        '--include=*.yaml', '--include=*.toml', '--include=*.sh');
       
-      const proc = spawn('sh', ['-c', cmd], { cwd: process.cwd() });
+      const proc = spawn('grep', args, { cwd: getToolWorkingDirectory() });
       let output = '';
+      let lineCount = 0;
       
-      proc.stdout.on('data', (data) => { output += data.toString(); });
-      proc.stderr.on('data', (data) => { output += data.toString(); });
+      proc.stdout.on('data', (data) => {
+        const text = data.toString();
+        const lines = text.split('\n');
+        for (const line of lines) {
+          if (lineCount >= 50) { proc.kill(); return; }
+          if (line) { output += line + '\n'; lineCount++; }
+        }
+      });
+      proc.stderr.on('data', () => {}); // ignore stderr
       
+      proc.on('error', (err) => {
+        resolve(`Error searching: ${err.message}`);
+      });
       proc.on('close', () => {
         if (output.trim()) {
           resolve(`Found matches:\n${output.trim()}`);
@@ -2721,6 +4604,12 @@ async function runSapper() {
   const startupLines = [
     `${statusBadge('workspace', 'info')} ${chalk.white(`${workspaceFileCount} files`)} ${UI.slate('·')} ${chalk.white(`${workspaceSymbolCount} symbols`)} ${UI.slate('·')} ${UI.slate(`indexed ${workspaceAgeMinutes}m ago`)}`,
     `${statusBadge('memory', 'neutral')} ${chalk.white('.sapper/')} ${UI.slate('·')} ${UI.slate(`auto-attach ${sapperConfig.autoAttach ? 'on' : 'off'}`)}`,
+    `${statusBadge('prompt', hasCustomPromptConfig() ? 'warning' : 'neutral')} ${UI.slate(hasCustomPromptConfig() ? 'custom prompt on' : 'default prompt')}`,
+    `${statusBadge('thinking', 'neutral')} ${UI.slate(`mode ${thinkingMode()}`)}`,
+    `${statusBadge('tools', 'action')} ${UI.slate(`limit ${toolRoundLimit()} rounds`)}`,
+    `${statusBadge('shell', 'info')} ${UI.slate(`stream ${shellStreamToModelEnabled() ? 'on' : 'off'}`)} ${UI.slate('·')} ${UI.slate(`bg ${shellBackgroundMode()}`)} ${UI.slate('·')} ${UI.slate(`${activeShellSessionCount()} active`)}`,
+    `${statusBadge('stream', 'neutral')} ${UI.slate(`heartbeat ${streamHeartbeatEnabled() ? 'on' : 'off'}`)} ${UI.slate('·')} ${UI.slate(`phases ${streamPhaseStatusEnabled() ? 'on' : 'off'}`)}`,
+    `${statusBadge('summary', 'info')} ${UI.slate(`phases ${summaryPhasesEnabled() ? 'on' : 'off'}`)} ${UI.slate('·')} ${UI.slate(`trigger ${summaryTriggerPercent()}%`)}`,
     `${statusBadge('agents', 'action')} ${chalk.white(`${agentCount}`)} ${UI.slate('·')} ${statusBadge('skills', 'success')} ${chalk.white(`${skillCount}`)}`,
   ];
   if (newlyCreated > 0) {
@@ -2774,7 +4663,15 @@ async function runSapper() {
     process.exit(1);
   }
   
-  const selectedModel = await pickModel(localModels.models) || localModels.models[0].name;
+  // Use defaultModel from config if available and exists in local models
+  let selectedModel;
+  const configModel = sapperConfig.defaultModel;
+  if (configModel && localModels.models.some(m => m.name === configModel)) {
+    selectedModel = configModel;
+    console.log(UI.slate(`  Using configured model: ${configModel}`));
+  } else {
+    selectedModel = await pickModel(localModels.models) || localModels.models[0].name;
+  }
 
   // ─── Detect model capabilities & context window ───────────────────
   let useNativeTools = false;
@@ -2797,48 +4694,147 @@ async function runSapper() {
           break;
         }
       }
-    }
-    // Fallback: parse from parameters string (e.g. "num_ctx 4096")
-    if (!modelContextLength && modelInfo.parameters) {
-      const match = modelInfo.parameters.match(/num_ctx\s+(\d+)/);
-      if (match) modelContextLength = parseInt(match[1]);
-    }
-    if (modelContextLength) {
-      contextLabel = `${modelContextLength.toLocaleString()} tokens`;
-    } else {
-      modelContextLength = 4096; // Conservative default
-      contextLabel = '4,096 tokens (default)';
-    }
-  } catch (e) {
-    modelContextLength = 4096;
-    toolModeLabel = 'default mode';
-    contextLabel = '4,096 tokens (fallback)';
-  }
-  // Show custom limit if set
-  const effectiveCtx = effectiveContextLength();
-  if (sapperConfig.contextLimit && effectiveCtx !== modelContextLength) {
-    contextLabel = `${effectiveCtx.toLocaleString()} tokens (custom limit, model: ${modelContextLength.toLocaleString()})`;
-  }
-  console.log(box(
-    `${statusBadge('model', 'action')} ${chalk.white.bold(selectedModel)}\n` +
-    `${statusBadge('tools', useNativeTools ? 'success' : 'neutral')} ${UI.ink(toolModeLabel)}\n` +
-    `${statusBadge('context', 'info')} ${UI.ink(contextLabel)}`,
-    'Session', 'cyan'
-  ));
-  console.log();
-  _useNativeToolsFlag = useNativeTools; // Set global for buildSystemPrompt
-
-  // Native Ollama tool definitions (used when useNativeTools=true)
-  const nativeToolDefs = [
+    }
+    // Fallback: parse from parameters string (e.g. "num_ctx 4096")
+    if (!modelContextLength && modelInfo.parameters) {
+      const match = modelInfo.parameters.match(/num_ctx\s+(\d+)/);
+      if (match) modelContextLength = parseInt(match[1]);
+    }
+    if (modelContextLength) {
+      contextLabel = `${modelContextLength.toLocaleString()} tokens`;
+    } else {
+      modelContextLength = 4096; // Conservative default
+      contextLabel = '4,096 tokens (default)';
+    }
+  } catch (e) {
+    modelContextLength = 4096;
+    toolModeLabel = 'default mode';
+    contextLabel = '4,096 tokens (fallback)';
+  }
+  // Show custom limit if set
+  const effectiveCtx = effectiveContextLength();
+  if (sapperConfig.contextLimit && effectiveCtx !== modelContextLength) {
+    contextLabel = `${effectiveCtx.toLocaleString()} tokens (custom limit, model: ${modelContextLength.toLocaleString()})`;
+  }
+  console.log(box(
+    `${statusBadge('model', 'action')} ${chalk.white.bold(selectedModel)}\n` +
+    `${statusBadge('tools', useNativeTools ? 'success' : 'neutral')} ${UI.ink(toolModeLabel)}\n` +
+    `${statusBadge('context', 'info')} ${UI.ink(contextLabel)}`,
+    'Session', 'cyan'
+  ));
+  console.log();
+  _useNativeToolsFlag = useNativeTools; // Set global for buildSystemPrompt
+
+  // Native Ollama tool definitions (used when useNativeTools=true)
+  const nativeToolDefs = [
+    {
+      type: 'function',
+      function: {
+        name: 'list_directory',
+        description: 'List the contents of a directory. If path is omitted, use the current directory ".".',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Directory path to list' }
+          }
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'read_file',
+        description: 'Read the full contents of a file',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'File path to read' }
+          },
+          required: ['path']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'search_files',
+        description: 'Search for a pattern across project files',
+        parameters: {
+          type: 'object',
+          properties: {
+            pattern: { type: 'string', description: 'Search pattern (text or regex)' }
+          },
+          required: ['pattern']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'write_file',
+        description: 'Create or overwrite a file with new content',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'File path to write' },
+            content: { type: 'string', description: 'Content to write to the file' }
+          },
+          required: ['path', 'content']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'patch_file',
+        description: 'Edit an existing file by replacing old text with new text. Prefer line_number mode.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'File path to patch' },
+            old_text: { type: 'string', description: 'Exact text to find and replace, or LINE:<number> for line-number mode' },
+            new_text: { type: 'string', description: 'Replacement text' }
+          },
+          required: ['path', 'old_text', 'new_text']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'create_directory',
+        description: 'Create a directory (recursive)',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Directory path to create' }
+          },
+          required: ['path']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'ls',
+        description: 'List directory contents. If path is omitted, use the current tool working directory.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Directory path to list' }
+          }
+        }
+      }
+    },
     {
       type: 'function',
       function: {
-        name: 'list_directory',
-        description: 'List the contents of a directory. Use "." for current directory.',
+        name: 'cat',
+        description: 'Read the full contents of a file.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string', description: 'Directory path to list' }
+            path: { type: 'string', description: 'File path to read' }
           },
           required: ['path']
         }
@@ -2847,12 +4843,13 @@ async function runSapper() {
     {
       type: 'function',
       function: {
-        name: 'read_file',
-        description: 'Read the full contents of a file',
+        name: 'head',
+        description: 'Read the first lines of a file.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string', description: 'File path to read' }
+            path: { type: 'string', description: 'File path to read' },
+            lines: { type: 'number', description: 'How many lines to show (default 20)' }
           },
           required: ['path']
         }
@@ -2861,8 +4858,23 @@ async function runSapper() {
     {
       type: 'function',
       function: {
-        name: 'search_files',
-        description: 'Search for a pattern across project files',
+        name: 'tail',
+        description: 'Read the last lines of a file.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'File path to read' },
+            lines: { type: 'number', description: 'How many lines to show (default 20)' }
+          },
+          required: ['path']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'grep',
+        description: 'Search for matching text across project files.',
         parameters: {
           type: 'object',
           properties: {
@@ -2875,53 +4887,117 @@ async function runSapper() {
     {
       type: 'function',
       function: {
-        name: 'write_file',
-        description: 'Create or overwrite a file with new content',
+        name: 'find',
+        description: 'Find files or directories by name.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string', description: 'File path to write' },
-            content: { type: 'string', description: 'Content to write to the file' }
+            pattern: { type: 'string', description: 'Name fragment to search for' },
+            path: { type: 'string', description: 'Directory to search from (default current tool working directory)' }
           },
-          required: ['path', 'content']
+          required: ['pattern']
         }
       }
     },
     {
       type: 'function',
       function: {
-        name: 'patch_file',
-        description: 'Edit an existing file by replacing old text with new text. Prefer line_number mode.',
+        name: 'pwd',
+        description: 'Show the current tool working directory.',
+        parameters: {
+          type: 'object',
+          properties: {}
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'cd',
+        description: 'Change the tool working directory for later tool calls.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string', description: 'File path to patch' },
-            old_text: { type: 'string', description: 'Exact text to find and replace, or LINE:<number> for line-number mode' },
-            new_text: { type: 'string', description: 'Replacement text' }
+            path: { type: 'string', description: 'Directory path to switch to' }
           },
-          required: ['path', 'old_text', 'new_text']
+          required: ['path']
         }
       }
     },
     {
       type: 'function',
       function: {
-        name: 'create_directory',
-        description: 'Create a directory (recursive)',
+        name: 'rmdir',
+        description: 'Remove a directory recursively after approval.',
         parameters: {
           type: 'object',
           properties: {
-            path: { type: 'string', description: 'Directory path to create' }
+            path: { type: 'string', description: 'Directory path to remove' }
           },
           required: ['path']
         }
       }
     },
+    {
+      type: 'function',
+      function: {
+        name: 'changes',
+        description: 'Show git status and diffs for the current repository or an optional file/directory path.',
+        parameters: {
+          type: 'object',
+          properties: {
+            path: { type: 'string', description: 'Optional file or directory path to scope the diff output' }
+          }
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'fetch_web',
+        description: 'Fetch a web page and return readable text content.',
+        parameters: {
+          type: 'object',
+          properties: {
+            url: { type: 'string', description: 'URL to fetch, starting with http:// or https://' }
+          },
+          required: ['url']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'recall_memory',
+        description: 'Search Sapper\'s saved conversation memory for relevant prior context.',
+        parameters: {
+          type: 'object',
+          properties: {
+            query: { type: 'string', description: 'Memory search query' }
+          },
+          required: ['query']
+        }
+      }
+    },
+    {
+      type: 'function',
+      function: {
+        name: 'open_url',
+        description: 'Open a URL in the default browser after approval.',
+        parameters: {
+          type: 'object',
+          properties: {
+            url: { type: 'string', description: 'URL to open, usually http://, https://, or file:' }
+          },
+          required: ['url']
+        }
+      }
+    },
     {
       type: 'function',
       function: {
         name: 'run_shell',
-        description: 'Execute a shell command in the project directory',
+        description: 'Execute a shell command in the project directory. Special commands: __shell_list__, __shell_read__ <session_id>, __shell_stop__ <session_id>.',
         parameters: {
           type: 'object',
           properties: {
@@ -2940,6 +5016,20 @@ async function runSapper() {
     }];
   }
 
+  // Auto-load defaultAgent from config if set
+  if (!currentAgent && sapperConfig.defaultAgent) {
+    const agents = loadAgents();
+    const agentKey = sapperConfig.defaultAgent.toLowerCase();
+    if (agents[agentKey]) {
+      currentAgent = agentKey;
+      currentAgentTools = agents[agentKey].tools || null;
+      if (messages.length > 0 && messages[0]?.role === 'system') {
+        messages[0].content = buildSystemPrompt(agents[agentKey].content);
+      }
+      console.log(UI.slate(`  Using configured agent: ${agents[agentKey].name}`));
+    }
+  }
+
   // Log session start
   logEntry('session_start', {
     model: selectedModel,
@@ -2950,51 +5040,62 @@ async function runSapper() {
   // Main conversation loop - never exits unless user types 'exit'
   while (true) {
     try {
+      const previousConfig = JSON.stringify(sapperConfig);
+      const reloadedConfig = loadConfig();
+      if (JSON.stringify(reloadedConfig) !== previousConfig) {
+        sapperConfig = reloadedConfig;
+        if (messages.length > 0 && messages[0]?.role === 'system') {
+          refreshSystemPrompt(messages);
+        }
+        console.log(chalk.gray(`↻ Reloaded ${CONFIG_FILE}`));
+        console.log(chalk.gray('   System prompt and runtime settings refreshed from config.'));
+      }
+
       // Context size check - auto-summarize when approaching effective context limit
-      const estimatedTokens = estimateMessagesTokens(messages);
+      let estimatedTokens = estimateMessagesTokens(messages);
       const ctxLen = effectiveContextLength();
-      const tokenThreshold = ctxLen ? Math.floor(ctxLen * 0.75) : 8000;
+      const tokenThreshold = summaryTokenThreshold(ctxLen);
       if (estimatedTokens > tokenThreshold) {
         messages = await autoSummarizeContext(messages, selectedModel);
+        estimatedTokens = estimateMessagesTokens(messages);
       }
       
       // Build prompt label with active agent/skills
       const contextPercent = ctxLen ? Math.round((estimatedTokens / ctxLen) * 100) : null;
       const promptParts = [
         statusBadge(selectedModel.split(':')[0] || selectedModel, 'action'),
-        currentAgent ? statusBadge(`/${currentAgent}`, 'info') : statusBadge('default', 'neutral'),
+        activeAgentPromptBadge(),
       ];
-      if (loadedSkills.length > 0) {
-        promptParts.push(statusBadge(`${loadedSkills.length} skill${loadedSkills.length !== 1 ? 's' : ''}`, 'success'));
+      const skillsBadge = activeSkillsPromptBadge();
+      if (skillsBadge) {
+        promptParts.push(skillsBadge);
       }
       if (contextPercent !== null) {
         const tone = contextPercent >= 85 ? 'error' : contextPercent >= 65 ? 'warning' : 'neutral';
         promptParts.push(statusBadge(`${contextPercent}% ctx`, tone));
       }
 
-      const promptDetail = ctxLen
+      const promptDetailLines = [ctxLen
         ? `${meter(estimatedTokens, ctxLen, 24)} ${UI.slate(`${estimatedTokens.toLocaleString()}/${ctxLen.toLocaleString()} tokens`)}`
-        : UI.slate(`${estimatedTokens.toLocaleString()} estimated tokens`);
+        : UI.slate(`${estimatedTokens.toLocaleString()} estimated tokens`)
+      ];
+      const modeSummary = activeModeSummary({ includeAgent: true, maxSkills: 3 });
+      if (modeSummary) {
+        promptDetailLines.push(UI.slate(modeSummary));
+      }
+      const promptDetail = promptDetailLines.join('\n');
 
-      const input = await safeQuestion(`\n${promptShell(promptParts.join(' '), promptDetail)}`);
+      const promptText = `\n${promptShell(promptParts.join(' '), promptDetail)}`;
+      const input = await safeQuestion(promptText);
+      clearPromptEcho(promptText, input);
       
       // Block empty prompts
       if (!input.trim()) {
         continue;
       }
 
-      // Clear readline echo to prevent duplicate display
-      {
-        const promptWidth = visibleLength(promptParts.join(' ')) + 4; // account for prompt chars
-        const totalLen = promptWidth + input.length;
-        const lines = Math.ceil(totalLen / (process.stdout.columns || 80));
-        for (let i = 0; i < lines; i++) {
-          process.stdout.write('\x1B[1A\x1B[2K');
-        }
-        // Reprint clean version
-        const preview = input.length > 120 ? input.substring(0, 120) + chalk.gray('...') : input;
-        console.log(UI.accent('› ') + chalk.white(preview));
-      }
+      const preview = input.length > LIMITS.INPUT_PREVIEW_CHARS ? input.substring(0, LIMITS.INPUT_PREVIEW_CHARS) + chalk.gray('...') : input;
+      console.log(UI.accent('› ') + chalk.white(preview));
       
       if (input.toLowerCase() === 'exit') {
         const stats = getSessionStats();
@@ -3056,7 +5157,11 @@ async function runSapper() {
         console.log(commandRow('/fetch <url>', 'Fetch a web page into context'));
         console.log(commandRow('/reset /clear', 'Clear all current context'));
         console.log(commandRow('/prune', 'Summarize long context and store memory'));
-        console.log(commandRow('/context', 'Inspect token usage and model window'));
+        console.log(commandRow('/summary', 'Show or change auto-summary settings'));
+        console.log(commandRow('/shell', 'Inspect shell config and background sessions'));
+        console.log(commandRow('/shell read <id>', 'Read output from a tracked shell session'));
+        console.log(commandRow('/shell stop <id>', 'Stop a tracked shell session'));
+        console.log(commandRow('/context', 'Inspect token usage, summary trigger, and model window'));
         console.log(commandRow('/ctx <limit>', 'Set context window limit (e.g. /ctx 64k)'));
         console.log(commandRow('/debug', 'Toggle regex and tool debug output'));
         console.log(commandRow('/log', 'Show the session activity timeline'));
@@ -3064,6 +5169,13 @@ async function runSapper() {
         console.log(commandRow('/log file', 'Show log file path and history'));
         console.log(commandRow('/help', 'Open this command view again'));
         console.log(commandRow('exit', 'Quit Sapper'));
+        console.log(UI.slate('  Summary settings: /summary  |  /summary phases off  |  /summary trigger 60'));
+        console.log(UI.slate('  Tool config: .sapper/config.json -> toolRoundLimit (default 40)'));
+        console.log(UI.slate('  Shell config: .sapper/config.json -> shell.streamToModel, shell.backgroundMode [off|auto|on], shell.backgroundAfterSeconds, shell.outputChunkChars'));
+        console.log(UI.slate('  Want to see all live shell output? Set shell.backgroundMode to off. thinking.mode only controls model reasoning.'));
+        console.log(UI.slate('  Streaming config: .sapper/config.json -> streaming.showPhaseStatus, streaming.showHeartbeat, streaming.idleNoticeSeconds'));
+        console.log(UI.slate('  Thinking config: .sapper/config.json -> thinking.mode [auto|on|off]'));
+        console.log(UI.slate('  Prompt config: .sapper/config.json -> prompt.prepend, prompt.append, prompt.coreOverride'));
         console.log();
         console.log(sectionTitle('Agents', 'specialist modes and skills', 'cyan'));
         console.log(commandRow('/agents', 'List available agents'));
@@ -3141,8 +5253,8 @@ async function runSapper() {
           console.log(`     ${chalk.gray(sym.file)}:${chalk.cyan(sym.line)}`);
         }
         
-        if (results.length > 15) {
-          console.log(chalk.gray(`\n   ... and ${results.length - 15} more`));
+        if (results.length > LIMITS.SYMBOL_RESULTS_MAX) {
+          console.log(chalk.gray(`\n   ... and ${results.length - LIMITS.SYMBOL_RESULTS_MAX} more`));
         }
         
         // Offer to add file to context
@@ -3211,7 +5323,7 @@ async function runSapper() {
             let contextContent = `\n📄 ${matchingFile}:\n`;
             contextContent += fs.readFileSync(matchingFile, 'utf8');
             
-            for (const relFile of related.slice(0, 5)) { // Limit to 5 related
+            for (const relFile of related.slice(0, LIMITS.WORKSPACE_RELATED_DEPTH)) { // Limit to N related
               try {
                 contextContent += `\n\n📄 ${relFile} (related):\n`;
                 contextContent += fs.readFileSync(relFile, 'utf8');
@@ -3288,20 +5400,112 @@ async function runSapper() {
         continue;
       }
 
+      if (input.toLowerCase().startsWith('/summary')) {
+        const arg = input.substring(8).trim();
+
+        if (!arg) {
+          const effective = effectiveContextLength();
+          const threshold = summaryTokenThreshold(effective);
+          const lines = [
+            `phases        ${summaryPhasesEnabled() ? chalk.green('ON') : chalk.red('OFF')}`,
+            `trigger       ${chalk.white.bold(summaryTriggerPercent() + '%')} ${UI.slate(`(~${threshold.toLocaleString()} tokens)`)}`,
+            `config file   ${chalk.white(CONFIG_FILE)}`,
+          ];
+          console.log();
+          console.log(box(lines.join('\n'), 'Summary Settings', 'cyan'));
+          console.log(UI.slate('  Usage: /summary phases [on|off]  |  /summary trigger <percent>  |  /summary reset'));
+          continue;
+        }
+
+        const [subcommandRaw, ...rest] = arg.split(/\s+/);
+        const subcommand = subcommandRaw.toLowerCase();
+        const value = rest.join(' ').trim();
+
+        if (subcommand === 'reset' || subcommand === 'default') {
+          sapperConfig.summaryPhases = DEFAULT_CONFIG.summaryPhases;
+          sapperConfig.summarizeTriggerPercent = DEFAULT_CONFIG.summarizeTriggerPercent;
+          saveConfig(sapperConfig);
+          console.log(chalk.green(`✅ Summary settings reset: phases ${summaryPhasesEnabled() ? 'ON' : 'OFF'}, trigger ${summaryTriggerPercent()}%`));
+          continue;
+        }
+
+        if (subcommand === 'phases' || subcommand === 'phase') {
+          let nextValue = null;
+
+          if (!value) {
+            nextValue = !summaryPhasesEnabled();
+          } else {
+            const normalized = value.toLowerCase();
+            if (['on', 'true', 'yes', '1', 'enable', 'enabled'].includes(normalized)) {
+              nextValue = true;
+            } else if (['off', 'false', 'no', '0', 'disable', 'disabled'].includes(normalized)) {
+              nextValue = false;
+            } else if (['toggle', 'flip'].includes(normalized)) {
+              nextValue = !summaryPhasesEnabled();
+            }
+          }
+
+          if (nextValue === null) {
+            console.log(chalk.yellow('Usage: /summary phases [on|off]'));
+            continue;
+          }
+
+          sapperConfig.summaryPhases = nextValue;
+          saveConfig(sapperConfig);
+          console.log(chalk.green(`✅ Summary phases: ${summaryPhasesEnabled() ? chalk.green('ON') : chalk.red('OFF')}`));
+          continue;
+        }
+
+        if (subcommand === 'trigger' || subcommand === 'percent' || subcommand === 'threshold') {
+          if (!value) {
+            console.log(chalk.yellow('Usage: /summary trigger <percent>'));
+            console.log(chalk.gray('  Examples: /summary trigger 65, /summary trigger 70%, /summary trigger 0.6'));
+            continue;
+          }
+
+          const parsedTrigger = parseSummaryTriggerInput(value);
+          if (parsedTrigger === null) {
+            console.log(chalk.yellow(`Invalid summary trigger: ${value}`));
+            console.log(chalk.gray('  Examples: /summary trigger 65, /summary trigger 70%, /summary trigger 0.6'));
+            continue;
+          }
+
+          sapperConfig.summarizeTriggerPercent = parsedTrigger;
+          saveConfig(sapperConfig);
+          const effective = effectiveContextLength();
+          const threshold = summaryTokenThreshold(effective);
+          console.log(chalk.green(`✅ Summary trigger set to ${chalk.white.bold(summaryTriggerPercent() + '%')}`));
+          console.log(chalk.gray(`   Auto-summary will start near ${threshold.toLocaleString()} tokens.`));
+          continue;
+        }
+
+        console.log(chalk.yellow(`Unknown summary option: ${subcommand}`));
+        console.log(chalk.gray('  Usage: /summary  |  /summary phases [on|off]  |  /summary trigger <percent>  |  /summary reset'));
+        continue;
+      }
+
       if (input.toLowerCase() === '/context') {
         const contextSize = JSON.stringify(messages).length;
         const estTokens = estimateMessagesTokens(messages);
         const ctxLen = effectiveContextLength();
+        const triggerPercent = summaryTriggerPercent();
+        const promptConfig = getPromptConfig();
         const contextLines = [
           `messages ${chalk.white(String(messages.length))} ${UI.slate('·')} raw ${chalk.white(Math.round(contextSize / 1024) + 'KB')} ${UI.slate('·')} tokens ${chalk.white('~' + estTokens.toLocaleString())}`,
         ];
+        contextLines.push(`prompt ${chalk.white(hasCustomPromptConfig() ? 'customized' : 'default')} ${UI.slate('·')} ${chalk.white(`prepend ${promptConfig.prepend.trim() ? 'yes' : 'no'}`)} ${UI.slate('·')} ${chalk.white(`append ${promptConfig.append.trim() ? 'yes' : 'no'}`)}`);
+        contextLines.push(`thinking ${chalk.white(thinkingMode())} ${UI.slate('·')} ${UI.slate(thinkingMode() === 'auto' ? 'simple prompts skip reasoning' : thinkingMode() === 'off' ? 'reasoning hidden for all prompts' : 'reasoning enabled for all prompts')}`);
+        contextLines.push(`tools ${chalk.white(`limit ${toolRoundLimit()} rounds`)} ${UI.slate('·')} ${UI.slate('per prompt turn')}`);
+        contextLines.push(`shell ${chalk.white(shellStreamToModelEnabled() ? 'stream on' : 'stream off')} ${UI.slate('·')} ${chalk.white(`bg ${shellBackgroundMode()}`)} ${UI.slate('·')} ${chalk.white(`after ${shellBackgroundAfterSeconds()}s`)} ${UI.slate('·')} ${chalk.white(`${activeShellSessionCount()} active`)}`);
+        contextLines.push(`stream ${chalk.white(streamHeartbeatEnabled() ? 'heartbeat on' : 'heartbeat off')} ${UI.slate('·')} ${chalk.white(streamPhaseStatusEnabled() ? 'phase status on' : 'phase status off')} ${UI.slate('·')} ${chalk.white(`idle ${streamIdleNoticeSeconds()}s`)}`);
         if (ctxLen) {
           const usagePercent = Math.round((estTokens / ctxLen) * 100);
-          const threshold = Math.floor(ctxLen * 0.75);
+          const threshold = summaryTokenThreshold(ctxLen);
           const limitLabel = sapperConfig.contextLimit
             ? `${ctxLen.toLocaleString()} tokens ${chalk.cyan('(custom)')}`
             : `${ctxLen.toLocaleString()} tokens`;
           contextLines.push(`limit ${chalk.white(limitLabel)} ${UI.slate('·')} usage ${chalk.white(usagePercent + '%')}`);
+          contextLines.push(`summary ${chalk.white(`trigger ${triggerPercent}%`)} ${UI.slate('·')} ${chalk.white(summaryPhasesEnabled() ? 'phases on' : 'phases off')}`);
           contextLines.push(`${meter(estTokens, ctxLen, 28)} ${UI.slate(`summarize near ${threshold.toLocaleString()} tokens`)}`);
         }
         if (lastPromptTokens > 0) {
@@ -3311,6 +5515,38 @@ async function runSapper() {
         console.log(box(contextLines.join('\n'), 'Context', 'gray'));
         continue;
       }
+
+      if (input.toLowerCase().startsWith('/shell')) {
+        const arg = input.substring(6).trim();
+
+        if (!arg || ['sessions', 'session', 'list', 'ls', 'status'].includes(arg.toLowerCase())) {
+          console.log();
+          console.log(renderShellSessionsPanel());
+          console.log(UI.slate('  Usage: /shell  |  /shell sessions  |  /shell read <session_id>  |  /shell stop <session_id>'));
+          continue;
+        }
+
+        const [subcommandRaw, ...rest] = arg.split(/\s+/);
+        const subcommand = subcommandRaw.toLowerCase();
+        const sessionId = rest.join(' ').trim();
+
+        if (['read', 'show', 'tail'].includes(subcommand)) {
+          const result = await handleShellSessionCommand(`__shell_read__ ${sessionId}`);
+          console.log();
+          console.log(box(String(result), sessionId ? `Shell ${sessionId}` : 'Shell Read', 'cyan'));
+          continue;
+        }
+
+        if (['stop', 'kill', 'end'].includes(subcommand)) {
+          const result = await handleShellSessionCommand(`__shell_stop__ ${sessionId}`);
+          console.log();
+          console.log(box(String(result), sessionId ? `Shell ${sessionId}` : 'Shell Stop', 'red'));
+          continue;
+        }
+
+        console.log(chalk.yellow('Usage: /shell  |  /shell sessions  |  /shell read <session_id>  |  /shell stop <session_id>'));
+        continue;
+      }
       
       // Handle debug mode toggle
       if (input.toLowerCase() === '/debug') {
@@ -3340,14 +5576,14 @@ async function runSapper() {
             const logFiles = fs.readdirSync(LOGS_DIR).filter(f => f.endsWith('.md')).sort().reverse();
             if (logFiles.length > 0) {
               console.log(chalk.cyan(`\n📋 All session logs:`));
-              logFiles.slice(0, 10).forEach((f, i) => {
+              logFiles.slice(0, LIMITS.LOG_FILES_DISPLAY_MAX).forEach((f, i) => {
                 const stats = fs.statSync(`${LOGS_DIR}/${f}`);
                 const isCurrent = f === `session-${sessionId}.md`;
                 const label = isCurrent ? chalk.green(' ← current') : '';
                 console.log(chalk.gray(`   ${i + 1}. `) + chalk.white(f) + chalk.gray(` (${Math.round(stats.size / 1024)}KB)`) + label);
               });
-              if (logFiles.length > 10) {
-                console.log(chalk.gray(`   ... and ${logFiles.length - 10} more`));
+              if (logFiles.length > LIMITS.LOG_FILES_DISPLAY_MAX) {
+                console.log(chalk.gray(`   ... and ${logFiles.length - LIMITS.LOG_FILES_DISPLAY_MAX} more`));
               }
             }
           } catch (e) {}
@@ -3447,6 +5683,7 @@ async function runSapper() {
         const agentMd = `---\nname: "${agentTitle}"\ndescription: "${description || agentTitle + ' assistant'}"\ntools: [read, edit, write, list, search, shell]\n---\n\n# ${agentTitle}\n\nYou are a ${agentTitle} AI assistant working within Sapper.\n${description ? `Your role: ${description}\n` : ''}\nAdapt your responses to match this role. Use Sapper's tools (file read/write, shell commands, search) when needed to assist the user.\n`;
         
         fs.writeFileSync(agentFile, agentMd);
+        invalidateLoaderCache('agents');
         console.log(chalk.green(`\n✅ Agent "${agentName}" created!`));
         console.log(chalk.gray(`   File: ${agentFile}`));
         console.log(chalk.cyan(`   Use it: /${agentName} <your prompt>`));
@@ -3568,13 +5805,14 @@ async function runSapper() {
         const agentTitle = await safeQuestion(chalk.cyan('Agent title/role: '));
         const agentExpertise = await safeQuestion(chalk.cyan('Areas of expertise (comma-separated): '));
         const agentStyle = await safeQuestion(chalk.cyan('Communication style (e.g., professional, casual, technical): '));
-        const agentToolsInput = await safeQuestion(chalk.cyan('Allowed tools (comma-sep, or Enter for all): ') + chalk.gray('read,edit,write,list,search,shell: '));
+        const agentToolsInput = await safeQuestion(chalk.cyan('Allowed tools (comma-sep, or Enter for all): ') + chalk.gray('read,edit,write,list,ls,search,grep,find,shell,mkdir,rmdir,pwd,cd,cat,head,tail,changes,fetch,memory,open: '));
         
         const expertiseList = agentExpertise.split(',').map(e => `- ${e.trim()}`).join('\n');
         const toolsLine = agentToolsInput.trim() ? `tools: [${agentToolsInput.trim()}]` : 'tools: [read, edit, write, list, search, shell]';
         const agentMd = `---\nname: "${agentTitle.trim() || agentName}"\ndescription: "${agentExpertise.trim() || agentTitle.trim() || agentName}"\n${toolsLine}\n---\n\n# ${agentTitle.trim() || agentName}\n\nYou are a ${agentTitle.trim() || agentName} AI assistant working within Sapper.\n\n## Your Expertise\n${expertiseList}\n\n## Communication Style\n${agentStyle.trim() || 'Professional and helpful'}.\n\nWhen the user asks for help, leverage your expertise and Sapper's tools to provide comprehensive assistance.\n`;
         
         fs.writeFileSync(agentFile, agentMd);
+        invalidateLoaderCache('agents');
         console.log(chalk.green(`\n✅ Agent "${agentName}" created!`));
         console.log(chalk.gray(`   File: ${agentFile}`));
         console.log(chalk.cyan(`   Use it: /${agentName} <your prompt>`));
@@ -3615,6 +5853,7 @@ async function runSapper() {
           : `---\nname: ${skillTitle.trim() || skillName}\ndescription: "${descLine}"${argHintLine}\n---\n\n# ${skillTitle.trim() || skillName}\n\nBest practices and knowledge for ${skillTitle.trim() || skillName}:\n- [Add your knowledge points here]\n- [Add patterns and conventions]\n- [Add common solutions]\n\n## Commands Reference\n| User says | Action |\n|-----------|--------|\n| "example command" | What the AI should do |\n\n## Procedures\n- [Add step-by-step procedures here]\n`;
         
         fs.writeFileSync(skillFile, skillMd);
+        invalidateLoaderCache('skills');
         console.log(chalk.green(`\n✅ Skill "${skillName}" created!`));
         console.log(chalk.gray(`   File: ${skillFile}`));
         console.log(chalk.cyan(`   Load it: /use ${skillName}`));
@@ -3732,7 +5971,7 @@ async function runSapper() {
           console.log(chalk.green(`Found ${relevant.length} relevant memories:\n`));
           relevant.forEach((chunk, i) => {
             console.log(box(
-              chalk.gray(chunk.text.substring(0, 300) + '...') + '\n' +
+              chalk.gray(chunk.text.substring(0, LIMITS.MEMORY_PREVIEW_CHARS) + '...') + '\n' +
               chalk.cyan(`Similarity: ${(chunk.score * 100).toFixed(1)}%`),
               `Memory ${i + 1}`, 'magenta'
             ));
@@ -3802,12 +6041,12 @@ async function runSapper() {
               continue;
             }
             const stats = fs.statSync(filePath);
-            if (stats.size > MAX_FILE_SIZE) {
+            if (stats.size > getMaxFileSize()) {
               console.log(chalk.red.bold(`\n╔══════════════════════════════════════════════════════════╗`));
               console.log(chalk.red.bold(`║  ⛔ FILE TOO LARGE — Cannot attach                       ║`));
               console.log(chalk.red.bold(`╚══════════════════════════════════════════════════════════╝`));
               console.log(chalk.yellow(`   File: ${filePath}`));
-              console.log(chalk.yellow(`   Size: ${Math.round(stats.size/1024)}KB (limit: ${Math.round(MAX_FILE_SIZE/1024)}KB)`));
+              console.log(chalk.yellow(`   Size: ${Math.round(stats.size/1024)}KB (limit: ${Math.round(getMaxFileSize()/1024)}KB)`));
               console.log(chalk.gray(`   Tip: Use a smaller file or increase limit in .sapper/config.json\n`));
               continue;
             }
@@ -3831,16 +6070,7 @@ async function runSapper() {
         }
         
         // Build message with attachments
-        let attachedContent = '\n\n══════════════════════════════════════\n';
-        attachedContent += `📎 ATTACHED FILES (${fileAttachments.length})\n`;
-        attachedContent += '══════════════════════════════════════\n\n';
-        
-        for (const file of fileAttachments) {
-          attachedContent += `┌─── ${file.path} ───\n`;
-          attachedContent += file.content;
-          if (!file.content.endsWith('\n')) attachedContent += '\n';
-          attachedContent += `└─── END ${file.path} ───\n\n`;
-        }
+        const attachedContent = formatFileAttachments(fileAttachments);
         
         messages.push({ role: 'user', content: prompt + attachedContent });
         // Continue to AI response (don't use 'continue' here)
@@ -3862,11 +6092,11 @@ async function runSapper() {
             }
             const stats = fs.statSync(filePath);
             if (stats.isFile()) {
-              if (stats.size > MAX_FILE_SIZE) {
+              if (stats.size > getMaxFileSize()) {
                 console.log(chalk.red.bold(`\n╔══════════════════════════════════════════════════════════╗`));
                 console.log(chalk.red.bold(`║  ⛔ FILE TOO LARGE — Cannot attach @${filePath.padEnd(22).slice(0, 22)}║`));
                 console.log(chalk.red.bold(`╚══════════════════════════════════════════════════════════╝`));
-                console.log(chalk.yellow(`   Size: ${Math.round(stats.size/1024)}KB — exceeds ${Math.round(MAX_FILE_SIZE/1024)}KB limit`));
+                console.log(chalk.yellow(`   Size: ${Math.round(stats.size/1024)}KB — exceeds ${Math.round(getMaxFileSize()/1024)}KB limit`));
                 console.log(chalk.gray(`   Tip: Use a smaller file or increase limit in .sapper/config.json\n`));
               } else {
                 const content = fs.readFileSync(filePath, 'utf8');
@@ -3880,7 +6110,7 @@ async function runSapper() {
                   try {
                     if (!fileAttachments.some(f => f.path === relFile)) {
                       const relStats = fs.statSync(relFile);
-                      if (relStats.size <= MAX_FILE_SIZE) {
+                      if (relStats.size <= getMaxFileSize()) {
                         const relContent = fs.readFileSync(relFile, 'utf8');
                         fileAttachments.push({ path: relFile, content: relContent, size: relStats.size, related: true });
                         console.log(chalk.gray(`   ↳ +${relFile} (related)`));
@@ -3901,16 +6131,7 @@ async function runSapper() {
       
       // Build the final message with attachments
       if (fileAttachments.length > 0) {
-        let attachedContent = '\n\n══════════════════════════════════════\n';
-        attachedContent += `📎 ATTACHED FILES (${fileAttachments.length})\n`;
-        attachedContent += '══════════════════════════════════════\n\n';
-        
-        for (const file of fileAttachments) {
-          attachedContent += `┌─── ${file.path} ───\n`;
-          attachedContent += file.content;
-          if (!file.content.endsWith('\n')) attachedContent += '\n';
-          attachedContent += `└─── END ${file.path} ───\n\n`;
-        }
+        const attachedContent = formatFileAttachments(fileAttachments);
         
         processedInput = input + attachedContent;
       }
@@ -3981,9 +6202,28 @@ async function runSapper() {
       } // End of if (!agentHandled)
 
       let toolRounds = 0; // Prevent infinite loops
-      const MAX_TOOL_ROUNDS = 20;
+      const MAX_TOOL_ROUNDS = toolRoundLimit();
       const patchFailures = {}; // Track consecutive PATCH failures per file: { path: count }
-      const MAX_PATCH_RETRIES = 3;
+      const MAX_PATCH_RETRIES = getPatchRetries();
+
+      // Unified patch-with-retry logic used by both native and text-marker tool handlers
+      async function patchWithRetry(filePath, oldText, newText) {
+        const key = filePath.trim();
+        if (patchFailures[key] >= MAX_PATCH_RETRIES) {
+          return { result: `Error: PATCH failed ${MAX_PATCH_RETRIES} times on ${key}. STOP retrying PATCH on this file. Instead, READ the file to see exact content, then use LINE:number mode or WRITE to rewrite the file.`, success: false };
+        }
+        const result = await tools.patch(filePath, oldText, newText);
+        if (result.includes('Successfully')) {
+          patchFailures[key] = 0;
+          return { result, success: true };
+        }
+        if (result.startsWith('Error:')) {
+          patchFailures[key] = (patchFailures[key] || 0) + 1;
+          return { result: result + `\n(Attempt ${patchFailures[key]}/${MAX_PATCH_RETRIES})`, success: false };
+        }
+        return { result, success: true };
+      }
+      const turnThinkingEnabled = shouldUseThinkingForInput(input);
       
       let active = true;
       while (active) {
@@ -3998,17 +6238,20 @@ async function runSapper() {
           if (effectiveContextLength()) {
             chatOpts.options = { num_ctx: effectiveContextLength() };
           }
-          // Enable thinking for reasoning models (deepseek-r1, qwq, etc.)
-          chatOpts.think = true;
+          // Thinking can be forced on, forced off, or auto-disabled for simple prompts.
+          chatOpts.think = turnThinkingEnabled;
           if (useNativeTools) {
             // Filter tool defs by agent restrictions if any
             if (currentAgentTools) {
               const toolNameMap = {
                 list_directory: 'LIST', read_file: 'READ', search_files: 'SEARCH',
-                write_file: 'WRITE', patch_file: 'PATCH', create_directory: 'MKDIR', run_shell: 'SHELL'
+                write_file: 'WRITE', patch_file: 'PATCH', create_directory: 'MKDIR',
+                ls: 'LS', cat: 'CAT', head: 'HEAD', tail: 'TAIL', grep: 'GREP', find: 'FIND',
+                pwd: 'PWD', cd: 'CD', rmdir: 'RMDIR', changes: 'CHANGES',
+                fetch_web: 'FETCH', recall_memory: 'MEMORY', open_url: 'OPEN', run_shell: 'SHELL'
               };
               chatOpts.tools = nativeToolDefs.filter(t => 
-                currentAgentTools.includes(toolNameMap[t.function.name])
+                isToolAllowedForAgent(currentAgentTools, toolNameMap[t.function.name])
               );
             } else {
               chatOpts.tools = nativeToolDefs;
@@ -4026,7 +6269,7 @@ async function runSapper() {
 
         let msg = '';
         let thinkMsg = ''; // Thinking/reasoning content from thinking models
-        const MAX_RESPONSE_LENGTH = 100000; // 100KB - allow long code generation
+        const MAX_RESPONSE_LENGTH = LIMITS.MAX_RESPONSE_LENGTH;
         let lastChunkTime = Date.now();
         let repetitionCount = 0;
         let lastContent = '';
@@ -4037,10 +6280,55 @@ async function runSapper() {
         let chunkPromptTokens = 0; // Track actual tokens from Ollama
         let chunkEvalTokens = 0;
         let isThinking = false; // Track if we're currently in thinking mode
+        let thinkingContinuationNeedsPrefix = false;
+        let lastThinkingIdleNoticeAt = 0;
         const genStartTime = Date.now(); // Track generation elapsed time
         let genTokenCount = 0; // Count response tokens as they stream
+        let lastVisibleActivityAt = Date.now();
+        let heartbeatInterval = null;
         
-        console.log(sectionTitle('Sapper', selectedModel, 'cyan'));
+        const activeAgent = getActiveAgentMeta();
+        const responseTitle = activeAgent ? activeAgent.name || currentAgent : 'Sapper';
+        const responseSubtitleParts = [selectedModel];
+        if (activeAgent && currentAgent) {
+          responseSubtitleParts.push(`/${currentAgent}`);
+        }
+        console.log(sectionTitle(responseTitle, responseSubtitleParts.join(' · '), activeAgent ? 'magenta' : 'cyan'));
+        const responseModeSummary = activeModeSummary({ includeAgent: !activeAgent, maxSkills: 4 });
+        if (responseModeSummary) {
+          console.log(UI.slate(responseModeSummary));
+        }
+        const MAX_THINKING_IDLE_SECONDS = 300; // Abort if model stalls in thinking >5min
+        if (streamHeartbeatEnabled()) {
+          heartbeatInterval = setInterval(() => {
+            if (abortStream) return;
+
+            if (isThinking) {
+              const idleSeconds = Math.max(0, Math.floor((Date.now() - lastVisibleActivityAt) / 1000));
+              const idleThreshold = streamIdleNoticeSeconds();
+              if (idleSeconds >= MAX_THINKING_IDLE_SECONDS) {
+                process.stdout.write(`\n${UI.slate('  │ ')}${chalk.yellow(`⚠ thinking stalled ${idleSeconds}s — aborting stream`)}\n`);
+                abortStream = true;
+                return;
+              }
+              if (idleSeconds >= idleThreshold && Date.now() - lastThinkingIdleNoticeAt >= 5000) {
+                process.stdout.write(`\n${UI.slate('  │ ')}${UI.slate.italic(`... waiting ${idleSeconds}s for more reasoning`)}\n`);
+                thinkingContinuationNeedsPrefix = true;
+                lastThinkingIdleNoticeAt = Date.now();
+              }
+              return;
+            }
+
+            renderStreamingHeartbeat({
+              genTokenCount,
+              genStartTime,
+              lastVisibleActivityAt,
+              stage: genTokenCount > 0 ? 'generating' : 'waiting-first',
+            });
+          }, 1000);
+        }
+        let streamErrored = null;
+        try {
         for await (const chunk of response) {
           // Check if user pressed Ctrl+C
           if (abortStream) {
@@ -4059,10 +6347,13 @@ async function runSapper() {
             // Live-stream thinking — dim italic, wrap at line breaks
             const lines = thinking.split('\n');
             for (let li = 0; li < lines.length; li++) {
-              if (li > 0) process.stdout.write(`\n${UI.slate('  │ ')}`);
+              if (li > 0 || thinkingContinuationNeedsPrefix) process.stdout.write(`\n${UI.slate('  │ ')}`);
+              thinkingContinuationNeedsPrefix = false;
               process.stdout.write(UI.slate.italic(lines[li]));
             }
             thinkMsg += thinking;
+            lastVisibleActivityAt = Date.now();
+            lastThinkingIdleNoticeAt = 0;
           }
           
           const content = chunk.message.content;
@@ -4073,10 +6364,13 @@ async function runSapper() {
             }
             msg += content;
             genTokenCount++;
-            // Show live progress with timer, tokens, and interrupt hint
-            const elapsed = ((Date.now() - genStartTime) / 1000).toFixed(1);
-            const tps = genTokenCount / Math.max((Date.now() - genStartTime) / 1000, 0.1);
-            process.stdout.write(`\r  ${UI.slate(`Generating... ${genTokenCount} tokens · ${elapsed}s · ${tps.toFixed(1)} t/s`)}  ${UI.slate.italic('Ctrl+C to stop')}`);
+            lastVisibleActivityAt = Date.now();
+            renderStreamingHeartbeat({
+              genTokenCount,
+              genStartTime,
+              lastVisibleActivityAt,
+              stage: 'generating',
+            });
           }
           
           // Capture token stats from the final chunk (done: true)
@@ -4089,14 +6383,14 @@ async function runSapper() {
           }
           
           // Smart loop detection: check for repetitive content patterns
-          if (msg.length > 10000) {
-            const recentContent = msg.slice(-500);
-            const previousContent = msg.slice(-1000, -500);
+          if (msg.length > LIMITS.REPETITION_THRESHOLD) {
+            const recentContent = msg.slice(-LIMITS.REPETITION_WINDOW);
+            const previousContent = msg.slice(-LIMITS.REPETITION_WINDOW * 2, -LIMITS.REPETITION_WINDOW);
             
             // If last 500 chars are very similar to previous 500, might be looping
             if (recentContent === previousContent) {
               repetitionCount++;
-              if (repetitionCount > 3) {
+              if (repetitionCount > LIMITS.REPETITION_COUNT) {
                 console.log(chalk.red('\n\n⚠️ REPETITIVE OUTPUT DETECTED: Stopping to prevent loop.'));
                 wasRepetitionStopped = true;
                 break;
@@ -4112,9 +6406,34 @@ async function runSapper() {
             // Don't break - just warn. User can Ctrl+C if needed
           }
         }
+        } catch (streamErr) {
+          streamErrored = streamErr;
+        } finally {
+          if (heartbeatInterval) {
+            clearInterval(heartbeatInterval);
+            heartbeatInterval = null;
+          }
+        }
+        if (streamErrored) {
+          if (isThinking) {
+            isThinking = false;
+            process.stdout.write(`\n${UI.slate('  └─')}\n`);
+          }
+          process.stdout.write('\r\x1b[K');
+          console.error(chalk.red(`\n❌ Stream error: ${streamErrored.message || streamErrored}`));
+          logEntry('error', { message: `Stream error: ${streamErrored.message || streamErrored}` });
+          active = false;
+          continue;
+        }
+        if (isThinking) {
+          isThinking = false;
+          process.stdout.write(`\n${UI.slate('  └─')}\n`);
+        }
         // Clear progress line and render formatted markdown
         process.stdout.write('\r\x1b[K');
+        showStreamPhase('Finalizing streamed response...');
         if (msg.trim()) {
+          showStreamPhase('Rendering markdown output...');
           console.log(renderMarkdown(msg));
         } else {
           console.log();
@@ -4176,22 +6495,27 @@ async function runSapper() {
           // Map native function names to tool executors
           const nativeToolNameMap = {
             list_directory: 'LIST', read_file: 'READ', search_files: 'SEARCH',
-            write_file: 'WRITE', patch_file: 'PATCH', create_directory: 'MKDIR', run_shell: 'SHELL'
+            write_file: 'WRITE', patch_file: 'PATCH', create_directory: 'MKDIR',
+            ls: 'LS', cat: 'CAT', head: 'HEAD', tail: 'TAIL', grep: 'GREP', find: 'FIND',
+            pwd: 'PWD', cd: 'CD', rmdir: 'RMDIR', changes: 'CHANGES',
+            fetch_web: 'FETCH', recall_memory: 'MEMORY', open_url: 'OPEN', run_shell: 'SHELL'
           };
 
+          showStreamPhase(`Running ${nativeToolCalls.length} native tool call${nativeToolCalls.length === 1 ? '' : 's'}...`);
+
           for (const tc of nativeToolCalls) {
             const fn = tc.function;
             const toolType = nativeToolNameMap[fn.name] || fn.name.toUpperCase();
             const args = fn.arguments || {};
 
             // Enforce agent tool restrictions
-            if (currentAgentTools && !currentAgentTools.includes(toolType)) {
+            if (currentAgentTools && !isToolAllowedForAgent(currentAgentTools, toolType)) {
               console.log(chalk.yellow(`\n⚠️  Tool ${toolType} blocked — not in agent's allowed tools`));
               messages.push({ role: 'tool', content: `Error: Tool ${toolType} is not allowed for the current agent.`, tool_name: fn.name });
               continue;
             }
 
-            const displayPath = args.path || args.pattern || args.command || '';
+            const displayPath = args.path || args.pattern || args.url || args.query || args.command || '';
             console.log();
             console.log(statusBadge(toolType, 'action') + chalk.gray(' → ') + chalk.white(displayPath));
 
@@ -4202,8 +6526,8 @@ async function runSapper() {
             try {
               switch (fn.name) {
                 case 'list_directory':
-                  result = tools.list(args.path);
-                  logEntry('file', { action: 'list', path: args.path });
+                  result = tools.list(args.path ?? '.');
+                  logEntry('file', { action: 'list', path: args.path ?? '.' });
                   break;
                 case 'read_file':
                   result = tools.read(args.path);
@@ -4218,26 +6542,66 @@ async function runSapper() {
                   logEntry('file', { action: 'write', path: args.path, size: args.content?.length || 0, userApproved: result.includes('Successfully') });
                   break;
                 case 'patch_file': {
-                  const patchKey = args.path?.trim();
-                  if (patchFailures[patchKey] >= MAX_PATCH_RETRIES) {
-                    result = `Error: PATCH failed ${MAX_PATCH_RETRIES} times on ${patchKey}. Use read_file to see exact content, then try write_file instead.`;
-                    toolSuccess = false;
-                  } else {
-                    result = await tools.patch(args.path, args.old_text, args.new_text);
-                    if (result.includes('Successfully')) {
-                      patchFailures[patchKey] = 0;
-                    } else if (result.startsWith('Error:')) {
-                      patchFailures[patchKey] = (patchFailures[patchKey] || 0) + 1;
-                      result += `\n(Attempt ${patchFailures[patchKey]}/${MAX_PATCH_RETRIES})`;
-                    }
-                  }
-                  logEntry('file', { action: 'patch', path: args.path, userApproved: result.includes('Successfully') });
+                  const pr = await patchWithRetry(args.path, args.old_text, args.new_text);
+                  result = pr.result;
+                  toolSuccess = pr.success;
+                  logEntry('file', { action: 'patch', path: args.path, userApproved: pr.success });
                   break;
                 }
                 case 'create_directory':
                   result = tools.mkdir(args.path);
                   logEntry('file', { action: 'mkdir', path: args.path });
                   break;
+                case 'ls':
+                  result = tools.ls(args.path ?? '.');
+                  logEntry('file', { action: 'list', path: args.path ?? '.' });
+                  break;
+                case 'cat':
+                  result = tools.cat(args.path);
+                  logEntry('file', { action: 'read', path: args.path, size: result?.length || 0 });
+                  break;
+                case 'head':
+                  result = tools.head(args.path, args.lines);
+                  logEntry('file', { action: 'read', path: args.path, size: result?.length || 0 });
+                  break;
+                case 'tail':
+                  result = tools.tail(args.path, args.lines);
+                  logEntry('file', { action: 'read', path: args.path, size: result?.length || 0 });
+                  break;
+                case 'grep':
+                  result = await tools.grep(args.pattern);
+                  logEntry('tool', { toolType: 'GREP', path: args.pattern, duration: Date.now() - toolStart, success: true, resultSize: result?.length });
+                  break;
+                case 'find':
+                  result = tools.find(args.pattern, args.path ?? '.');
+                  logEntry('tool', { toolType: 'FIND', path: args.pattern, duration: Date.now() - toolStart, success: !String(result).startsWith('Error:'), resultSize: result?.length });
+                  break;
+                case 'pwd':
+                  result = tools.pwd();
+                  break;
+                case 'cd':
+                  result = tools.cd(args.path);
+                  break;
+                case 'rmdir':
+                  result = await tools.rmdir(args.path);
+                  logEntry('file', { action: 'rmdir', path: args.path, userApproved: !String(result).includes('blocked') });
+                  break;
+                case 'changes':
+                  result = await tools.changes(args.path);
+                  logEntry('tool', { toolType: 'CHANGES', path: args.path ?? '.', duration: Date.now() - toolStart, success: !String(result).startsWith('Error:'), resultSize: result?.length });
+                  break;
+                case 'fetch_web':
+                  result = await tools.fetch_web(args.url);
+                  logEntry('tool', { toolType: 'FETCH', path: args.url, duration: Date.now() - toolStart, success: !String(result).startsWith('Error:'), resultSize: result?.length });
+                  break;
+                case 'recall_memory':
+                  result = await tools.recall_memory(args.query);
+                  logEntry('tool', { toolType: 'MEMORY', path: args.query, duration: Date.now() - toolStart, success: !String(result).startsWith('Error:'), resultSize: result?.length });
+                  break;
+                case 'open_url':
+                  result = await tools.open_url(args.url);
+                  logEntry('tool', { toolType: 'OPEN', path: args.url, duration: Date.now() - toolStart, success: String(result).startsWith('Opened URL'), resultSize: result?.length });
+                  break;
                 case 'run_shell':
                   result = await tools.shell(args.command);
                   logEntry('shell', { command: args.command, duration: Date.now() - toolStart, userApproved: !result.includes('blocked'), exitCode: result.match(/code (\d+)/)?.[1] ?? null });
@@ -4261,8 +6625,11 @@ async function runSapper() {
           fs.writeFileSync(CONTEXT_FILE, JSON.stringify(messages, null, 2));
 
           if (hitToolLimit) {
+            showStreamPhase('Tool limit reached. Requesting final answer...');
             resetTerminal();
             messages.push({ role: 'user', content: 'STOP using tools now. Provide your analysis based on what you have.' });
+          } else {
+            showStreamPhase('Tool results ready. Continuing response generation...');
           }
           continue; // Loop back for AI to process tool results
         }
@@ -4308,7 +6675,7 @@ async function runSapper() {
             const toolAttempt = msg.match(/\[TOOL:[^\]]*\][^\[]{0,100}/s);
             if (toolAttempt) {
               console.log(chalk.yellow(`  Raw tool attempt (first 150 chars):`));
-              console.log(chalk.gray(`  "${toolAttempt[0].substring(0, 150)}..."`));
+              console.log(chalk.gray(`  "${toolAttempt[0].substring(0, LIMITS.DEBUG_TOOL_PREVIEW)}..."`));
             }
           }
           console.log(chalk.magenta('═══════════════════════════════\n'));
@@ -4331,11 +6698,13 @@ async function runSapper() {
             if (lastAiLog) lastAiLog.toolCount = toolMatches.length;
           }
 
+          showStreamPhase(`Running ${toolMatches.length} parsed tool call${toolMatches.length === 1 ? '' : 's'}...`);
+
           for (const match of toolMatches) {
             const [_, type, path, content] = match;
             
             // Enforce tool restrictions from active agent
-            if (currentAgentTools && !currentAgentTools.includes(type.toUpperCase())) {
+            if (currentAgentTools && !isToolAllowedForAgent(currentAgentTools, type)) {
               console.log();
               console.log(chalk.yellow(`⚠️  Tool ${type.toUpperCase()} blocked — not in agent's allowed tools: [${currentAgentTools.join(', ')}]`));
               const result = `Error: Tool ${type.toUpperCase()} is not allowed for the current agent. Allowed tools: ${currentAgentTools.join(', ')}. Use only the allowed tools.`;
@@ -4354,14 +6723,40 @@ async function runSapper() {
               result = tools.list(path);
               logEntry('file', { action: 'list', path });
             }
+            else if (type.toLowerCase() === 'ls') {
+              result = tools.ls(path);
+              logEntry('file', { action: 'list', path: path || '.' });
+            }
             else if (type.toLowerCase() === 'read') {
               result = tools.read(path);
               logEntry('file', { action: 'read', path, size: result?.length || 0 });
             }
+            else if (type.toLowerCase() === 'cat') {
+              result = tools.cat(path);
+              logEntry('file', { action: 'read', path, size: result?.length || 0 });
+            }
+            else if (type.toLowerCase() === 'head') {
+              result = tools.head(path, content);
+              logEntry('file', { action: 'read', path, size: result?.length || 0 });
+            }
+            else if (type.toLowerCase() === 'tail') {
+              result = tools.tail(path, content);
+              logEntry('file', { action: 'read', path, size: result?.length || 0 });
+            }
             else if (type.toLowerCase() === 'mkdir') {
               result = tools.mkdir(path);
               logEntry('file', { action: 'mkdir', path });
             }
+            else if (type.toLowerCase() === 'rmdir') {
+              result = await tools.rmdir(path);
+              logEntry('file', { action: 'rmdir', path, userApproved: !String(result).includes('blocked') });
+            }
+            else if (type.toLowerCase() === 'pwd') {
+              result = tools.pwd();
+            }
+            else if (type.toLowerCase() === 'cd') {
+              result = tools.cd(path);
+            }
             else if (type.toLowerCase() === 'write') {
               if (!content || content.trim() === '') {
                 result = 'Error: WRITE requires content. Use [TOOL:WRITE]path]content here[/TOOL]';
@@ -4375,37 +6770,55 @@ async function runSapper() {
             else if (type.toLowerCase() === 'patch') {
               // PATCH format: [TOOL:PATCH]path:::OLD_TEXT|||NEW_TEXT[/TOOL]
               // Also supports line mode: [TOOL:PATCH]path:::LINE:15|||new text[/TOOL]
-              const patchKey = path.trim();
-              if (patchFailures[patchKey] >= MAX_PATCH_RETRIES) {
-                result = `Error: PATCH failed ${MAX_PATCH_RETRIES} times on ${patchKey}. STOP retrying PATCH on this file. Instead, use [TOOL:READ]${patchKey}[/TOOL] to see exact content, then either use LINE:number mode (e.g. [TOOL:PATCH]${patchKey}:::LINE:42|||new text[/TOOL]) or use [TOOL:WRITE] to rewrite the file.`;
-                toolSuccess = false;
-                logEntry('file', { action: 'patch', path, userApproved: false });
+              // Accept ||| as primary separator, ||: as fallback (small models sometimes mistype)
+              let parts = null;
+              const sepIdx = content?.indexOf('|||');
+              if (sepIdx > -1) {
+                parts = [content.substring(0, sepIdx), content.substring(sepIdx + 3)];
               } else {
-                // Accept ||| as primary separator, ||: as fallback (small models sometimes mistype)
-                let parts = content?.split('|||');
-                if (!parts || parts.length !== 2) {
-                  parts = content?.split('||:');
-                }
-                if (parts && parts.length === 2) {
-                  result = await tools.patch(path, parts[0], parts[1]);
-                  const approved = result.includes('Successfully');
-                  if (!approved && result.startsWith('Error:')) {
-                    patchFailures[patchKey] = (patchFailures[patchKey] || 0) + 1;
-                    result += `\n(Attempt ${patchFailures[patchKey]}/${MAX_PATCH_RETRIES} — after ${MAX_PATCH_RETRIES} failures, PATCH will be blocked on this file)`;
-                  } else if (approved) {
-                    patchFailures[patchKey] = 0; // Reset on success
-                  }
-                  logEntry('file', { action: 'patch', path, userApproved: approved });
-                } else {
-                  result = 'Error: PATCH requires format [TOOL:PATCH]path:::OLD_TEXT|||NEW_TEXT[/TOOL] or [TOOL:PATCH]path:::LINE:number|||NEW_TEXT[/TOOL]';
-                  toolSuccess = false;
+                const sepIdx2 = content?.indexOf('||:');
+                if (sepIdx2 > -1) {
+                  parts = [content.substring(0, sepIdx2), content.substring(sepIdx2 + 3)];
                 }
               }
+              if (parts && parts.length === 2) {
+                const pr = await patchWithRetry(path, parts[0], parts[1]);
+                result = pr.result;
+                toolSuccess = pr.success;
+                logEntry('file', { action: 'patch', path, userApproved: pr.success });
+              } else {
+                result = 'Error: PATCH requires format [TOOL:PATCH]path:::OLD_TEXT|||NEW_TEXT[/TOOL] or [TOOL:PATCH]path:::LINE:number|||NEW_TEXT[/TOOL]';
+                toolSuccess = false;
+              }
             }
             else if (type.toLowerCase() === 'search') {
               result = await tools.search(path);
               logEntry('tool', { toolType: 'SEARCH', path, duration: Date.now() - toolStart, success: true, resultSize: result?.length });
             }
+            else if (type.toLowerCase() === 'grep') {
+              result = await tools.grep(path);
+              logEntry('tool', { toolType: 'GREP', path, duration: Date.now() - toolStart, success: true, resultSize: result?.length });
+            }
+            else if (type.toLowerCase() === 'find') {
+              result = tools.find(path, content);
+              logEntry('tool', { toolType: 'FIND', path, duration: Date.now() - toolStart, success: !String(result).startsWith('Error:'), resultSize: result?.length });
+            }
+            else if (type.toLowerCase() === 'changes') {
+              result = await tools.changes(path);
+              logEntry('tool', { toolType: 'CHANGES', path: path || '.', duration: Date.now() - toolStart, success: !String(result).startsWith('Error:'), resultSize: result?.length });
+            }
+            else if (type.toLowerCase() === 'fetch') {
+              result = await tools.fetch_web(path);
+              logEntry('tool', { toolType: 'FETCH', path, duration: Date.now() - toolStart, success: !String(result).startsWith('Error:'), resultSize: result?.length });
+            }
+            else if (type.toLowerCase() === 'memory') {
+              result = await tools.recall_memory(path);
+              logEntry('tool', { toolType: 'MEMORY', path, duration: Date.now() - toolStart, success: !String(result).startsWith('Error:'), resultSize: result?.length });
+            }
+            else if (type.toLowerCase() === 'open') {
+              result = await tools.open_url(path);
+              logEntry('tool', { toolType: 'OPEN', path, duration: Date.now() - toolStart, success: String(result).startsWith('Opened URL'), resultSize: result?.length });
+            }
             else if (type.toLowerCase() === 'shell') {
               result = await tools.shell(path);
               const approved = !result.includes('blocked');
@@ -4413,7 +6826,7 @@ async function runSapper() {
             }
 
             // Log tool execution (for non-shell, non-file specific ones)
-            if (!['list', 'read', 'mkdir', 'write', 'patch', 'search', 'shell'].includes(type.toLowerCase())) {
+            if (!['list', 'ls', 'read', 'cat', 'head', 'tail', 'mkdir', 'rmdir', 'pwd', 'cd', 'write', 'patch', 'search', 'grep', 'find', 'changes', 'fetch', 'memory', 'open', 'shell'].includes(type.toLowerCase())) {
               logEntry('tool', { toolType: type.toUpperCase(), path, duration: Date.now() - toolStart, success: toolSuccess, resultSize: result?.length, error: toolSuccess ? undefined : result });
             }
 
@@ -4422,17 +6835,20 @@ async function runSapper() {
           ensureSapperDir();
           fs.writeFileSync(CONTEXT_FILE, JSON.stringify(messages, null, 2));
           
-          if (toolMatches.length > 30) {
+          if (toolMatches.length > LIMITS.TOOL_WARN_THRESHOLD) {
             console.log(chalk.yellow('\n⚠️  Reading 30+ files! This might take time.'));
           }
           
           // If tool limit was reached, stop after processing this round
           if (hitToolLimit) {
+            showStreamPhase('Tool limit reached. Requesting final answer...');
             resetTerminal();
             messages.push({ 
               role: 'user', 
               content: 'STOP using tools now. You have enough information. Please provide your analysis based on what you have read.' 
             });
+          } else {
+            showStreamPhase('Tool results ready. Continuing response generation...');
           }
         } else {
           // No tools found - check if malformed command