@bahulam/code 0.1.22 → 0.1.24

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahulam/code",
-  "version": "0.1.22",
+  "version": "0.1.24",
   "description": "Bahulam Code — abundance, in your terminal. CLI-first, reliability-first, sub-agents, 65.6% SWE-bench Verified.",
   "type": "module",
   "bin": {

package/src/commands/mcp.mjs

@@ -0,0 +1,296 @@
+/**
+ * `bahulam mcp` — manage MCP server registrations.
+ *
+ *   bahulam mcp add <name> --command <cmd> [--args ...] [--env KEY=VAL ...]
+ *   bahulam mcp add <name> --url <url> [--headers ...]
+ *   bahulam mcp remove <name>
+ *   bahulam mcp list
+ *   bahulam mcp test <name>
+ *
+ * MCP servers are stored in ~/.claude/settings.json under mcpServers,
+ * matching the Claude Desktop / Cursor / Cline portable format.
+ * The settings loader chain reads this file at startup, and the MCP
+ * loader (src/mcp/loader.mjs) spawns and registers tools from it.
+ */
+
+import * as fs from 'node:fs';
+import * as path from 'node:path';
+import * as os from 'node:os';
+
+const RESET = '\x1b[0m';
+const BOLD = '\x1b[1m';
+const DIM = '\x1b[2m';
+const CYAN = '\x1b[36m';
+const GREEN = '\x1b[32m';
+const YELLOW = '\x1b[33m';
+const RED = '\x1b[31m';
+
+function settingsFilePath() {
+    return path.join(os.homedir(), '.claude', 'settings.json');
+}
+
+function loadSettingsFile() {
+    const file = settingsFilePath();
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf-8'));
+    } catch {
+        return {};
+    }
+}
+
+function saveSettingsFile(data) {
+    const file = settingsFilePath();
+    const dir = path.dirname(file);
+    fs.mkdirSync(dir, { recursive: true });
+    fs.writeFileSync(file, JSON.stringify(data, null, 2) + '\n');
+}
+
+function parseArgs(argv) {
+    const parsed = {
+        subcommand: null,
+        name: null,
+        command: null,
+        args: [],
+        url: null,
+        env: {},
+        headers: {},
+        transport: null,
+        help: false,
+        json: false,
+    };
+    const positional = [];
+    for (let i = 0; i < argv.length; i++) {
+        const arg = argv[i];
+        switch (arg) {
+            case '--help': case '-h': parsed.help = true; break;
+            case '--json': parsed.json = true; break;
+            case '--command': parsed.command = argv[++i]; break;
+            case '--url': parsed.url = argv[++i]; break;
+            case '--transport': parsed.transport = argv[++i]; break;
+            case '--env': {
+                const pair = argv[++i] || '';
+                const eq = pair.indexOf('=');
+                if (eq > 0) parsed.env[pair.slice(0, eq)] = pair.slice(eq + 1);
+                break;
+            }
+            case '--header': case '--headers': {
+                const pair = argv[++i] || '';
+                const eq = pair.indexOf(':');
+                if (eq > 0) parsed.headers[pair.slice(0, eq).trim()] = pair.slice(eq + 1).trim();
+                break;
+            }
+            case '--args': {
+                // Collect remaining positional args until next --flag
+                while (i + 1 < argv.length && !argv[i + 1].startsWith('--')) {
+                    parsed.args.push(argv[++i]);
+                }
+                break;
+            }
+            default:
+                if (!arg.startsWith('-')) positional.push(arg);
+                break;
+        }
+    }
+    parsed.subcommand = positional.shift() || null;
+    parsed.name = positional.shift() || null;
+    return parsed;
+}
+
+export async function handleMcpCommand(argv) {
+    const args = parseArgs(argv);
+
+    if (args.help || !args.subcommand) {
+        process.stderr.write(`
+  ${BOLD}bahulam mcp <subcommand>${RESET}
+
+  Manage MCP (Model Context Protocol) server registrations.
+
+  ${BOLD}Subcommands:${RESET}
+
+    ${CYAN}add${RESET} <name> ${DIM}--command <cmd> [--args a b c] [--env KEY=VAL ...]${RESET}
+         Register a stdio MCP server (spawns a child process).
+
+    ${CYAN}add${RESET} <name> ${DIM}--url <url> [--header "Key: Val" ...]${RESET}
+         Register a remote MCP server (SSE, WebSocket, or Streamable HTTP).
+         Transport is auto-detected: ws:// → WebSocket, /sse → SSE, else sHTTP.
+
+    ${CYAN}remove${RESET} <name>          Unregister an MCP server.
+    ${CYAN}list${RESET}                   List all registered MCP servers.
+    ${CYAN}test${RESET} <name>            Connect, list tools, and call one.
+
+  ${BOLD}Examples:${RESET}
+
+    ${DIM}# Supabase MCP (stdio)${RESET}
+    ${CYAN}bahulam mcp add supabase --command npx --args -y @supabase/mcp-server-supabase --env SUPABASE_ACCESS_TOKEN=sbp_xxx${RESET}
+
+    ${DIM}# Remote SSE server${RESET}
+    ${CYAN}bahulam mcp add myapi --url https://api.example.com/sse --header "Authorization: Bearer token123"${RESET}
+
+    ${DIM}# List and test${RESET}
+    ${CYAN}bahulam mcp list${RESET}
+    ${CYAN}bahulam mcp test supabase${RESET}
+
+  ${BOLD}Config location:${RESET} ${settingsFilePath()}
+
+`);
+        if (!args.subcommand) process.exit(1);
+        return;
+    }
+
+    switch (args.subcommand) {
+        case 'add': return handleAdd(args);
+        case 'remove': case 'rm': return handleRemove(args);
+        case 'list': case 'ls': return handleList(args);
+        case 'test': return handleTest(args);
+        default:
+            process.stderr.write(`${RED}✗${RESET} Unknown subcommand: ${args.subcommand}\n`);
+            process.stderr.write(`Run ${CYAN}bahulam mcp --help${RESET} for usage.\n`);
+            process.exit(1);
+    }
+}
+
+function handleAdd(args) {
+    if (!args.name) {
+        process.stderr.write(`${RED}✗${RESET} Server name required. Usage: bahulam mcp add <name> --command <cmd> | --url <url>\n`);
+        process.exit(1);
+    }
+    if (!args.command && !args.url) {
+        process.stderr.write(`${RED}✗${RESET} Either --command or --url is required.\n`);
+        process.exit(1);
+    }
+
+    const settings = loadSettingsFile();
+    if (!settings.mcpServers) settings.mcpServers = {};
+
+    const config = {};
+    if (args.command) {
+        config.command = args.command;
+        if (args.args.length > 0) config.args = args.args;
+    }
+    if (args.url) config.url = args.url;
+    if (Object.keys(args.env).length > 0) config.env = args.env;
+    if (Object.keys(args.headers).length > 0) config.headers = args.headers;
+    if (args.transport) config.transport = args.transport;
+
+    settings.mcpServers[args.name] = config;
+    saveSettingsFile(settings);
+
+    if (args.json) {
+        process.stdout.write(JSON.stringify({ ok: true, name: args.name, config }) + '\n');
+        return;
+    }
+
+    const type = config.command ? 'stdio' : 'remote';
+    const endpoint = config.command || config.url;
+    process.stderr.write(`${GREEN}✓${RESET} Registered MCP server ${BOLD}${args.name}${RESET} (${type}: ${endpoint})\n`);
+    process.stderr.write(`  ${DIM}config${RESET}  ${settingsFilePath()}\n`);
+    process.stderr.write(`  ${DIM}test${RESET}   ${CYAN}bahulam mcp test ${args.name}${RESET}\n\n`);
+}
+
+function handleRemove(args) {
+    if (!args.name) {
+        process.stderr.write(`${RED}✗${RESET} Server name required. Usage: bahulam mcp remove <name>\n`);
+        process.exit(1);
+    }
+    const settings = loadSettingsFile();
+    if (!settings.mcpServers?.[args.name]) {
+        process.stderr.write(`${YELLOW}!${RESET} No MCP server named "${args.name}" is registered.\n`);
+        process.exit(1);
+    }
+    delete settings.mcpServers[args.name];
+    saveSettingsFile(settings);
+
+    if (args.json) {
+        process.stdout.write(JSON.stringify({ ok: true, removed: args.name }) + '\n');
+        return;
+    }
+    process.stderr.write(`${GREEN}✓${RESET} Removed MCP server ${BOLD}${args.name}${RESET}\n`);
+}
+
+function handleList(args) {
+    const settings = loadSettingsFile();
+    const servers = settings.mcpServers || {};
+    const names = Object.keys(servers);
+
+    if (names.length === 0) {
+        process.stderr.write(`${DIM}No MCP servers registered.${RESET}\n`);
+        process.stderr.write(`Add one: ${CYAN}bahulam mcp add <name> --command <cmd>${RESET}\n\n`);
+        return;
+    }
+
+    if (args.json) {
+        process.stdout.write(JSON.stringify({ servers }) + '\n');
+        return;
+    }
+
+    process.stderr.write(`${BOLD}MCP Servers${RESET} (${names.length}):\n`);
+    for (const name of names) {
+        const cfg = servers[name];
+        const type = cfg.command ? 'stdio' : 'remote';
+        const endpoint = cfg.command || cfg.url || 'unknown';
+        const toolCount = cfg._tools ? ` (${cfg._tools} tools)` : '';
+        process.stderr.write(`  ${CYAN}${name.padEnd(20)}${RESET} ${type.padEnd(7)} ${endpoint}${toolCount}\n`);
+    }
+    process.stderr.write(`\n${DIM}Config: ${settingsFilePath()}${RESET}\n\n`);
+}
+
+async function handleTest(args) {
+    if (!args.name) {
+        process.stderr.write(`${RED}✗${RESET} Server name required. Usage: bahulam mcp test <name>\n`);
+        process.exit(1);
+    }
+
+    const settings = loadSettingsFile();
+    const config = settings.mcpServers?.[args.name];
+    if (!config) {
+        process.stderr.write(`${RED}✗${RESET} No MCP server named "${args.name}" is registered.\n`);
+        process.exit(1);
+    }
+
+    process.stderr.write(`${DIM}Connecting to ${args.name}…${RESET}\n`);
+
+    try {
+        const { McpClient } = await import('../mcp/client.mjs');
+        const { loadMcpServers } = await import('../mcp/loader.mjs');
+
+        // Use the loader to handle env expansion
+        const fakeExecutor = {
+            registerMcpTool: () => true,
+            unregisterMcpServer: () => 0,
+        };
+        const mcp = await loadMcpServers(fakeExecutor, { mcpServers: { [args.name]: config } });
+
+        if (mcp.clients.length === 0) {
+            process.stderr.write(`${RED}✗${RESET} Failed to connect to "${args.name}".\n`);
+            process.stderr.write(`${DIM}Check that the command/URL is correct and any required env vars are set.${RESET}\n`);
+            process.exit(1);
+        }
+
+        const client = mcp.clients[0].client;
+        const tools = client.tools;
+
+        process.stderr.write(`${GREEN}✓${RESET} Connected! Server: ${BOLD}${client.serverInfo?.serverInfo?.name || args.name}${RESET}\n`);
+        process.stderr.write(`  ${DIM}tools${RESET}  ${tools.length}\n`);
+        for (const t of tools) {
+            process.stderr.write(`         ${CYAN}${t.name}${RESET} — ${(t.description || '').slice(0, 70)}\n`);
+        }
+
+        // Try calling the first tool that looks like a list/query
+        const listTool = tools.find(t =>
+            /list|query|search|get|fetch/i.test(t.name) && !/delete|update|create|insert|drop/i.test(t.name)
+        );
+
+        if (listTool) {
+            process.stderr.write(`\n${DIM}Testing tool: ${listTool.name}…${RESET}\n`);
+            const result = await client.callTool(listTool.name, {});
+            const preview = String(result).slice(0, 500);
+            process.stderr.write(`${GREEN}✓${RESET} Result: ${preview}${preview.length >= 500 ? '…' : ''}\n`);
+        }
+
+        await mcp.disconnectAll();
+        process.stderr.write(`\n${GREEN}✓${RESET} Test passed.\n\n`);
+    } catch (err) {
+        process.stderr.write(`${RED}✗${RESET} Test failed: ${err.message}\n`);
+        process.exit(1);
+    }
+}

