loom-agent 1.2.33 → 1.2.37

package/src/core/agents.js

@@ -60,9 +60,9 @@ function escapeRegExp(s) {
 const BUILTIN_AGENTS = {
   build: {
     id: 'build', name: 'Build', mode: 'primary',
-    description: 'Full development work with all tools enabled.',
+    description: 'Main orchestrator agent: full development work with all tools, drives tasks to completion.',
     tools: ['*'],
-    prompt: null,
+    prompt: 'You are the MAIN ORCHESTRATOR agent. For non-trivial, multi-step work: (1) capture the plan as a todowrite list up front, (2) keep working until every item is completed or explicitly cancelled — never stop mid-task with a summary while todos remain, (3) delegate independent/parallelizable packages via the task tool (research for deep investigation, coder for isolated implementation, reviewer for review, tester for tests, web for browser work, explore for fast code search), (4) verify your work (run tests/typecheck/lint the project actually uses) before declaring done, (5) finish with a terse summary of what changed.',
   },
   plan: {
     id: 'plan', name: 'Plan', mode: 'primary',
@@ -95,6 +95,36 @@ const BUILTIN_AGENTS = {
     tools: ['read', 'glob', 'grep', 'webfetch'],
     prompt: null,
   },
+  research: {
+    id: 'research', name: 'Research', mode: 'subagent',
+    description: 'Deep multi-source research: combines web search/fetch with local code and docs, cross-checks facts, and returns a structured findings report with sources and confidence levels.',
+    tools: ['read', 'glob', 'grep', 'webfetch', 'websearch', 'todowrite'],
+    prompt: 'You are the Research agent. Investigate the topic from multiple independent sources (websearch/webfetch AND local files when relevant). Never state a fact you have not verified in a source. Track your investigation with todowrite when it has many steps. Return a structured report: "## Findings" (numbered facts, each with its source: URL or file:line), "## Gaps" (what you could not verify), "## Recommendation".',
+  },
+  coder: {
+    id: 'coder', name: 'Coder', mode: 'subagent',
+    description: 'Implementation specialist: writes and edits code, runs commands, verifies results. Use for well-scoped feature/bugfix packages that can run independently.',
+    tools: ['*', '!task'],
+    prompt: 'You are the Coder agent. Implement exactly what was delegated — no scope creep. Follow the existing code conventions of the files you touch (imports, naming, JSDoc/typing style). Verify your work (run the relevant tests/typecheck) before reporting. Final report: files changed with line deltas, commands run and their outcomes, and anything left undone.',
+  },
+  reviewer: {
+    id: 'reviewer', name: 'Reviewer', mode: 'subagent',
+    description: 'Code review specialist: reads diffs and files, runs read-only git/inspection commands, returns severity-ranked findings with file:line references.',
+    tools: ['read', 'glob', 'grep', 'bash', 'webfetch'],
+    prompt: 'You are a strict code reviewer. Hunt for: correctness bugs, security issues, data loss risks, broken edge cases, missing tests, and convention violations. Inspect the actual diff/files (git diff, git log, read) — never review code you have not read. Findings first, ranked by severity (critical/major/minor), each with file:line and a concrete suggested fix. If there are no issues, say so explicitly and note what you checked.',
+  },
+  tester: {
+    id: 'tester', name: 'Tester', mode: 'subagent',
+    description: 'Test engineer: writes tests that reproduce the issue, runs them, iterates until green. Use for test creation, bug reproduction, and verification work.',
+    tools: ['read', 'write', 'edit', 'glob', 'grep', 'bash', 'todowrite'],
+    prompt: 'You are the Tester agent. First reproduce the behavior (write a failing test when possible), run it, then iterate until the outcome is deterministic and understood. Use the project\'s real test runner (inspect package.json/bunfig — never invent commands). Report: exact commands run, pass/fail counts, and what the tests prove.',
+  },
+  web: {
+    id: 'web', name: 'Web', mode: 'subagent',
+    description: 'Browser specialist: drives a real headless browser (navigate, click, fill, read DOM, screenshot) plus webfetch/websearch. Use for live-site inspection, rendered-page research, and end-to-end UI verification.',
+    tools: ['read', 'glob', 'grep', 'webfetch', 'websearch', 'browser', 'todowrite'],
+    prompt: 'You are the Web agent with a real headless browser (the browser tool). Prefer the browser over webfetch whenever the page needs JavaScript rendering, clicking, or form interaction. Verify claims by reading the ACTUAL DOM (browser text/eval/links) — never guess page content. Use screenshots to confirm visual state when relevant. Stay on http/https pages; do not use the browser to access local files.',
+  },
 };
 
 function readOnlyTools() {

package/src/core/cli.js

@@ -9,6 +9,10 @@ const { ProviderRouter, PROVIDERS } = require('../providers');
 const { saveSession, loadSession } = require('./session-store');
 const { defaultMcpInstall } = require('./plugin-cmd');
 
+// Single source of truth for every version string the CLI prints (banner,
+// --version). package.json is the only place to bump.
+const VERSION = require('../../package.json').version;
+
 const LOOM_BASE = `
  ██╗      ██████╗  ██████╗ ███╗   ███╗      ██████╗ ██████╗ ██████╗ ███████╗
  ██║     ██╔═══██╗██╔═══██╗████╗ ████║     ██╔════╝██╔═══██╗██╔══██╗██╔════╝
@@ -38,7 +42,7 @@ class LoomCLI {
       terminal: true,
     });
     console.log(LOOM_BASE);
-    console.log(`\n  Loom Code v1.2.28 — AI Coding Agent for the terminal`);
+    console.log(`\n  Loom Code v${VERSION} — AI Coding Agent for the terminal`);
     console.log(`  Press Ctrl+C or ESC to interrupt | /help for commands\n`);
 
     process.stdin.on('keypress', (str, key) => {
@@ -391,7 +395,13 @@ class LoomCLI {
    */
   async openGraphBrowser(graph) {
     const http = require('http');
-    const template = fs.readFileSync(path.join(__dirname, '..', 'web', 'graph-view.html'), 'utf8');
+    let template;
+    try {
+      template = fs.readFileSync(path.join(__dirname, '..', 'web', 'graph-view.html'), 'utf8');
+    } catch {
+      console.log('Browser graph view is not available (the web UI has been removed).');
+      return;
+    }
     const html = template.replace('window.__GRAPH__ || { nodes: [], edges: [] }', JSON.stringify(graph).replace(/<\/script/gi, '<\\/script'));
     const server = http.createServer((req, res) => {
       const p = req.url || '/';
@@ -460,7 +470,31 @@ class LoomCLI {
 }
 
 function findBun() {
-  // Check common installation paths
+  // 1. The bundled bun binary shipped via @oven/bun-<platform> optional deps
+  //    (npm i -g loom-agent brings its own bun — works with zero setup).
+  try {
+    const PKGS = {
+      'win32-x64': 'bun-windows-x64',
+      'win32-arm64': 'bun-windows-aarch64',
+      'darwin-x64': 'bun-darwin-x64',
+      'darwin-arm64': 'bun-darwin-aarch64',
+      'linux-x64': 'bun-linux-x64',
+      'linux-arm64': 'bun-linux-aarch64',
+    };
+    const short = PKGS[process.platform + '-' + process.arch];
+    if (short) {
+      const exe = process.platform === 'win32' ? 'bun.exe' : 'bun';
+      const pkgRoot = path.join(__dirname, '..', '..');
+      const candidates = [
+        path.join(pkgRoot, 'node_modules', '@oven', short, 'bin', exe), // nested
+        path.join(pkgRoot, '..', '@oven', short, 'bin', exe),           // hoisted
+      ];
+      for (const c of candidates) {
+        if (fs.existsSync(c)) return c;
+      }
+    }
+  } catch {}
+  // 2. Common installation paths
   const paths = [
     path.join(os.homedir(), '.bun', 'bin', 'bun.exe'),
     path.join(os.homedir(), '.bun', 'bin', 'bun'),
@@ -471,7 +505,7 @@ function findBun() {
   for (const p of paths) {
     if (fs.existsSync(p)) return p;
   }
-  // Search PATH (Windows: where.exe, POSIX: which)
+  // 3. Search PATH (Windows: where.exe, POSIX: which)
   try {
     const { execSync } = require('child_process');
     const isWin = process.platform === 'win32';
@@ -485,7 +519,6 @@ async function main() {
   const cli = new LoomCLI();
 
   const args = process.argv.slice(2);
-  const VERSION = require('../../package.json').version;
 
   const printIdx = args.indexOf('-p');
   const printLongIdx = args.indexOf('--print');
@@ -506,8 +539,7 @@ if (args.includes('--help') || args.includes('-h')) {
     console.log('  loom --basic            Use basic line-mode REPL (no TUI)');
     console.log('  loom --auto             Auto-approve permission prompts');
     console.log('  loom acp                ACP server (JSON-RPC over stdio, for editor plugins)');
-    console.log('  loom web                Browser interface (HTTP server, opens the browser)');
-    console.log('  loom attach <url>       Attach the terminal to a running `loom web` server');
+    console.log('  loom add mcp <spec>     Add an MCP server (same syntax as /mcp add)');
     console.log('  loom -s <session-id>    Resume a saved session');
     console.log('  loom --version           Show version');
     console.log('  loom --help              Show this help');
@@ -527,6 +559,23 @@ if (args.includes('--help') || args.includes('-h')) {
     return;
   }
 
+  // loom add mcp <name> [--] <command> [args...] — register an MCP server from
+  // the shell with the same one-liner syntax as /mcp add (quote paths with
+  // spaces; -e KEY=V for env). Exits 0 on success.
+  if (args[0] === 'add' && args[1] === 'mcp') {
+    const spec = args.slice(2);
+    if (!spec.length) {
+      console.log('Usage: loom add mcp [-e KEY=V] <name> [--] <command> [args...]');
+      console.log('Example: loom add mcp fetch -- npx -y mcp-server-fetch');
+      process.exit(1);
+    }
+    const { mcpAddLineCmd } = require('./plugin-cmd');
+    const msg = mcpAddLineCmd(spec.join(' '));
+    const ok = typeof msg === 'string' && msg.startsWith('Added');
+    console.log(ok ? msg : 'Error: ' + msg);
+    process.exit(ok ? 0 : 1);
+  }
+
   if (sessionId && sIndex !== -1) {
     const data = loadSession(sessionId);
     if (data && data.messages && data.messages.length) {

package/src/core/permissions.js

@@ -34,7 +34,7 @@ const DANGER_PATTERNS = [
 // user config).
 const PERMISSION_KEYS = [
   'read', 'edit', 'glob', 'grep', 'bash', 'task', 'skill', 'lsp', 'question',
-  'webfetch', 'websearch',
+  'webfetch', 'websearch', 'browser',
   'external_directory', 'doom_loop',
 ];
 
@@ -53,6 +53,15 @@ const DEFAULT_PERMISSIONS = {
     '*.env.*': 'deny',
     '*.env.example': 'allow',
   },
+  // Browser: passive reads of live pages are as safe as webfetch (allow);
+  // INTERACTIVE actions (click/fill/press) can submit forms and change remote
+  // state, so they prompt by default. Patterns match "action arg".
+  browser: {
+    '*': 'allow',
+    'click*': 'ask',
+    'fill*': 'ask',
+    'press*': 'ask',
+  },
 };
 
 // Tools that write files map onto the "edit" permission (OpenCode semantics:
@@ -71,6 +80,7 @@ const TOOL_TO_PERMISSION = {
   ask: 'question',
   webfetch: 'webfetch',
   websearch: 'websearch',
+  browser: 'browser',
   todowrite: null,   // never prompts
   mcp: null,         // wired by the session (only the "add" action prompts)
 };
@@ -301,6 +311,7 @@ class PermissionManager {
       case 'ask': return String(inp.question ?? inp.text ?? '');
       case 'webfetch': return String(inp.url ?? '');
       case 'websearch': return String(inp.query ?? '');
+      case 'browser': return String(inp.action ?? '') + ' ' + String(inp.url ?? inp.selector ?? inp.key ?? inp.path ?? '');
       default: return String(inp.command ?? inp.filePath ?? inp.path ?? inp.pattern ?? inp.url ?? '');
     }
   }

package/src/core/plugin-cmd.js

@@ -123,6 +123,7 @@ function mcpHelp() {
     '',
     'Example (claude-compatible): /mcp add stm32 -- "C:\\stm32-mcp\\.venv\\Scripts\\python.exe" -m stm32_mcp.server',
     'Example with env: /mcp add -e BRAVE_API_KEY=x brave-search -- npx -y @modelcontextprotocol/server-brave-search',
+    'From the shell (same syntax): loom add mcp [-e KEY=V] <name> [--] <command> [args...]',
     'The "--" separator is optional; quote any path with spaces. Env keys are usable as $KEY in args.',
     'In the /mcp and /connectors browsers, press A to add with the same one-liner syntax.',
   ].join('\n');

package/src/core/session.js

@@ -23,6 +23,13 @@ const COMPACT_DEFAULT_THRESHOLD = 0.75;
 const COMPACT_KEEP_MESSAGES = 8;
 // Never compact conversations shorter than this.
 const COMPACT_MIN_MESSAGES = 6;
+// Drive-to-completion: how many continuation nudges one turn may spend when
+// the model stops with todos still unfinished (the "stops between tasks"
+// failure). Capped so a model that refuses to update its todos cannot spin.
+const MAX_DRIVE_NUDGES = 5;
+// Transient provider failures (network blip, 5xx, stream reset) retry the
+// model call this many times before the turn surfaces an error.
+const PROVIDER_RETRIES = 2;
 
 /**
  * @typedef {Object} SpeedStats
@@ -244,6 +251,19 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
 - If the user wants code changes, tell them to switch to Build mode (Tab or /build) and resend.` : ''}${this.config.outputStyle ? `\n\n## Output style\n${this.config.outputStyle}` : ''}`;
   }
 
+  // System-prompt suffix for the active PRIMARY agent (build/plan/chat): each
+  // primary can carry a role prompt (the Build orchestrator instructions, the
+  // Plan agent role, …) that appends after the base prompt. Child sessions and
+  // @agent turns already use _agentBlock, and primaries never set this.agent,
+  // so the two cannot stack. Resolved lazily so per-turn config changes apply.
+  _primaryBlock() {
+    if (this._isChild || this.agent) return '';
+    let agent = null;
+    try { agent = require('./agents').resolveAgent(this.mode); } catch { return ''; }
+    if (!agent || !agent.prompt) return '';
+    return '\n\n## Acting as the "' + agent.name + '" agent\n' + agent.prompt + '\n';
+  }
+
   // Create ./LOOM.md with a template when missing, so memory exists from the
   // first turn (Claude Code behavior). Disable with LOOM_MEM_AUTO=0 (tests).
   ensureMemoryFile() {
@@ -542,13 +562,19 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
           interrupted: true,
         });
       }
-      return { type: 'text', content: streamed || '(interrupted)', interrupted: true };
+      return { type: 'text', content: streamed || '(interrupted before any text was streamed)', interrupted: true };
     };
 
     // No tool-use cap: the model decides when a turn is finished; the user can
     // always Esc-interrupt a runaway loop.
     let ranTools = false;
     let nudged = false;
+    let toolCallsThisTurn = 0;
+    // Drive-to-completion state (see the no-toolCalls branch below).
+    let driveNudges = 0;
+    let todowroteThisTurn = false;
+    // Transient provider-error retry state.
+    let providerRetries = 0;
     while (true) {
       if (this.interrupted) {
         return finishInterrupted();
@@ -575,6 +601,16 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
             continue;
           }
         }
+        // Transient provider failure (network blip, 5xx, stream reset): retry
+        // the model call a couple of times instead of killing the turn
+        // mid-task. No tools ran for this iteration, so a retry is side-effect
+        // free.
+        if (providerRetries < PROVIDER_RETRIES) {
+          providerRetries++;
+          await new Promise((resolve) => setTimeout(resolve, 400 * providerRetries));
+          if (this.interrupted) return finishInterrupted();
+          continue;
+        }
         return { type: 'error', content: err.message };
       }
 
@@ -611,15 +647,59 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
         // Silent-stop guard: models occasionally end a turn with an EMPTY
         // reply right after running tools (truncation / provider hiccup),
         // which reads to the user like "the agent just stopped". One
-        // automatic continuation instead of dead-ending with '(no response)'.
+        // automatic continuation instead of dead-ending with a placeholder.
         if (!text.trim() && ranTools && !nudged && !this.interrupted) {
           nudged = true;
-          this.addMessage({ role: 'user', content: '(your last reply was empty — continue where you left off and finish the task)' });
+          this.addMessage({
+            role: 'user',
+            content: '(the model returned an empty reply after ' + toolCallsThisTurn +
+              ' tool call(s) — continue where you left off and finish the task)',
+          });
           continue;
         }
-        return { type: 'text', content: text || '(no response)' };
+        // Drive-to-completion guard: the model stopped calling tools in the
+        // middle of tracked work (todos written this turn still
+        // pending/in_progress). Inject one continuation that quotes the
+        // model's ACTUAL last message and lists the unfinished items — up to
+        // MAX_DRIVE_NUDGES times — so a premature summary does not strand the
+        // task. The model can stop cleanly by completing or cancelling the
+        // items via todowrite. Plan/chat modes are excluded (plan drafts are
+        // meant to end with pending steps).
+        if (!this.interrupted && this.mode === 'build' && ranTools && todowroteThisTurn && driveNudges < MAX_DRIVE_NUDGES) {
+          const unfinished = (this.todos || []).filter((t) => t.status === 'pending' || t.status === 'in_progress');
+          if (unfinished.length) {
+            driveNudges++;
+            const list = unfinished.slice(0, 20).map((t) => '- [' + t.status + '] ' + t.content).join('\n');
+            // Quote what the model actually said — a canned nudge alone gives
+            // the user (and the model) no clue WHERE the turn went off the rails.
+            const lastReply = text.replace(/\s+/g, ' ').trim();
+            const snippet = lastReply
+              ? '\nYour last message was: "' + (lastReply.length > 240 ? lastReply.slice(0, 240) + '…' : lastReply) + '"'
+              : '';
+            this.addMessage({
+              role: 'user',
+              content: '(unfinished work detected: ' + unfinished.length + ' todo(s) still open:\n' + list + snippet +
+                '\nYour reply stopped the turn, but the work above is not done — continue exactly where you left off and finish it. ' +
+                'Only stop when every item is completed or cancelled via todowrite, or when something concrete blocks you — then name the blocker.)',
+            });
+            continue;
+          }
+        }
+        // Surface WHAT is still open when a build-mode turn that WROTE todos
+        // ends with work remaining (same signal as the nudge above), so the
+        // UI can show the real leftovers instead of a generic "stopped"
+        // placeholder. Stale todos from older turns stay silent.
+        const openTodos = (this.mode === 'build' && todowroteThisTurn)
+          ? (this.todos || []).filter((t) => t.status === 'pending' || t.status === 'in_progress')
+          : [];
+        return {
+          type: 'text',
+          content: text || '(the model ended the turn without any text)',
+          openTodos: openTodos.length ? openTodos : undefined,
+        };
       }
       ranTools = true;
+      toolCallsThisTurn += toolCalls.length;
 
       // Execute independent tool calls in parallel; results are appended in the
       // original call order so the conversation history stays deterministic.
@@ -659,7 +739,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
         // are checked separately where they apply.
         const permKey = { read:'read', edit:'edit', write:'edit', glob:'glob', grep:'grep', bash:'bash',
                           task:'task', skill:'skill', lsp:'lsp', question:'question', ask:'question', webfetch:'webfetch',
-                          websearch:'websearch' }[tc.name];
+                          websearch:'websearch', browser:'browser' }[tc.name];
         const isMcpAdd = tc.name === 'mcp' && tc.input && tc.input.action === 'add';
         if (permKey || isMcpAdd) {
           const arg = this.permissions.permissionArg(tc.name, tc.input || {});
@@ -734,6 +814,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
         this.addMessage({ role: 'tool', toolCallId: tc.id, content: text });
         // Persist real todo state when the model uses the todowrite tool.
         if (tc.name === 'todowrite' && !outcome.error) {
+          todowroteThisTurn = true;
           this.setTodos(tc.input && tc.input.todos);
           // Notify observers (sidebar, etc.) over the tiny event bus — the TUI
           // subscribes once and the panel updates without a re-render cycle.
@@ -805,7 +886,7 @@ ${this.mode === 'build' ? `- You have all tools available: read, write, edit, ba
       maxTokens: this.config.maxTokens || 8192,
       temperature: this.config.temperature ?? 0.7,
       tools: toolDefs,
-      system: this.systemPrompt + (this._skillBlock || '') + (this._agentBlock || ''),
+      system: this.systemPrompt + (this._skillBlock || '') + (this._agentBlock || '') + this._primaryBlock(),
       signal: this.abortController?.signal,
       // Extended thinking: models tagged 'reasoning' reason BEFORE every
       // reply — including after each tool result — so complex tasks get

package/src/mcp/mcp-client.js

@@ -1,4 +1,34 @@
 const { spawn } = require('child_process');
+// Minimal OS/runtime baseline handed to every spawned MCP server (see note in
+// connectToJson). Explicit cfg.env keys are layered on top per server.
+const MCP_ENV_KEYS = [
+  'PATH', 'PATHEXT', 'COMSPEC', 'SystemRoot', 'windir', 'SystemDrive',
+  'TEMP', 'TMP', 'HOME', 'USERPROFILE', 'APPDATA', 'LOCALAPPDATA',
+  'PROGRAMFILES', 'PROGRAMDATA', 'ALLUSERSPROFILE', 'COMMONPROGRAMFILES',
+  'PROCESSOR_ARCHITECTURE', 'NUMBER_OF_PROCESSORS', 'OS',
+  'COMPUTERNAME', 'USERNAME', 'LANG', 'TZ', 'TERM', 'SHELL',
+  'XDG_CONFIG_HOME', 'HTTP_PROXY', 'HTTPS_PROXY', 'NO_PROXY',
+];
+/** @returns {Record<string,string>} filtered copy of process.env */
+function buildMcpBaseEnv() {
+  const out = /** @type {Record<string,string>} */ ({});
+  for (const k of MCP_ENV_KEYS) {
+    const v = process.env[k];
+    if (v !== undefined) out[k] = v;
+  }
+  return out;
+}
+const MCP_BASE_ENV = buildMcpBaseEnv();
+
+/**
+ * Compose the environment for one MCP server process: the filtered baseline
+ * plus whatever that server's config explicitly declares (cfg.env wins).
+ * @param {{env?: Record<string,string|undefined>|null}} cfg
+ * @returns {Record<string,string>}
+ */
+function mcpSpawnEnv(cfg) {
+  return Object.assign({}, MCP_BASE_ENV, cfg.env || {});
+}
 const { loadServers } = require('./mcp-manager');
 
 let toolCachePromise = null;
@@ -22,9 +52,19 @@ function killTree(child) {
 
 function connectToJson(cfg, timeoutMs) {
   return new Promise((resolve, reject) => {
+    // MCP servers are third-party processes. Inheriting the parent's FULL
+    // environment would hand every provider API key / cloud token / cookie in
+    // the user's shell to whatever npm package a config spawns. Instead pass a
+    // minimal OS/runtime baseline plus only what cfg.env explicitly declares —
+    // per-server secrets belong in the server's own env config, not leaked by
+    // inheritance. (network proxies forwarded; they carry routing, not auth.)
+    // Per-server environment via allowlist + explicit cfg.env only — see
+    // buildMcpBaseEnv/mcpSpawnEnv above; inheriting all of process.env would
+    // leak provider keys to every third-party server.
+    const env = mcpSpawnEnv(cfg);
     const child = spawn(cfg.command, cfg.args || [], {
       stdio: ['pipe', 'pipe', 'pipe'],
-      env: Object.assign({}, process.env, cfg.env || {}),
+      env,
       // No console window for stdio MCP servers: on Windows spawn() would
       // otherwise pop a flashing console up and down while chats happen.
       windowsHide: true,
@@ -198,4 +238,4 @@ function getCachedTools() {
   return warm();
 }
 
-module.exports = { getTools, getCachedTools, clearCache, buildToolName, callTool, warm, callRpc, killTree };
+module.exports = { getTools, getCachedTools, clearCache, buildToolName, callTool, warm, callRpc, killTree, buildMcpBaseEnv, mcpSpawnEnv };

package/src/skills/skills-manager.js

@@ -11,6 +11,19 @@ function validateUrl(url) {
   } catch { return false; }
 }
 
+/**
+ * Reduce an install target to a single safe folder name under ~/.loom/skills.
+ * Strict allowlist (alnum/_/./-, ≤64 chars): drives, separators and '..'
+ * segments are rejected outright, never silently collapsed, so remote-provided
+ * names can't rename unexpectedly or point outside the skills directory.
+ * @param {unknown} name
+ * @returns {string|null} cleaned single-segment name, or null when unusable
+ */
+function safeSkillName(name) {
+  const s = typeof name === 'string' ? name.trim() : '';
+  return /^[A-Za-z0-9][A-Za-z0-9_.-]{0,63}$/.test(s) ? s : null;
+}
+
 const LOOM_DIR = path.join(os.homedir(), '.loom');
 
 function globalSkillsDir() {
@@ -111,8 +124,17 @@ function installFrom(srcDir, targetName) {
   if (!fs.existsSync(path.join(src, 'SKILL.md'))) {
     return { error: `No SKILL.md in ${src}` };
   }
-  const name = targetName || path.basename(src);
-  const dest = path.join(globalSkillsDir(), name);
+  const name = safeSkillName(targetName != null ? targetName : path.basename(src));
+  if (!name) {
+    return { error: `Invalid skill name: ${JSON.stringify(targetName)} — use letters/digits/-/_ only` };
+  }
+  const destRoot = globalSkillsDir();
+  const dest = path.join(destRoot, name);
+  // Paranoia check: `name` is already a sanitized single segment, so this can
+  // not trip short of path.join behavior changing underneath us.
+  if (path.resolve(dest) !== path.join(path.resolve(destRoot), name)) {
+    return { error: 'Invalid install location' };
+  }
   if (fs.existsSync(dest)) {
     fs.rmSync(dest, { recursive: true, force: true });
   }
@@ -210,4 +232,5 @@ module.exports = {
   globalSkillsDir,
   agentsSkillsDir,
   projectSkillsDir,
+  safeSkillName,
 };