shmakk 1.2.2 → 1.2.4

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shmakk",
-  "version": "1.2.2",
+  "version": "1.2.4",
   "description": "AI-supervised terminal wrapper — command correction, tool-driven tasks, safety controls",
   "license": "MIT",
   "keywords": [

package/src/agent.js

@@ -7,7 +7,7 @@
 
 const fs = require('fs');
 const path = require('path');
-const { makeClient, modelFor, isConfigured, getDeepSeekOptions } = require('./llm');
+const { makeClient, modelFor, isConfigured, getDeepSeekOptions, supportsVision } = require('./llm');
 const {
   sanitizeAssistantContent,
   isLeakedToolMarkup,
@@ -87,13 +87,16 @@ function clearTaskJournal(root) {
 const { renderBlock } = require('./markdown');
 
 // Tiny spinner so the user sees "the agent is thinking" while we wait on
-// the model. Erased when stop() is called.
+// the model. Erased when stop() is called. Also updates the terminal tab
+// title so you can see agent activity even when looking at another tab.
 function startSpinner(write, label = 'thinking') {
   const frames = ['⠋', '⠙', '⠹', '⠸', '⠼', '⠴', '⠦', '⠧', '⠇', '⠏'];
   let i = 0; let line = '';
   const draw = () => {
     line = `\x1b[2m${frames[i % frames.length]} ${label}…\x1b[0m`;
     write('\r' + line);
+    // Update terminal tab/window title so activity is visible from other tabs
+    write(`\x1b]0;${frames[i % frames.length]} ${label} — shmakk\x07`);
     i++;
   };
   draw();
@@ -101,6 +104,8 @@ function startSpinner(write, label = 'thinking') {
   return () => {
     clearInterval(tm);
     write('\r' + ' '.repeat(line.replace(/\x1b\[[0-9;]*m/g, '').length + 2) + '\r\r');
+    // Clear the terminal title — shell will restore normal title on next prompt
+    write('\x1b]0;\x07');
   };
 }
 
@@ -251,6 +256,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     mcpToolHint,
     userRulesText,
     userMemoryText,
+    supportsVision: supportsVision(),
   });
 
   const boundedHistory = trimForContext(history, runtimeProfile.historyEntries);
@@ -292,14 +298,22 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
   // Tool loop. Streams content as it arrives; prints each tool call.
   let producedAnything = false;
   const runState = { _dsmlLeakRetries: 0 };
+  let taskSpinnerStop = null;
+  const ensureSpinner = () => {
+    if (!taskSpinnerStop) taskSpinnerStop = startSpinner(write, 'thinking');
+  };
+  const stopTaskSpinner = () => {
+    if (taskSpinnerStop) { taskSpinnerStop(); taskSpinnerStop = null; }
+  };
   for (let i = 0; i < dynamicToolBudget; i++) {
-    if (signal && signal.aborted) return messages.slice(1);
+    if (signal && signal.aborted) { stopTaskSpinner(); return messages.slice(1); }
 
     // Stream the response so the user sees text as it generates.
     const cacheKey = promptCacheEnabled ? promptCache.makeKey({ model: modelFor('agent'), messages, toolChoice: 'auto' }) : null;
     if (promptCacheEnabled && cacheKey) {
       const hit = promptCache.get(roots[0], cacheKey);
       if (hit && hit.content) {
+        stopTaskSpinner();
         write(dim('[shmakk] prompt cache hit', colors) + '\n');
         write(highlightCodeBlocks(hit.content, colors));
         if (!hit.content.endsWith('\n')) write('\n');
@@ -309,7 +323,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
       }
     }
 
-    const stop = startSpinner(write, i === 0 ? 'thinking' : 'continuing');
+    ensureSpinner();
     const allTools = mcpManager ? [...TOOLS, ...mcpManager.getToolDefinitions()] : TOOLS;
     let stream;
     try {
@@ -324,14 +338,13 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
         ...getDeepSeekOptions('tool_loop'),
       }, { signal });
     } catch (e) {
-      stop();
+      stopTaskSpinner();
       throw e;
     }
 
     let content = '';
     let reasoningContent = '';
     const toolCalls = []; // [{id, type:'function', function:{name, arguments}}]
-    let spinnerStopped = false;
     let streamingContentOk = true;  // flipped to false on leak
     try {
       for await (const chunk of stream) {
@@ -370,7 +383,6 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
           reasoningContent += delta.reasoning_content;
         }
         if (delta.tool_calls) {
-          if (!spinnerStopped) { stop(); spinnerStopped = true; }
           for (const tc of delta.tool_calls) {
             const idx = tc.index ?? 0;
             if (!toolCalls[idx]) toolCalls[idx] = { id: tc.id || '', type: 'function', function: { name: '', arguments: '' } };
@@ -382,7 +394,8 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
         }
       }
     } finally {
-      if (!spinnerStopped) stop();
+      // Spinner runs continuously from loop start — stopped below when
+      // we're about to show output or dispatch tools that may need input.
     }
 
     // ── DSML leak detection (after stream completes) ────────────────────
@@ -427,6 +440,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
       // Max retries exceeded — strip and show what we can.
       content = sanitized.visibleText;
       if (!content) {
+        stopTaskSpinner();
         write(dim('[shmakk] response contained only leaked tool markup — blocked.', colors) + '\n');
         clearTaskJournal(roots[0]);
         return messages.slice(1);
@@ -477,6 +491,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
 
     // No tools → done.
     if (!normalizedToolCalls.length) {
+      stopTaskSpinner();
       if (content) {
         write(renderBlock(content, { enabled: markdown, colors }));
         if (!content.endsWith('\n')) write('\n');
@@ -497,6 +512,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     // Dispatch tool calls.
     // Reads/lists are noisy — collect them silently and show a single dim summary.
     // Writes, edits, runs, and errors always print clearly.
+    stopTaskSpinner();
     const SILENT_TOOLS = new Set(['read_file', 'list_dir', 'web_search', 'fetch_url']);
     let iterProgress = false;
     let silentReads = [];
@@ -534,7 +550,34 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
         write(dim(`→ ${c.function.name}(${shortArgs(args)})${summary ? ' — ' + summary : ''}`, colors) + '\n');
       }
 
-      messages.push({ role: 'tool', tool_call_id: c.id, content: JSON.stringify(result).slice(0, 8000) });
+      // Build tool result message. If the result includes images with real
+      // base64 data AND the current endpoint has `vision: true`, send them as
+      // vision content blocks in a follow-up user message. Otherwise just
+      // include image metadata in the text. Keep the tool message text-only.
+      const toolImages = Array.isArray(result.images) ? result.images.filter((img) => img.data) : [];
+      const toolText = result.content || '';
+      const toolMeta = Object.fromEntries(
+        Object.entries(result || {}).filter(([k]) => !['content', 'images', 'error', 'isRetryable'].includes(k)),
+      );
+      let toolContent = (toolText + (Object.keys(toolMeta).length ? ' ' + JSON.stringify(toolMeta) : '')).trim();
+      if (toolImages.length > 0 && !supportsVision()) {
+        // Endpoint doesn't support vision — include image metadata as text
+        const imgDesc = toolImages.map((img, i) => `[Image #${i + 1}: ${img.mimeType}, base64=${img.dataLength} chars${img.truncated ? ', truncated' : ''}]`).join(', ');
+        toolContent = toolContent ? `${toolContent} ${imgDesc}` : imgDesc;
+      }
+      messages.push({ role: 'tool', tool_call_id: c.id, content: toolContent.slice(0, 8000) });
+      if (toolImages.length > 0 && supportsVision()) {
+        messages.push({
+          role: 'user',
+          content: [
+            { type: 'text', text: `[Images returned by ${c.function.name}${toolImages.some((img) => img.truncated) ? ' (some truncated to ~2MB base64)' : ''}]` },
+            ...toolImages.map((img) => ({
+              type: 'image_url',
+              image_url: { url: `data:${img.mimeType};base64,${img.data}`, detail: 'auto' },
+            })),
+          ],
+        });
+      }
       producedAnything = true;
       persistJournal('running');
       if (signal && signal.aborted) return messages.slice(1);
@@ -553,6 +596,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     }
 
     if (repeatedSignatureCount >= runtimeProfile.stallRepeat && noProgressRepeats >= 2) {
+      stopTaskSpinner();
       break;
     }
   }
@@ -589,6 +633,7 @@ async function runAgent({ input, roots, glossary, confirmTool, write, signal, hi
     }
   } catch {}
 
+  stopTaskSpinner();
   write(dim('[shmakk] paused after several tool rounds. Resume later continues from task journal; try `shmakk --reset` to clear.', colors) + '\n');
   persistJournal('paused');
   return messages.slice(1);

package/src/cli.js

@@ -41,8 +41,10 @@ function parseArgs(argv) {
     voiceSilenceStartSec: null,
     voicePadStartSec: null,
     ttsVoice: null,
-    notify: false,
+    notify: true,
     completion: null,
+    helpCategory: null,
+    shell: null,
     unknown: [],
   };
 
@@ -53,7 +55,13 @@ function parseArgs(argv) {
       case '--yes-files': opts.yesFiles = true; break;
       case '--update-command-glossary': opts.updateGlossary = true; break;
       case '-h':
-      case '--help': opts.help = true; break;
+      case '--help':
+        opts.help = true;
+        // Capture optional category: shmakk --help voice
+        if (i + 1 < argv.length && !argv[i + 1].startsWith('-')) {
+          opts.helpCategory = argv[++i];
+        }
+        break;
       case '--debug': opts.debug = true; break;
       case '--no-ai': opts.noAi = true; break;
       case '--no-correction': opts.noCorrection = true; break;
@@ -102,34 +110,67 @@ function parseArgs(argv) {
       case '--markdown': opts.markdown = argv[++i] || null; break;
       case '--endpoint': opts.endpoint = argv[++i] || null; break;
       case '--model-recommendation': opts.modelRecommendation = true; break;
+      case '--shell':
+        {
+          const v = argv[++i];
+          if (!v || !['fish', 'bash', 'zsh'].includes(v)) {
+            process.stderr.write('[shmakk] invalid --shell. Use: fish|bash|zsh\n');
+            process.exit(2);
+          }
+          opts.shell = v;
+        }
+        break;
       default: opts.unknown.push(a);
     }
   }
   return opts;
 }
 
-const HELP = `shmakk - AI-supervised terminal wrapper
+// ── Help: category-based navigation ──────────────────────────────────────────
+
+const HELP_SUMMARY = `shmakk - AI-supervised terminal wrapper
 
   Launch shmakk, then type commands as usual. shmakk watches the shell, catches
   failures, and calls an LLM to fix them, plan tasks, and edit files.
 
-  You can also type natural-language self-commands directly into the session
-  (e.g. "list skills", "agent overview", "compact"). See SELF-COMMANDS below.
-
   Type "help" inside a session to see this same text.
 
-═══════════════════════════════════════════════════════════════════════════
-  LAUNCH OPTIONS
+  Usage: shmakk [--flag ...]
+         shmakk --help [category]
+
+Categories (shmakk --help <name> for details):
+
+  launch       Startup modes, profiles, tuning flags
+  session      Status, stats, restart, exit, control signals
+  skills       Skill discovery, loading, listing, management
+  models       Provider configuration, endpoint presets
+  voice        Speech-to-Text / Text-to-Speech options
+  env          Environment variable reference
+  mcp          MCP servers and browser automation
+  ssh          Remote host execution
+  self         Natural-language self-commands (inside a session)
+
+`;
+
+const HELP_SECTIONS = {};
+
+HELP_SECTIONS.launch = `═══════════════════════════════════════════════════════════════════════════
+  LAUNCH OPTIONS  (shmakk --flag  from outside a session)
 ═══════════════════════════════════════════════════════════════════════════
 
+  These flags only apply when starting a new shmakk session. They are
+  ignored if you are already inside shmakk (SHMAKK=1).
+
   shmakk                           Launch in auto mode (AI acts on failures)
   shmakk --review                  Launch in review mode (confirm every AI action)
   shmakk --yes-files               Auto-accept file writes, edits, mkdir
 
-  shmakk --help                    Show this help
+  shmakk --help                    Show overview (this text)
+  shmakk --help <category>         Show detailed help for a category
   shmakk --build-history [files]   Parse shell history for better corrections
   shmakk --update-command-glossary Scan PATH and build local command glossary
 
+  --shell <fish|bash|zsh>          Use a specific shell (default: current $SHELL)
   --no-ai                          Disable AI entirely (pure passthrough)
   --no-correction                  Disable command correction
   --debug                          Verbose logging to stderr
@@ -140,8 +181,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   --colors <true|false>            Enable or disable ANSI colors
   --markdown <true|false>          Enable or disable markdown rendering
   --notify                         Desktop notifications for Y/n prompts
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.models = `═══════════════════════════════════════════════════════════════════════════
   MODEL PROVIDERS
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -159,8 +201,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
                           "model":"qwen/qwen3.5-9b" }
       }
     }
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.session = `═══════════════════════════════════════════════════════════════════════════
   SESSION CONTROL  (shmakk --flag  from another terminal)
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -176,6 +219,11 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   shmakk --exit                    Cleanly exit the parent shmakk
 
   shmakk --profile-set <name>      Switch profile and restart
+`;
+
+HELP_SECTIONS.skills = `═══════════════════════════════════════════════════════════════════════════
+  SKILLS
+═══════════════════════════════════════════════════════════════════════════
 
   shmakk --load-skill <name>       Load a skill into workspace state
   shmakk --install-skill <url>     Download skill markdown from URL, validate, load
@@ -183,71 +231,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   shmakk --list-skills             List all registered skills (workspace + global)
   shmakk --skill-status            Active skill and registry status
   shmakk --unload-skill <name>     Remove skill from whichever registry has it
+`;
 
-═══════════════════════════════════════════════════════════════════════════
-  SELF-COMMANDS  (type inside an shmakk session)
-═══════════════════════════════════════════════════════════════════════════
-
-  ── Skills ──
-  list skills                      List all registered skills
-  list skills <category>           List skills in a specific category
-  list skill categories            Show available skill categories
-  find skills <query>              Search skills by name/description
-  load skill <name>                Load a skill into the active workspace
-  unload skill <name>              Remove a skill from its registry
-  skill status                     Show active skill and registry state
-
-  ── Agents & Team ──
-  agent overview                   Show all agents and their specialisms
-  agent skills                     List all agent skills
-  agent <name>                     Show detail for a specific agent
-  list agents                      Alias for agent overview
-
-  ── Context & Session ──
-  status                           Show session status
-  stats                            Show session/task statistics
-  resume status                    Show task journal for resume continuity
-  show plan                        Display current plan and progress
-  compact                          Clear conversation + task journal
-  reset                            Clear AI conversation history
-
-  ── Memory & Search ──
-  recall <query>                   Search past sessions by content
-  find session <query>             Find a session by topic
-  last sessions                    Show recent sessions
-  search db status                 Display session search DB info
-  show memory                      List stored memories
-  forget <query>                   Remove matching memories
-
-  ── Configuration ──
-  show config                      Print resolved configuration
-  mcp status                       Show MCP servers and tools
-  show rules                       Display active workspace rules
-  list endpoints                   List configured model endpoints
-  use endpoint <name>              Switch to a named model endpoint
-  set model to <name>              Change the active model
-  set url to <url>                 Change the base URL
-  set api key to <key>             Change the API key
-
-  ── Toggles ──
-  enable review  |  disable review
-  enable correction  |  disable correction
-  enable yes-files  |  disable yes-files
-  enable colors  |  disable colors
-  enable debug  |  disable debug
-
-  ── Workflows ──
-  list workflows                   Show available automation workflows
-  run workflow <name>              Execute a named workflow
-
-  ── Edits ──
-  review edits                     Step through pending file changes
-
-  ── Meta ──
-  sidebar <query>                  Out-of-band agent query (not added to history)
-  help                             Show this help
-
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.voice = `═══════════════════════════════════════════════════════════════════════════
   VOICE  (Speech-to-Text / Text-to-Speech)
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -266,8 +252,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   STT: Whisper-base ONNX in-process. No Python, no server, no API key.
   TTS: kokoro-js (Kokoro-82M ONNX, ~334MB fp16). Auto-download on first use.
   Requires aplay, paplay, or afplay for audio. 28 voices, rotated daily.
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.env = `═══════════════════════════════════════════════════════════════════════════
   ENVIRONMENT
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -287,8 +274,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
   SHMAKK_VOICE_SILENCE_SEC         VAD silence threshold seconds
   SHMAKK_VOICE_SILENCE_THRESHOLD   VAD amplitude threshold
   SHMAKK_VOICE_PAD_START_SEC       Start-of-recording padding
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.mcp = `═══════════════════════════════════════════════════════════════════════════
   MCP & BROWSER
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -299,8 +287,9 @@ const HELP = `shmakk - AI-supervised terminal wrapper
     npm install playwright && npx playwright install chromium
   Tools: navigate, click, type, read_page, screenshot, evaluate, select,
   wait, scroll, close.
+`;
 
-═══════════════════════════════════════════════════════════════════════════
+HELP_SECTIONS.ssh = `═══════════════════════════════════════════════════════════════════════════
   REMOTE HOSTS (SSH)
 ═══════════════════════════════════════════════════════════════════════════
 
@@ -326,7 +315,106 @@ const HELP = `shmakk - AI-supervised terminal wrapper
       ControlMaster auto
       ControlPath ~/.ssh/controlmasters/%r@%h:%p
       ControlPersist 600
+`;
+
+HELP_SECTIONS.self = `═══════════════════════════════════════════════════════════════════════════
+  SELF-COMMANDS  (type inside an shmakk session)
+═══════════════════════════════════════════════════════════════════════════
+
+  Self-commands work with a prefix — /cmd or shmakk cmd.
+  Bare words like "status" or "stats" go to the shell, not shmakk.
+
+  -- Session --
+  /status  |  shmakk status         Show session status
+  /stats   |  shmakk stats          Show session/task statistics
+  /sessions  |  shmakk sessions     Show recent sessions
+  show sessions  |  last sessions   (same as /sessions)
+  resume status                     Show task journal for resume continuity
+  show plan                         Display current plan and progress
+  /compact  |  shmakk compact       Clear conversation + task journal
+  /reset  |  shmakk reset           Clear AI conversation history
+
+  -- Skills --
+  list skills                       List all registered skills
+  list skills <category>            List skills in a specific category
+  list skill categories             Show available skill categories
+  find skills <query>               Search skills by name/description
+  load skill <name>                 Load a skill into the active workspace
+  unload skill <name>               Remove a skill from its registry
+  skill status                      Show active skill and registry state
+
+  -- Agents & Team --
+  agent overview                    Show all agents and their specialisms
+  agent skills                      List all agent skills
+  agent <name>                      Show detail for a specific agent
+  list agents                       Alias for agent overview
+
+  -- Memory & Search --
+  recall <query>                    Search past sessions by content
+  find session <query>              Find a session by topic
+  search db status                  Display session search DB info
+  show memory                       List stored memories
+  forget <query>                    Remove matching memories
+
+  -- Configuration --
+  show config                       Print resolved configuration
+  mcp status                        Show MCP servers and tools
+  show rules                        Display active workspace rules
+  list endpoints                    List configured model endpoints
+  use endpoint <name>               Switch to a named model endpoint
+  set model to <name>               Change the active model
+  set url to <url>                  Change the base URL
+  set api key to <key>              Change the API key
+
+  -- Toggles --
+  enable review  |  disable review
+  enable correction  |  disable correction
+  enable yes-files  |  disable yes-files
+  enable colors  |  disable colors
+  enable debug  |  disable debug
+
+  -- Workflows --
+  list workflows                    Show available automation workflows
+  run workflow <name>               Execute a named workflow
+
+  -- Edits --
+  review edits                      Step through pending file changes
+
+  -- Meta --
+  sidebar <query>                   Out-of-band agent query (not added to history)
+  help                              Show this help
+`;
+
+// Resolve: returns the full old HELP string for backward compat, or the category
+// text, or the summary.
+function resolveHelp(category) {
+  if (category) {
+    const key = category.toLowerCase();
+    if (HELP_SECTIONS[key]) return HELP_SECTIONS[key];
+    // Unknown category: show summary + available categories
+    const available = Object.keys(HELP_SECTIONS).join(', ');
+    return HELP_SUMMARY + `Unknown category "${category}". Available: ${available}\n`;
+  }
+  return HELP_SUMMARY;
+}
+
+// Help text shown INSIDE a session (no launch flags — you're already running)
+const HELP_SESSION_SUMMARY = `shmakk — inside a session
+
+  Type commands as usual. shmakk watches the shell, catches failures, and
+  calls an LLM to fix them, plan tasks, and edit files.
+
+  Self-commands use a prefix: /cmd  or  shmakk cmd
+  Examples:  /status   /sessions   shmakk status   shmakk show sessions
+
+  Multi-word natural language also works:  "show help"  "list skills"
+
+  For the full reference: shmakk --help self (from outside the session)
+  For launch flags:        shmakk --help launch
 
 `;
 
-module.exports = { parseArgs, HELP };
+// Full legacy HELP for backward compat
+const HELP = HELP_SUMMARY + Object.values(HELP_SECTIONS).join('\n');
+
+module.exports = { parseArgs, HELP, resolveHelp, HELP_SUMMARY, HELP_SESSION_SUMMARY };

package/src/correction.js

@@ -115,6 +115,18 @@ function preserveCase(original, corrected) {
 }
 
 async function correct({ input, glossary, signal: _unused }) {
+  // Null/empty input: can happen at shell startup when precmd fires before
+  // any command is executed (especially in zsh). Nothing to correct.
+  if (!input || !input.trim()) {
+    return { category: 'not_a_correction', proposed: null, safety: 'uncertain', reason: 'empty input' };
+  }
+
+  // /-prefixed and "shmakk ..." commands are shmakk self-commands.
+  // They should never reach the correction engine — bail out immediately.
+  if (/^\//.test(input) || /^shmakk\s/i.test(input)) {
+    return { category: 'not_a_correction', proposed: null, safety: 'uncertain', reason: 'shmakk self-command prefix — not a shell command' };
+  }
+
   // Pre-filter natural language
   if (looksLikeNaturalLanguage(input)) {
     return { category: 'not_a_correction', proposed: null, safety: 'uncertain', reason: 'looks like natural language' };

package/src/endpoints.js

@@ -73,6 +73,7 @@ function normalizeModelConfig(name, cfg) {
     headers: cfg.headers || cfg.headears || null,
     registry: cfg.registry || null,
     main: !!cfg.main,
+    vision: !!cfg.vision,
   };
 }
 
@@ -143,6 +144,10 @@ function getCurrentEndpointName() {
   return currentEndpointName;
 }
 
+function supportsVision() {
+  return !!(currentEndpointConfig && currentEndpointConfig.vision);
+}
+
 function listEndpoints(cwd) {
   return Object.keys(loadModelRegistry(cwd).models);
 }
@@ -160,5 +165,6 @@ module.exports = {
   listEndpoints,
   getCurrentEndpoint,
   getCurrentEndpointName,
+  supportsVision,
   getModelRegistry,
 };

package/src/hooks/bash.js

@@ -3,6 +3,21 @@ const os = require('os');
 const path = require('path');
 
 const INIT = `
+# Source login scripts first (equivalent to bash -l).
+# When --rcfile is used, bash skips the normal login sequence, so we must
+# replicate it manually. Order matters: profile.d → /etc/profile, then
+# first found of: ~/.bash_profile, ~/.bash_login, ~/.profile, ~/.bashrc.
+[ -d /etc/profile.d ] && for f in /etc/profile.d/*.sh; do [ -r "$f" ] && . "$f"; done
+[ -f /etc/profile ] && . /etc/profile
+if [ -f "$HOME/.bash_profile" ]; then
+    . "$HOME/.bash_profile"
+elif [ -f "$HOME/.bash_login" ]; then
+    . "$HOME/.bash_login"
+elif [ -f "$HOME/.profile" ]; then
+    . "$HOME/.profile"
+fi
+# Then interactive rc files (these may be already sourced above, but
+# sourcing twice is harmless for well-behaved scripts).
 [ -f /etc/bash.bashrc ] && . /etc/bash.bashrc
 [ -f "$HOME/.bashrc" ] && . "$HOME/.bashrc"
 
@@ -13,13 +28,13 @@ __shmakk_preexec() {
     [ "$BASH_COMMAND" = "$PROMPT_COMMAND" ] && return
     __shmakk_armed=
     local cmd
-    cmd=$(printf '%s' "$BASH_COMMAND" | base64 -w0 2>/dev/null || printf '%s' "$BASH_COMMAND" | base64)
+    cmd=$(printf '%s' "$BASH_COMMAND" | base64 -w0 2>/dev/null || base64 -b 0 2>/dev/null || base64 | tr -d '\n')
     printf '\\e]6973;B;%s\\a' "$cmd"
 }
 __shmakk_precmd() {
     local ec=$?
     local p
-    p=$(printf '%s' "$PWD" | base64 -w0 2>/dev/null || printf '%s' "$PWD" | base64)
+    p=$(printf '%s' "$PWD" | base64 -w0 2>/dev/null || base64 -b 0 2>/dev/null || base64 | tr -d '\n')
     printf '\\e]6973;C;%s\\a' "$ec"
     printf '\\e]6973;D;%s\\a' "$p"
     __shmakk_armed=1

package/src/hooks/fish.js

@@ -1,17 +1,36 @@
 // Returns { args, env, cleanup } for spawning fish with markers wired up.
 // fish supports `-C COMMAND` to run init code after config.fish.
+//
+// base64 encoding: try `-w0` (GNU coreutils), fall back to `-b 0` (BSD/macOS),
+// then plain `base64` as last resort. `tr -d '\n'` strips any line wrapping
+// so the OSC marker payload stays on one line.
 
 const INIT = `
 function __shmakk_pre --on-event fish_preexec
-    set -l c (printf '%s' "$argv" | base64 -w0 2>/dev/null; or printf '%s' "$argv" | base64)
+    set -l c (printf '%s' "$argv" | base64 -w0 2>/dev/null || base64 -b 0 2>/dev/null || base64 | tr -d '\n')
     printf '\\e]6973;B;%s\\a' "$c"
 end
 function __shmakk_post --on-event fish_postexec
     set -l ec $status
-    set -l p (printf '%s' "$PWD" | base64 -w0 2>/dev/null; or printf '%s' "$PWD" | base64)
+    set -l p (printf '%s' "$PWD" | base64 -w0 2>/dev/null || base64 -b 0 2>/dev/null || base64 | tr -d '\n')
     printf '\\e]6973;C;%s\\a' $ec
     printf '\\e]6973;D;%s\\a' "$p"
 end
+# Override shmakk binary inside a session so "shmakk <cmd>" routes to
+# local self-commands instead of forking a nested shmakk process.
+# Passes through --flags to the real shmakk binary.
+function shmakk
+    if set -q argv[1]; and string match -qr '^--' -- "$argv[1]"
+        command shmakk $argv
+        return $status
+    end
+    set -l raw (printf '%s' "shmakk $argv" | base64 -w0 2>/dev/null || base64 -b 0 2>/dev/null || base64 | tr -d '\n')
+    set -l pwd_b64 (printf '%s' "$PWD" | base64 -w0 2>/dev/null || base64 -b 0 2>/dev/null || base64 | tr -d '\n')
+    printf '\\e]6973;B;%s\\a' "$raw"
+    printf '\\e]6973;C;127\\a'
+    printf '\\e]6973;D;%s\\a' "$pwd_b64"
+    return 127
+end
 `.trim();
 
 function configure() {

package/src/hooks/zsh.js

@@ -2,6 +2,28 @@ const fs = require('fs');
 const os = require('os');
 const path = require('path');
 
+// zsh under a custom ZDOTDIR sources .zshenv, .zprofile, .zshrc, .zlogin from
+// that directory. We create all four so nothing from the user's real ZDOTDIR
+// is skipped.
+
+const ZSHENV = `
+# Source the real .zshenv so PATH and env vars are available.
+if [ -n "$SHMAKK_REAL_ZDOTDIR" ] && [ -f "$SHMAKK_REAL_ZDOTDIR/.zshenv" ]; then
+    source "$SHMAKK_REAL_ZDOTDIR/.zshenv"
+elif [ -f "$HOME/.zshenv" ]; then
+    source "$HOME/.zshenv"
+fi
+`;
+
+const ZPROFILE = `
+# Source the real .zprofile (login shell initialization).
+if [ -n "$SHMAKK_REAL_ZDOTDIR" ] && [ -f "$SHMAKK_REAL_ZDOTDIR/.zprofile" ]; then
+    source "$SHMAKK_REAL_ZDOTDIR/.zprofile"
+elif [ -f "$HOME/.zprofile" ]; then
+    source "$HOME/.zprofile"
+fi
+`;
+
 const ZSHRC = `
 # preserve real ZDOTDIR so user config is sourced
 if [ -n "$SHMAKK_REAL_ZDOTDIR" ]; then
@@ -12,13 +34,13 @@ fi
 
 __shmakk_preexec() {
     local cmd
-    cmd=$(printf '%s' "$1" | base64 -w0 2>/dev/null || printf '%s' "$1" | base64)
+    cmd=$(printf '%s' "$1" | base64 -w0 2>/dev/null || base64 -b 0 2>/dev/null || base64 | tr -d '\n')
     printf '\\e]6973;B;%s\\a' "$cmd"
 }
 __shmakk_precmd() {
     local ec=$?
     local p
-    p=$(printf '%s' "$PWD" | base64 -w0 2>/dev/null || printf '%s' "$PWD" | base64)
+    p=$(printf '%s' "$PWD" | base64 -w0 2>/dev/null || base64 -b 0 2>/dev/null || base64 | tr -d '\n')
     printf '\\e]6973;C;%s\\a' "$ec"
     printf '\\e]6973;D;%s\\a' "$p"
 }
@@ -30,7 +52,14 @@ precmd_functions+=(__shmakk_precmd)
 function configure() {
   const dir = path.join(os.tmpdir(), `shmakk-zsh-${process.pid}`);
   fs.mkdirSync(dir, { recursive: true });
+  // zsh under a custom ZDOTDIR sources .zshenv, .zprofile, .zshrc, .zlogin
+  // from that directory. We must provide all four so the user's environment
+  // is complete.
+  fs.writeFileSync(path.join(dir, '.zshenv'), ZSHENV, { mode: 0o600 });
+  fs.writeFileSync(path.join(dir, '.zprofile'), ZPROFILE, { mode: 0o600 });
   fs.writeFileSync(path.join(dir, '.zshrc'), ZSHRC, { mode: 0o600 });
+  // No .zlogin needed — zsh docs say .zlogin is for commands to run at the
+  // start of an interactive login shell; .zprofile already covers env setup.
   const realZ = process.env.ZDOTDIR || '';
   return {
     args: ['-i'],

package/src/index.js

@@ -1,4 +1,4 @@
-const { parseArgs, HELP } = require('./cli');
+const { parseArgs, HELP, resolveHelp } = require('./cli');
 const { normalizeProfile, resolveProfile } = require('./profiles');
 const { applyEndpoint, getCurrentEndpoint, getCurrentEndpointName } = require('./endpoints');
 const { ensureModelRuntime } = require('./llm');
@@ -66,7 +66,7 @@ async function main() {
   }
 
   if (opts.help) {
-    process.stdout.write(HELP);
+    process.stdout.write(resolveHelp(opts.helpCategory));
     process.exit(0);
   }
 
@@ -204,6 +204,15 @@ async function main() {
   if (opts.ttsVoice) process.env.SHMAKK_TTS_VOICE = opts.ttsVoice;
 
   const { start } = require('./orchestrator');
+
+  // Refuse to nest sessions: launching shmakk inside shmakk would
+  // create a recursive PTY tree with no benefit.
+  if (process.env.SHMAKK === '1') {
+    process.stderr.write('[shmakk] already inside an shmakk session (SHMAKK=1).\n');
+    process.stderr.write('[shmakk] use --help to see in-session commands, or exit the current session first.\n');
+    process.exit(1);
+  }
+
   const exitCode = await start(opts);
   process.exit(exitCode);
 }

package/src/llm.js

@@ -4,7 +4,7 @@ try { OpenAI = require('openai'); } catch { OpenAI = null; }
 const path = require('path');
 const os = require('os');
 const fs = require('fs');
-const { getCurrentEndpoint, getCurrentEndpointName, getModelRegistry } = require('./endpoints');
+const { getCurrentEndpoint, getCurrentEndpointName, getModelRegistry, supportsVision } = require('./endpoints');
 
 function parseHeaders(s) {
   const out = {};
@@ -536,4 +536,4 @@ function getDeepSeekOptions(taskType) {
   };
 }
 
-module.exports = { makeClient, modelFor, isConfigured, ensureModelRuntime, getDeepSeekOptions, isDeepSeekProvider };
+module.exports = { makeClient, modelFor, isConfigured, ensureModelRuntime, getDeepSeekOptions, isDeepSeekProvider, supportsVision };

package/src/mcp-client.js

@@ -212,9 +212,15 @@ class MCPServer {
         if (item.type === 'text') {
           texts.push(item.text);
         } else if (item.type === 'image') {
+          // Preserve base64 image data so vision-capable providers can process it.
+          // Cap at ~2MB of base64 to avoid blowing out context windows.
+          const raw = String(item.data || '');
+          const capped = raw.length > 2_000_000 ? raw.slice(0, 2_000_000) : raw;
           images.push({
             mimeType: item.mimeType || 'image/png',
-            dataLength: (item.data || '').length,
+            data: capped,
+            dataLength: raw.length,
+            truncated: raw.length > 2_000_000,
           });
         } else if (item.type === 'resource') {
           texts.push(`[resource: ${item.resource?.uri || 'unknown'}]`);

package/src/notify.js

@@ -2,14 +2,17 @@
 // Falls back silently if notify-send is not available or no notification
 // daemon is running.
 
-const { execFile } = require('child_process');
+const { execFile, execFileSync } = require('child_process');
+const { existsSync } = require('fs');
 
 const NOTIFY_BIN = 'notify-send';
 
 function available() {
   try {
-    const { execFileSync } = require('child_process');
-    execFileSync('which', [NOTIFY_BIN], { stdio: 'ignore' });
+    // Prefer direct path check; fall back to `command -v` if not at known paths
+    if (existsSync('/usr/bin/notify-send')) return true;
+    if (existsSync('/usr/local/bin/notify-send')) return true;
+    execFileSync('command', ['-v', NOTIFY_BIN], { stdio: 'ignore' });
     return true;
   } catch {
     return false;

package/src/pty.js

@@ -13,8 +13,8 @@ function getSize() {
 
 const VOICE_HOTKEY = 0x0f; // Ctrl+O — triggers voice recording
 
-function startSession({ debug = false, voiceEnabled = false } = {}) {
-  const shell = detectShell();
+function startSession({ debug = false, voiceEnabled = false, shellOverride = null } = {}) {
+  const shell = detectShell(shellOverride);
   const cfg = configureForShell(shell.name);
   const { cols, rows } = getSize();
 

package/src/review.js

@@ -2,13 +2,13 @@
 // optional `{ onCancel }` callback that fires when the user hits Ctrl-C.
 
 function makePrompter(pty, write, opts = {}) {
-  const { onNotify } = opts;
   return function ask(question, defaultYes, { onCancel, onWhy } = {}) {
     return new Promise((resolve) => {
-      if (onNotify) {
+      if (opts.notify) {
         try {
+          const { notify } = require('./notify');
           const body = typeof question === 'string' ? question.replace(/\x1b\[[0-9;]*m/g, '') : String(question || '');
-          onNotify('shmakk needs your attention', body.slice(0, 120));
+          notify('shmakk needs your attention', body.slice(0, 120));
         } catch {}
       }
       const tag = defaultYes ? '[Y/n/?]' : '[y/N/?]';

package/src/self-commands.js

@@ -110,12 +110,14 @@ const SELF_COMMANDS = [
   },
 
   // ── Session ──
+  // NOTE: Bare "status", "stats" etc. are NOT intercepted — they may be
+  // real shell commands. Use /status, /stats, shmakk status, etc. instead.
   {
-    patterns: [/^(?:shmakk\s+)?status$/i],
+    patterns: [/^status$/i],
     action: 'status',
   },
   {
-    patterns: [/^(?:show\s+)?stats$/i, /^session\s+stats$/i],
+    patterns: [/^stats$/i, /^session\s+stats$/i],
     action: 'stats',
   },
   {
@@ -164,8 +166,8 @@ const SELF_COMMANDS = [
   },
   {
     patterns: [
-      /^(?:show\s+)?last\s+sessions?$/i,
-      /^recent\s+sessions?$/i,
+      /^(?:show\s+)?(?:last\s+|recent\s+)?sessions?$/i,
+      /^sessions?$/i,
     ],
     action: 'last-sessions',
   },
@@ -320,6 +322,22 @@ const SELF_COMMANDS = [
     action: 'disable-yes-files',
   },
 
+  // ── Notify ──
+  {
+    patterns: [
+      /^(?:enable|turn\s+on)\s+notify$/i,
+      /^notify\s+on$/i,
+    ],
+    action: 'enable-notify',
+  },
+  {
+    patterns: [
+      /^(?:disable|turn\s+off|no)\s+notify$/i,
+      /^notify\s+off$/i,
+    ],
+    action: 'disable-notify',
+  },
+
   // ── Colors ──
   {
     patterns: [
@@ -399,20 +417,65 @@ const SELF_COMMANDS = [
   },
 ];
 
+// Self-command prefixes accepted by the shell:
+//   /cmd          — e.g. /status, /sessions, /compact
+//   shmakk cmd    — e.g. shmakk status, shmakk show sessions
+// Bare words like "status" are NOT intercepted (they go to the shell).
+const SELF_PREFIX_RE = /^\/(.+)$/;
+const SHMAKK_PREFIX_RE = /^shmakk\s+(.+)$/i;
+
+function hasSelfCommandPrefix(input) {
+  const text = String(input || '').trim();
+  return SELF_PREFIX_RE.test(text) || SHMAKK_PREFIX_RE.test(text);
+}
+
+function stripSelfCommandPrefix(input) {
+  const text = String(input || '').trim();
+  let m = SELF_PREFIX_RE.exec(text);
+  if (m) return m[1].trim();
+  m = SHMAKK_PREFIX_RE.exec(text);
+  if (m) return m[1].trim();
+  return text;
+}
+
 function matchSelfCommand(input) {
   const text = String(input || '').trim();
   if (!text) return { matched: false };
 
-  for (const entry of SELF_COMMANDS) {
-    for (const pattern of entry.patterns) {
-      const m = pattern.exec(text);
-      if (m) {
-        return {
-          matched: true,
-          action: entry.action,
-          arg: entry.needsArg && m[1] ? m[1].trim() : null,
-          confirm: !!entry.confirm,
-        };
+  // Try matching with prefix stripped first (for /status, shmakk status, etc.)
+  const stripped = stripSelfCommandPrefix(text);
+  if (stripped !== text) {
+    for (const entry of SELF_COMMANDS) {
+      for (const pattern of entry.patterns) {
+        const m = pattern.exec(stripped);
+        if (m) {
+          return {
+            matched: true,
+            action: entry.action,
+            arg: entry.needsArg && m[1] ? m[1].trim() : null,
+            confirm: !!entry.confirm,
+          };
+        }
+      }
+    }
+    return { matched: false };
+  }
+
+  // Multi-word natural-language commands (no prefix needed).
+  // Single bare words are NOT matched — they could be real shell commands.
+  const wordCount = text.split(/\s+/).length;
+  if (wordCount >= 2) {
+    for (const entry of SELF_COMMANDS) {
+      for (const pattern of entry.patterns) {
+        const m = pattern.exec(text);
+        if (m) {
+          return {
+            matched: true,
+            action: entry.action,
+            arg: entry.needsArg && m[1] ? m[1].trim() : null,
+            confirm: !!entry.confirm,
+          };
+        }
       }
     }
   }
@@ -422,6 +485,9 @@ function matchSelfCommand(input) {
 
 // ctx is optional: { opts, HELP, setColors }
 function executeSelfCommand(match, write, ctx = {}) {
+  // Update terminal tab title so self-command activity is visible from other tabs
+  const label = match.action.replace(/-/g, ' ');
+  write(`\x1b]0;${label} — shmakk\x07`);
   const ctl = require('./control');
   const opts = ctx.opts || {};
 
@@ -429,7 +495,7 @@ function executeSelfCommand(match, write, ctx = {}) {
 
     // ── Help ──
     case 'show-help': {
-      const helpText = ctx.HELP || '[shmakk] help text not available';
+      const helpText = ctx.HELP_SESSION_SUMMARY || ctx.HELP_SUMMARY || ctx.HELP || '[shmakk] help text not available';
       write(helpText.replace(/\n/g, '\r\n'));
       break;
     }
@@ -803,6 +869,18 @@ function executeSelfCommand(match, write, ctx = {}) {
       break;
     }
 
+    // ── Notify ──
+    case 'enable-notify': {
+      if (ctx.opts) ctx.opts.notify = true;
+      write('[shmakk] desktop notifications enabled\r\n');
+      break;
+    }
+    case 'disable-notify': {
+      if (ctx.opts) ctx.opts.notify = false;
+      write('[shmakk] desktop notifications disabled\r\n');
+      break;
+    }
+
     // ── Colors ──
     case 'enable-colors': {
       if (ctx.opts) ctx.opts.colors = true;
@@ -858,6 +936,8 @@ function executeSelfCommand(match, write, ctx = {}) {
     default:
       write(`[shmakk] unknown self-command: ${match.action}\r\n`);
   }
+  // Clear terminal title — shell will restore normal title on next prompt
+  write('\x1b]0;\x07');
 }
 
-module.exports = { matchSelfCommand, executeSelfCommand, SELF_COMMANDS };
+module.exports = { matchSelfCommand, executeSelfCommand, hasSelfCommandPrefix, stripSelfCommandPrefix, SELF_COMMANDS };

package/src/session.js

@@ -20,7 +20,7 @@ const { runTeam, looksMultiDomain } = require('./team');
 const { addPlanTasks, markTaskComplete, markTaskSkipped } = require('./task-file');
 const { captureGitSha, runPostPlanReview } = require('./code-reviewer');
 const sessionSearch = require('./session-search');
-const { HELP } = require('./cli');
+const { HELP, HELP_SUMMARY, HELP_SESSION_SUMMARY } = require('./cli');
 const audit = require('./audit');
 const { setMaxListeners } = require('events');
 
@@ -163,13 +163,11 @@ function makeToolConfirm(opts, ask, out, getAbort) {
 }
 
 async function runOneSession(opts, registerSession) {
-  const session = startSession({ debug: opts.debug, voiceEnabled: !!opts.voice });
+  const session = startSession({ debug: opts.debug, voiceEnabled: !!opts.voice, shellOverride: opts.shell });
   let colorsEnabled = opts.colors !== false;
   let markdownEnabled = opts.markdown !== false;
   const out = (s) => session.stdoutWrite(colorsEnabled ? s : stripAnsi(s));
-  const ask = makePrompter(session, out, {
-    onNotify: opts.notify ? (summary, body) => notify(summary, body) : null,
-  });
+  const ask = makePrompter(session, out, opts);
   const glossary = loadGlossary();
   // Workspace tracking: explicit --workspace is "pinned"; otherwise cwd
   // floats with the inner shell's `cd`. When both pinned and cwd differ,
@@ -373,6 +371,8 @@ async function runOneSession(opts, registerSession) {
       executeSelfCommand(voiceSelfCmd, out, {
         opts,
         HELP,
+        HELP_SUMMARY,
+        HELP_SESSION_SUMMARY,
         setColors: (v) => { colorsEnabled = v; },
       });
       return;
@@ -613,6 +613,14 @@ async function runOneSession(opts, registerSession) {
     lastCommand = null;
     if (flushTimer) { clearTimeout(flushTimer); flushTimer = null; }
 
+    // No command was tracked — precmd can fire at shell startup (especially
+    // in zsh) before any command executes. There's nothing to correct or
+    // route to the agent.
+    if (!lastCmd) {
+      discardPending();
+      return;
+    }
+
     // ── Self-command detection (FIRST — before ANY other processing) ──
     // Self-commands are pure local execution. They MUST bypass:
     //   - the noAi early-return (they don't need an LLM)
@@ -672,11 +680,20 @@ async function runOneSession(opts, registerSession) {
         executeSelfCommand(selfCmd, out, {
           opts,
           HELP,
+          HELP_SUMMARY,
+          HELP_SESSION_SUMMARY,
           setColors: (v) => { colorsEnabled = v; },
         });
         session.childWrite('\r');
         return;
       }
+      // /-prefixed and "shmakk ..." commands that didn't match a known
+      // self-command are invalid shmakk commands. Don't send them to the
+      // correction engine — the user was explicitly addressing shmakk.
+      if (/^\//.test(lastCmd) || /^shmakk\s/i.test(lastCmd)) {
+        flushPending();
+        return;
+      }
     }
 
     // Determine the command to feed forward.

package/src/shell.js

@@ -1,32 +1,52 @@
 const fs = require('fs');
 const path = require('path');
 
-function detectShell() {
+// Map shell name to the preferred executable path.
+// Resolve's dctl paths on Arch-like systems can put bash in /usr/bin instead of /bin.
+// Map shell name to candidate executable paths.
+// Ordered by likelihood on the current platform; first existing path wins.
+const SHELL_PATH_CANDIDATES = {
+  fish: ['/usr/bin/fish', '/opt/homebrew/bin/fish', '/usr/local/bin/fish', '/bin/fish'],
+  bash: ['/usr/bin/bash', '/bin/bash', '/opt/homebrew/bin/bash', '/usr/local/bin/bash'],
+  zsh: ['/usr/bin/zsh', '/bin/zsh', '/opt/homebrew/bin/zsh', '/usr/local/bin/zsh'],
+};
+
+function shellPath(name) {
+  // Name given explicitly (--shell flag): try known paths first, then PATH.
+  const candidates = SHELL_PATH_CANDIDATES[name];
+  if (candidates) {
+    for (const candidate of candidates) {
+      if (fs.existsSync(candidate)) return candidate;
+    }
+  }
+
+  // Fall back to PATH search for the requested shell.
+  const { execSync } = require('child_process');
+  try {
+    const p = execSync(`command -v ${name}`, { encoding: 'utf8', stdio: ['pipe', 'pipe', 'ignore'] }).trim();
+    if (p && fs.existsSync(p)) return p;
+  } catch {}
+
+  return null;
+}
+
+function detectShell(shellOverride) {
+  // Explicit --shell flag overrides everything.
+  if (shellOverride) {
+    const p = shellPath(shellOverride);
+    if (p) return { path: p, name: shellOverride };
+    process.stderr.write(`[shmakk] shell "${shellOverride}" not found, falling back to default\n`);
+  }
+
   const env = process.env.SHELL;
   if (env && fs.existsSync(env)) {
     return { path: env, name: path.basename(env) };
   }
-  const fallbacks = ['/bin/bash', '/usr/bin/bash', '/bin/sh'];
+  const fallbacks = ['/bin/bash', '/usr/bin/bash', '/opt/homebrew/bin/bash', '/usr/local/bin/bash', '/bin/sh'];
   for (const f of fallbacks) {
     if (fs.existsSync(f)) return { path: f, name: path.basename(f) };
   }
   return { path: '/bin/sh', name: 'sh' };
 }
 
-function shellArgs(name) {
-  // Login + interactive so the user's normal init runs.
-  // We deliberately keep this minimal: do NOT inject rc files,
-  // do NOT alter prompt. Phase 2 will add hooks for command metadata.
-  switch (name) {
-    case 'fish':
-      return ['-i', '-l'];
-    case 'zsh':
-      return ['-i', '-l'];
-    case 'bash':
-      return ['-i', '-l'];
-    default:
-      return ['-i'];
-  }
-}
-
-module.exports = { detectShell, shellArgs };
+module.exports = { detectShell, shellPath };

package/src/system-prompt.js

@@ -15,6 +15,7 @@ function buildSystemPrompt({
   mcpToolHint = null,
   userRulesText = null,
   userMemoryText = null,
+  supportsVision = false,
 }) {
   return `You are an expert AI coding assistant running inside shmakk.
 
@@ -65,12 +66,13 @@ Tool Call Format:
 
 Available Tools:
 - list_dir: list files/directories
-- read_file: read file contents
+- read_file: read file contents (text or images)
 - write_file: create or overwrite a file
 - make_dir: create a directory
 - run: execute shell commands
 - web_search: search the web
 - fetch_url: fetch a URL
+${supportsVision ? '\nIf images are included in tool results (e.g. read_file on a PNG, or MCP tools that return visuals), you can describe and analyze what you see in them.\n' : ''}
 
 Path Rules:
 - Always use relative paths resolved against \`${roots[0]}\`.

package/src/tools.js

@@ -81,7 +81,7 @@ function within(roots, p) {
 const TOOLS = [
   { type: 'function', function: {
     name: 'read_file',
-    description: 'Read a UTF-8 file inside the workspace. Supports compact partial reads.',
+    description: 'Read a file inside the workspace. Text files support partial reads (head, tail, grep, imports, exports, symbol). Image files (.png/.jpg/.gif/.webp/.bmp/.svg) are returned as base64 for vision analysis.',
     parameters: {
       type: 'object',
       required: ['path'],
@@ -397,6 +397,31 @@ async function dispatchTool(name, args, roots, confirmTool, signal, mcpManager)
     if (!p) return { error: 'path outside workspace' };
     try {
       const buf = fs.readFileSync(p);
+      const ext = path.extname(p).toLowerCase();
+
+      // Image files: return as base64 for vision-capable providers.
+      // Mode-specific sub-reads don't apply to images — always return full.
+      const IMAGE_EXTS = new Set(['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg']);
+      const MIME_MAP = {
+        '.png': 'image/png', '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg',
+        '.gif': 'image/gif', '.webp': 'image/webp', '.bmp': 'image/bmp',
+        '.svg': 'image/svg+xml',
+      };
+      if (IMAGE_EXTS.has(ext)) {
+        const maxImageBytes = 2 * 1024 * 1024; // 2 MB binary (~2.7 MB base64)
+        const slice = buf.length > maxImageBytes ? buf.subarray(0, maxImageBytes) : buf;
+        const b64 = slice.toString('base64');
+        return {
+          content: `[Image: ${path.basename(p)} — ${buf.length} bytes${buf.length > maxImageBytes ? ' (truncated to 2MB for display)' : ''}]`,
+          images: [{
+            mimeType: MIME_MAP[ext],
+            data: b64,
+            dataLength: b64.length,
+            truncated: buf.length > maxImageBytes,
+          }],
+        };
+      }
+
       const text = buf.slice(0, MAX_FILE_BYTES).toString('utf8');
       const lines = text.split(/\r?\n/);
       const mode = args.mode || 'full';