package/src/core/headless.mjs

@@ -18,6 +18,8 @@ import { persistProjectArtifacts } from './project-artifacts.mjs';
 import { BahulamAuth } from '../auth/bahulam-auth.mjs';
 import { ApprovalManager } from './approval.mjs';
 import { PluginRegistry } from '../plugins/registry.mjs';
+import { loadSettings } from '../config/settings.mjs';
+import { loadMcpServers } from '../mcp/loader.mjs';
 // daemon wiring — headless (and `bahulam daemonize`) also starts the socket
 // server + relay bridge when eventlog is enabled. Without this the daemon
 // is invisible to attach clients and to paired mobile devices.
@@ -98,6 +100,9 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
             return outcome;
         };
         toolExecutor = createToolExecutor({ pluginRegistry, delegateRunner: runDelegateFromTool });
+        // Load MCP servers from settings chain (~/.claude/settings.json etc.)
+        const _settings = await loadSettings();
+        const _mcpClients = await loadMcpServers(toolExecutor, _settings);
         const timer = setTimeout(() => {
             emit({ type: 'timeout', duration_s: timeout });
             process.exit(2);
@@ -167,6 +172,10 @@ export async function runHeadless({ instruction, model, timeout = 300, maxCost,
     };
     toolExecutor = createToolExecutor({ pluginRegistry, delegateRunner: runDelegateFromTool });
 
+    // Load MCP servers from settings chain (~/.claude/settings.json etc.)
+    const _settings = await loadSettings();
+    const _mcpClients = await loadMcpServers(toolExecutor, _settings);
+
     // Auto-approve everything — no prompts
     const approval = new ApprovalManager({ autoApprove: true });
 

package/src/core/tool-executor.mjs

@@ -152,8 +152,13 @@ export function createToolExecutor({
         return project.resource.root;
     }
 
-    async function commandCwd(args = {}) {
-        return await resolvePath(args.cwd || null, args);
+    async function commandCwd(args = {}, { readOnly = false } = {}) {
+        try {
+            return await resolvePath(args.cwd || null, args);
+        } catch (err) {
+            if (readOnly) return args.cwd ? path.resolve(args.cwd) : process.cwd();
+            throw err;
+        }
     }
 
     function shellTargetPath(cwd, target) {
@@ -1390,7 +1395,7 @@ export function createToolExecutor({
                 args._riskReason = classification.reason || shellCheck.reason;
             }
             args._classification = classification.classification; // 'safe' or 'contained'
-            const cwd = await commandCwd(args);
+            const cwd = await commandCwd(args, { readOnly: classification.classification === 'safe' });
 
             // Background execution: start via the BackgroundTasks registry
             // and return immediately. Safety checks above still apply;

package/src/local-service/agent-relay.mjs

@@ -755,6 +755,13 @@ export class LocalAgentRelay {
   _makeWorkspaceSessionSubstrate(pluginRegistry) {
     return (agent, node, instruction, { scopedExecutor } = {}) => (async function* (relay) {
       const execContext = await relay._buildExecContext(instruction);
+      // Per-agent model override from YAML — same pattern as agents.mjs:330.
+      // If the agent definition declares a `model` field, it wins over
+      // the session default for this sub-agent's turn.
+      if (agent.model) execContext.model_override = agent.model;
+      if (agent.models && typeof agent.models === 'object' && Object.keys(agent.models).length) {
+        execContext.model_overrides = { ...(execContext.model_overrides || {}), ...agent.models };
+      }
       const slug = agent.slug || agent.command || agent.name || node?.agent_slug || node?.id || 'agent';
       execContext.sub_agent = {
         slug,

package/src/mcp/client.mjs

@@ -13,6 +13,7 @@
 import { spawn } from 'child_process';
 
 const MCP_PROTOCOL_VERSION = '2024-11-05';
+const DEFAULT_REQUEST_TIMEOUT_MS = 60_000;
 
 export class McpClient {
     /**
@@ -102,7 +103,9 @@ export class McpClient {
             }
         });
         this.connected = true;
-        return this._initRemote();
+        await this._initRemote();
+        this._notifyRemote('notifications/initialized', {});
+        return this.serverInfo;
     }
 
     async _connectWebSocket() {
@@ -117,6 +120,7 @@ export class McpClient {
             capabilities: {},
             clientInfo: { name: 'bahulam-code', version: '2.0.0' },
         });
+        this._notifyRemote('notifications/initialized', {});
         return this.serverInfo;
     }
 
@@ -132,6 +136,7 @@ export class McpClient {
             capabilities: {},
             clientInfo: { name: 'bahulam-code', version: '2.0.0' },
         });
+        this._notifyRemote('notifications/initialized', {});
         return this.serverInfo;
     }
 
@@ -145,11 +150,39 @@ export class McpClient {
         return result;
     }
 
+    _notifyRemote(method, params) {
+        if (this.transport?.request) {
+            // WebSocket / sHTTP transports have native request() — use send()
+            // for notifications (no id, no response expected).
+            if (this.transport.send) {
+                this.transport.send({ jsonrpc: '2.0', method, params }).catch(() => {});
+            }
+        } else if (this.transport) {
+            // SSE transport — fire-and-forget via send()
+            this.transport.send({ jsonrpc: '2.0', method, params }).catch(() => {});
+        }
+    }
+
     async _transportRequest(method, params) {
         return new Promise((resolve, reject) => {
             const id = ++this.requestId;
-            this.pending.set(id, { resolve, reject });
-            this.transport.send({ jsonrpc: '2.0', id, method, params });
+            const timeout = setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`MCP request timeout: ${method} (${DEFAULT_REQUEST_TIMEOUT_MS}ms)`));
+                }
+            }, DEFAULT_REQUEST_TIMEOUT_MS);
+            this.pending.set(id, {
+                resolve: (val) => { clearTimeout(timeout); resolve(val); },
+                reject: (err) => { clearTimeout(timeout); reject(err); },
+            });
+            this.transport.send({ jsonrpc: '2.0', id, method, params }).catch(err => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    clearTimeout(timeout);
+                    reject(err);
+                }
+            });
         });
     }
 
@@ -177,7 +210,14 @@ export class McpClient {
             result = await this._request('tools/call', params);
         }
         if (result?.content && Array.isArray(result.content)) {
-            return result.content.filter(c => c.type === 'text').map(c => c.text).join('\n');
+            const textParts = result.content.filter(c => c.type === 'text').map(c => c.text);
+            const imageParts = result.content.filter(c => c.type === 'image');
+            if (imageParts.length > 0 && textParts.length === 0) {
+                return result;
+            }
+            if (textParts.length > 0) {
+                return textParts.join('\n');
+            }
         }
         return result;
     }
@@ -222,7 +262,16 @@ export class McpClient {
     _request(method, params) {
         return new Promise((resolve, reject) => {
             const id = ++this.requestId;
-            this.pending.set(id, { resolve, reject });
+            const timeout = setTimeout(() => {
+                if (this.pending.has(id)) {
+                    this.pending.delete(id);
+                    reject(new Error(`MCP request timeout: ${method} (${DEFAULT_REQUEST_TIMEOUT_MS}ms)`));
+                }
+            }, DEFAULT_REQUEST_TIMEOUT_MS);
+            this.pending.set(id, {
+                resolve: (val) => { clearTimeout(timeout); resolve(val); },
+                reject: (err) => { clearTimeout(timeout); reject(err); },
+            });
             const msg = JSON.stringify({ jsonrpc: '2.0', id, method, params });
             this.process.stdin.write(msg + '\n');
         });

package/src/mcp/loader.mjs

@@ -0,0 +1,98 @@
+/**
+ * MCP Settings Loader — bridges settings-based mcpServers to the tool executor.
+ *
+ * The agent-relay path already spawns MCP servers from plugin manifests.
+ * This module provides the same capability for CLI/REPL/headless mode by
+ * reading mcpServers from the settings chain (~/.claude/settings.json etc.)
+ * and optionally from ~/.bahulam/config.json.
+ *
+ * Usage:
+ *   import { loadMcpServers } from '../mcp/loader.mjs';
+ *   const mcpClients = await loadMcpServers(toolExecutor, settings);
+ *   // ... later ...
+ *   await mcpClients.disconnectAll();
+ */
+
+import { McpClient } from './client.mjs';
+
+/**
+ * Recursively expand ${VAR} patterns in a config object using process.env.
+ * Matches the behavior in agent-relay.mjs _expandEnvInMcpConfig.
+ * @param {*} value
+ * @returns {*}
+ */
+function expandEnv(value) {
+    if (typeof value === 'string') {
+        return value.replace(/\$\{(\w+)\}/g, (_, name) => process.env[name] ?? '');
+    }
+    if (Array.isArray(value)) return value.map(expandEnv);
+    if (value && typeof value === 'object') {
+        return Object.fromEntries(
+            Object.entries(value).map(([k, v]) => [k, expandEnv(v)]),
+        );
+    }
+    return value;
+}
+
+/**
+ * Load and connect MCP servers from settings, registering their tools
+ * with the tool executor.
+ *
+ * @param {object} toolExecutor - the createToolExecutor() instance
+ * @param {object} settings - loaded settings (from loadSettings())
+ * @param {object} [options]
+ * @param {string} [options.pluginName='settings'] - namespace for tool registration
+ * @returns {Promise<{clients: Array, disconnectAll: Function}>}
+ */
+export async function loadMcpServers(toolExecutor, settings, options = {}) {
+    const pluginName = options.pluginName || 'settings';
+    const servers = settings?.mcpServers || {};
+    const clients = [];
+
+    for (const [name, config] of Object.entries(servers)) {
+        if (!config || typeof config !== 'object') continue;
+        if (!config.command && !config.url) continue;
+
+        try {
+            // Merge the config's env block into process.env BEFORE expanding
+            // ${VAR} patterns in args/env. This matches the Claude Desktop
+            // convention: the env block sets vars for the spawned process
+            // AND for ${VAR} expansion in the same config.
+            if (config.env && typeof config.env === 'object') {
+                for (const [k, v] of Object.entries(config.env)) {
+                    if (typeof v === 'string' && !process.env[k]) {
+                        process.env[k] = v;
+                    }
+                }
+            }
+            const expanded = expandEnv(config);
+            const client = new McpClient(expanded);
+            await client.connect();
+            const tools = await client.listTools();
+            for (const tool of tools) {
+                if (toolExecutor.registerMcpTool) {
+                    toolExecutor.registerMcpTool(pluginName, name, tool.name, client, tool.inputSchema || {});
+                }
+            }
+            clients.push({ name, client });
+            if (process.env.MCP_DEBUG) {
+                process.stderr.write(`[mcp:settings] ${name}: ${tools.length} tools registered\n`);
+            }
+        } catch (err) {
+            // One server failure must never block the session.
+            if (process.env.MCP_DEBUG) {
+                process.stderr.write(`[mcp:settings] ${name} failed: ${err.message}\n`);
+            }
+        }
+    }
+
+    return {
+        clients,
+        async disconnectAll() {
+            for (const { name, client } of clients) {
+                try { toolExecutor?.unregisterMcpServer?.(pluginName, name); } catch {}
+                try { await client.disconnect(); } catch {}
+            }
+        },
+    };
+}

package/src/mcp/transport-shttp.mjs

@@ -16,6 +16,7 @@ export class StreamableHttpTransport {
         this.timeout = options.timeout || 30000;
         this.sessionId = options.sessionId || null;
         this.connected = false;
+        this.requestId = 0;
     }
 
     async connect() {
@@ -42,7 +43,7 @@ export class StreamableHttpTransport {
      * Collects all events and returns the final result.
      */
     async request(method, params) {
-        const id = Date.now();
+        const id = ++this.requestId;
         const body = { jsonrpc: '2.0', id, method, params };
 
         const headers = {

package/src/permissions/command-classifier.mjs

@@ -238,6 +238,24 @@ const EXACT_SAFE = new Set([
     'python --version', 'python3 --version',
 ]);
 
+/** Tools commonly invoked with -version/--version to probe the installed version.
+ *  These are pure reads (no file access, no network) and should never require
+ *  project-scoping — they probe the local system's SDK/toolchain. */
+const VERSION_PROBE_TOOLS = new Set([
+    'java', 'javac', 'python', 'python3', 'node', 'ruby', 'go', 'rustc',
+    'deno', 'bun', 'php', 'perl', 'gcc', 'clang', 'make', 'cmake', 'mvn',
+    'gradle', 'pip', 'npm', 'yarn', 'pnpm', 'cargo', 'swift', 'kotlin',
+]);
+
+/** Absolute paths to system probes that are safe to invoke for read-only
+ *  version/path queries. These live outside any project root and should not
+ *  trigger project-scope errors. */
+const SAFE_ABS_PROBE_PATHS = new Set([
+    '/usr/libexec/java_home',
+    '/usr/bin/xcode-select',
+    '/usr/bin/which',
+]);
+
 /**
  * Commands with allowed flags — allowlist approach.
  * Key: command name (or "git diff" for multi-word).
@@ -682,6 +700,23 @@ function classifySingleCommand(command) {
         return { classification: 'safe', reason: 'Echo without expansion' };
     }
 
+    // ── Version probe: <tool> -version / --version (pure OS read, no project needed) ──
+    if (VERSION_PROBE_TOOLS.has(baseCmd)) {
+        const token = tokenize(trimmed);
+        const flag = token[1] || '';
+        if (/^--?v(ersion)?$/.test(flag)) {
+            return { classification: 'safe', reason: `Version probe: ${baseCmd}` };
+        }
+    }
+
+    // ── Known system-probe absolute paths (e.g. /usr/libexec/java_home -V) ──
+    if (SAFE_ABS_PROBE_PATHS.has(baseCmd)) {
+        const rest = trimmed.slice(baseCmd.length).trim();
+        if (!rest || /^--?[a-z]/i.test(rest)) {
+            return { classification: 'safe', reason: `System probe: ${baseCmd}` };
+        }
+    }
+
     // ── Default: contained (unknown command, not explicitly blocked) ──
     return { classification: 'contained', reason: `Unknown command, defaulting to contained: ${baseCmd}` };
 }

package/src/terminal/main.mjs

@@ -291,6 +291,12 @@ async function main() {
     return;
   }
 
+  if (subcommand === 'mcp') {
+    const { handleMcpCommand } = await import('../commands/mcp.mjs');
+    await handleMcpCommand(subcommandArgs);
+    return;
+  }
+
   if (subcommand === 'plugin' || subcommand === 'plugins') {
     // `install`/`pull` moved to top-level. Detect the old form and redirect.
     if (subcommandArgs[0] === 'install' || subcommandArgs[0] === 'pull') {
@@ -338,6 +344,9 @@ async function main() {
     bahulam login                  Sign in via browser
     bahulam logout                 Sign out and clear credentials
     bahulam init                   Scaffold .bahulam config, memory, hooks, tasks
+    bahulam mcp add <name> ...     Register an MCP server
+    bahulam mcp list               List registered MCP servers
+    bahulam mcp test <name>        Test an MCP server connection
     bahulam version                Show version
 
   \x1b[1mDaemon:\x1b[0m

package/src/terminal/repl-model-form.mjs

@@ -1,7 +1,7 @@
 /**
  * Interactive per-role model form for /model (PRD-076 W7).
  *
- * ↑↓ picks a role row, ←→ cycles through [backend default] + the curated
+ * ↑↓ picks a role row, ←→ cycles through [backend default] + the available
  * platform catalog for that role, Enter applies to session overrides,
  * c resets every row to default, Esc cancels. Same raw-stdin overlay
  * pattern as the resume picker (repl-resume.mjs): pause readline, raw
@@ -35,19 +35,19 @@ function formatTokenLimit(value, label) {
   return `${Math.round(n)} ${label}`;
 }
 
-function optionRowsForRole(catalog, row) {
-  const curated = (catalog || []).filter(m => m?.harness_validated && m?.id);
+export function optionRowsForRole(catalog, row) {
+  const available = (catalog || []).filter(m => m?.id);
   const group = String(row?.optionGroup || 'text').toLowerCase();
   if (group === 'image_analysis') {
-    return curated.filter(m => (
+    return available.filter(m => (
       ['image', 'multimodal'].includes(modelCategory(m))
       && !isImageGenerationModel(m)
     ));
   }
   if (group === 'image_generation') {
-    return curated.filter(m => modelCategory(m) === 'image' && isImageGenerationModel(m));
+    return available.filter(m => modelCategory(m) === 'image' && isImageGenerationModel(m));
   }
-  return curated.filter(m => ['text', 'chat'].includes(modelCategory(m)));
+  return available.filter(m => ['text', 'chat', 'multimodal'].includes(modelCategory(m)));
 }
 
 /**
@@ -63,11 +63,11 @@ export async function pickModelOverridesForm({ rl, roles, catalog, fallbackIds,
   if (!process.stdin.isTTY) return null;
   if (rl) rl.pause();
 
-  const catalogRows = (catalog || []).filter(m => m?.harness_validated && m?.id);
+  const catalogRows = (catalog || []).filter(m => m?.id);
   const usingFallback = catalogRows.length === 0;
   const byId = new Map(catalogRows.map(m => [m.id, m]));
 
-  // Per-row option list; a current override that isn't in the curated list
+  // Per-row option list; a current override that isn't in the catalog list
   // is appended so it stays visible and selectable.
   const rows = roles.map(r => {
     const optionIds = usingFallback
@@ -99,9 +99,7 @@ export async function pickModelOverridesForm({ rl, roles, catalog, fallbackIds,
       }
       const meta = byId.get(value);
       const badge = meta ? creditBadge(meta) : '';
-      // Only flag uncurated picks when a curated catalog actually loaded —
-      // in fallback mode every option is a known backend model, not a stray.
-      const flag = meta || usingFallback ? '' : c.yellow(' (uncurated)');
+      const flag = meta && meta.harness_validated === false ? c.yellow(' (uncurated)') : '';
       return `${c.brand(value)}${badge ? ` ${c.dim(badge)}` : ''}${flag}`;
     };
 

package/src/terminal/repl.mjs

@@ -4398,11 +4398,51 @@ async function handleCommand(input, ctx) {
       process.stderr.write(`\n  ${c.brand('Goodbye!')}\n\n`);
       process.exit(0);
 
+    case '/mcp': {
+      await handleMcpSlashCommand(rest, ctx);
+      return;
+    }
+
     default:
       process.stderr.write(`  ${c.gray(`Unknown: ${cmd}. Type /help.`)}\n`);
   }
 }
 
+/**
+ * /mcp slash command — dispatches to the CLI's handleMcpCommand.
+ * Supports: /mcp (status), /mcp add, /mcp remove, /mcp list, /mcp test.
+ */
+async function handleMcpSlashCommand(rest, ctx) {
+  const sub = String(rest || '').trim().split(/\s+/)[0]?.toLowerCase();
+  if (!sub || !['add', 'remove', 'rm', 'list', 'ls', 'test'].includes(sub)) {
+    // No subcommand → show connected server status from session state
+    const mcpClients = ctx?.toolExecutor?._mcpClients || [];
+    if (mcpClients.length === 0) {
+      process.stderr.write(`  ${c.dim('No MCP servers connected. Use:')} ${c.brand('/mcp add <name> --command <cmd> | --url <url>')}\n`);
+      return;
+    }
+    process.stderr.write(`\n  ${c.bold('MCP Servers')} (${mcpClients.length}):\n`);
+    for (let i = 0; i < mcpClients.length; i++) {
+      const cl = mcpClients[i];
+      const name = cl.name || cl.config?.command || 'unknown';
+      const endpoint = cl.config?.url || cl.config?.command || 'unknown';
+      const status = cl.connected ? c.green('connected') : c.yellow('disconnected');
+      process.stderr.write(`  ${c.brand(String(i + 1).padStart(2))}. ${c.brand(name.padEnd(20))} ${status} ${c.dim(endpoint)}\n`);
+    }
+    process.stderr.write('\n');
+    return;
+  }
+
+  // Dispatch to the CLI handler — same code path as `bahulam mcp`
+  try {
+    const { handleMcpCommand } = await import('../commands/mcp.mjs');
+    const mcpArgs = String(rest || '').trim().split(/\s+/);
+    await handleMcpCommand(mcpArgs);
+  } catch (err) {
+    process.stderr.write(`  ${c.red('✗')} ${c.dim(err.message)}\n`);
+  }
+}
+
 // ── Fetch User Profile ──
 
 async function fetchUser(ctx) {

package/src/tools/bash.mjs

@@ -10,6 +10,17 @@
  */
 import { spawn } from 'child_process';
 
+/**
+ * Resolve shell binary and args for the current platform.
+ * Windows uses cmd.exe; Linux/macOS use bash.
+ */
+function shellSpawnArgs(command) {
+    if (process.platform === 'win32') {
+        return ['cmd.exe', ['/d', '/s', '/c', command]];
+    }
+    return ['bash', ['-c', command]];
+}
+
 // Strip ANSI escape sequences
 function stripAnsi(str) {
     // eslint-disable-next-line no-control-regex
@@ -73,7 +84,8 @@ export const BashTool = {
             let killTimer = null;
             let settled = false;
 
-            const proc = spawn('bash', ['-c', input.command], {
+            const [shellBin, shellArgs] = shellSpawnArgs(input.command);
+            const proc = spawn(shellBin, shellArgs, {
                 cwd: input.cwd,
                 env: { ...process.env },
                 stdio: ['pipe', 'pipe', 'pipe'],
@@ -221,7 +233,8 @@ let bgJobId = 0;
 
 function runBackground(command, cwd) {
     const id = ++bgJobId;
-    const proc = spawn('bash', ['-c', command], {
+    const [shellBin, shellArgs] = shellSpawnArgs(command);
+    const proc = spawn(shellBin, shellArgs, {
         cwd,
         detached: true,
         stdio: ['ignore', 'pipe', 'pipe'],

package/src/ui/commands.mjs

@@ -345,15 +345,40 @@ export const COMMANDS = {
     },
 
     '/mcp': {
-        description: 'Show MCP server status',
-        handler(args, state) {
-            if (!state._mcpClients || state._mcpClients.length === 0) {
-                return 'No MCP servers connected.';
+        description: 'Manage MCP servers (add, remove, list, test, status)',
+        async handler(args, state) {
+            const sub = (args || '').trim().split(/\s+/)[0]?.toLowerCase();
+
+            // No subcommand → show status (default)
+            if (!sub || !['add', 'remove', 'rm', 'list', 'ls', 'test'].includes(sub)) {
+                if (!state._mcpClients || state._mcpClients.length === 0) {
+                    return 'No MCP servers connected. Use: /mcp add <name> --command <cmd> | --url <url>';
+                }
+                const lines = state._mcpClients.map((c, i) => {
+                    const name = c.name || c.config?.command || 'unknown';
+                    const endpoint = c.config?.url || c.config?.command || 'unknown';
+                    return `  ${i + 1}. ${name} (${endpoint}) — ${c.connected ? 'connected' : 'disconnected'}`;
+                });
+                return `MCP servers:\n${lines.join('\n')}`;
+            }
+
+            // Dispatch to the CLI handler — same code path as `bahulam mcp`
+            try {
+                const { handleMcpCommand } = await import('../commands/mcp.mjs');
+                const mcpArgs = (args || '').trim().split(/\s+/);
+                // Capture stdout/stderr from the handler
+                const origWrite = process.stdout.write.bind(process.stdout);
+                const origErrWrite = process.stderr.write.bind(process.stderr);
+                let captured = '';
+                process.stderr.write = (chunk) => { captured += chunk; return true; };
+                process.stdout.write = (chunk) => { captured += chunk; return true; };
+                await handleMcpCommand(mcpArgs);
+                process.stderr.write = origErrWrite;
+                process.stdout.write = origWrite;
+                return captured.trim() || 'Done.';
+            } catch (err) {
+                return `MCP command failed: ${err.message}`;
             }
-            const lines = state._mcpClients.map((c, i) =>
-                `  ${i + 1}. ${c.config?.command || 'unknown'} — ${c.connected ? 'connected' : 'disconnected'}`
-            );
-            return `MCP servers:\n${lines.join('\n')}`;
         },
     },
 
@@ -516,7 +541,7 @@ export const COMMANDS = {
  * @param {object} state - agent loop state
  * @returns {{ response: string, exit: boolean }}
  */
-export function executeCommand(input, state) {
+export async function executeCommand(input, state) {
     const parts = input.split(/\s+/);
     const cmd = parts[0].toLowerCase();
     const args = parts.slice(1).join(' ');
@@ -526,7 +551,7 @@ export function executeCommand(input, state) {
         return { response: `Unknown command: ${cmd}. Type /help for available commands.`, exit: false };
     }
 
-    const response = command.handler(args, state);
+    const response = await command.handler(args, state);
     return { response, exit: response === 'EXIT' };
 }