@bahulam/code 0.1.21 → 0.1.23

package/package.json

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

package/src/agents/loader.mjs

@@ -93,6 +93,7 @@ export class AgentLoader {
             slug,
             normalizeKey(agent.name),
             normalizeKey(agent.id),
+            ...(Array.isArray(agent.aliases) ? agent.aliases.map(normalizeKey) : []),
         ].filter(Boolean);
 
         // Earlier search paths have higher precedence: project beats global,

package/src/agents/parser.mjs

@@ -189,6 +189,7 @@ function normalizeAgent(data) {
         model: data.model || agent.model || null,
         models: data.models && typeof data.models === 'object' ? data.models : {},
         tools: Array.isArray(data.tools) ? data.tools : Array.isArray(config?.tools) ? config.tools : [],
+        aliases: Array.isArray(data.aliases) ? data.aliases : Array.isArray(metadata.aliases) ? metadata.aliases : [],
         capabilities: Array.isArray(data.capabilities) ? data.capabilities : Array.isArray(metadata.capabilities) ? metadata.capabilities : [],
         domains: Array.isArray(data.domains) ? data.domains : Array.isArray(metadata.domains) ? metadata.domains : [],
         hooks: data.hooks || {},

package/src/agents/registry.mjs

@@ -30,6 +30,7 @@ export function compactAgentMetadata(agent) {
     tools: Array.isArray(agent.tools) ? agent.tools : [],
     capabilities: Array.isArray(agent.capabilities) ? agent.capabilities : [],
     domains: Array.isArray(agent.domains) ? agent.domains : [],
+    aliases: Array.isArray(agent.aliases) ? agent.aliases : [],
     source_scope: agent.source_scope || 'unknown',
     source: agent.source || '',
     content_hash: agent.content_hash || '',
@@ -81,6 +82,7 @@ export function createAgentRegistry({
       tools: normalizeAgentTools(agentDef.tools || agentDef.agent_tools),
       capabilities: Array.isArray(agentDef.capabilities) ? agentDef.capabilities : [],
       domains: Array.isArray(agentDef.domains) ? agentDef.domains : [],
+      aliases: Array.isArray(agentDef.aliases) ? agentDef.aliases.map(String).filter(Boolean) : [],
       prompt: agentDef.prompt || agentDef.system_prompt || agentDef.systemPrompt || '',
       system_prompt: agentDef.system_prompt || agentDef.systemPrompt || agentDef.prompt || '',
       source_scope: 'plugin',
@@ -160,7 +162,7 @@ export function createAgentRegistry({
     const allowlist = new Set(pluginAgentAllowlist());
     for (const agent of listPluginAgents()) {
       if (!agent.slug || bySlug.has(agent.slug)) continue;
-      if (channel === 'workspace' || allowlist.has(agent.slug)) {
+      if (channel === 'workspace' || allowlist.has(agent.slug) || agent.entry_agent === true) {
         bySlug.set(agent.slug, { ...agent, runnable: true });
       }
     }
@@ -190,6 +192,7 @@ export function createAgentRegistry({
       agent.id,
       agent.command,
       agent.name,
+      ...(Array.isArray(agent.aliases) ? agent.aliases : []),
     ].some(value => String(value || '').trim().toLowerCase() === needle)) || null;
   }
 
@@ -212,6 +215,7 @@ export function createAgentRegistry({
           agent.name,
           agent.description,
           agent.role,
+          ...(Array.isArray(agent.aliases) ? agent.aliases : []),
           ...(Array.isArray(agent.capabilities) ? agent.capabilities : []),
           ...(Array.isArray(agent.domains) ? agent.domains : []),
         ].some(value => String(value || '').toLowerCase().includes(query));

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/commands/plugin-manage.mjs

@@ -7,8 +7,9 @@
  *   yet; if a bare name is given to `install`, we look it up in the
  *   awesome-bahulam-plugins index (a plain JSON manifest hosted in the
  *   community repo).
- * - Install target: `~/.bahulam/plugins/` by default, `.bahulam/plugins/`
- *   with --project. Never global npm, never modifies the user's PATH.
+ * - Install target: `~/.bahulam/plugins/`. Always. Plugins have no project
+ *   scope (skills have one, separately). Never global npm, never modifies
+ *   the user's PATH.
  * - Disable: rename directory to `<name>.disabled`. The plugin registry
  *   only scans directories with a valid manifest, so this hides the plugin
  *   without deleting it. `enable` reverses the rename.
@@ -24,7 +25,7 @@ import { spawn } from 'node:child_process';
 import { parsePluginManifestFile } from '../plugins/manifest.mjs';
 import { preflightPlugin, existingInstalledNames } from '../plugins/preflight.mjs';
 import { parsePiSource } from '../plugins/pi-compose.mjs';
-import { bahulamHome } from '../core/paths.mjs';
+import { bahulamHome, pluginDirs, pluginInstallDir } from '../core/paths.mjs';
 
 const RESET = '\x1b[0m';
 const BOLD = '\x1b[1m';
@@ -36,17 +37,20 @@ const RED = '\x1b[31m';
 
 const INSTALL_STAMP = '.bahulam-plugin.json';
 
-function searchDirs(cwd) {
-  return [
-    { scope: 'project', dir: path.join(cwd, '.bahulam', 'plugins') },
-    { scope: 'global', dir: path.join(bahulamHome(), 'plugins') },
-  ];
+function searchDirs(_cwd) {
+  // One scope. `_cwd` is accepted but ignored so callers don't churn, and so
+  // nobody is tempted to reintroduce cwd-dependence here.
+  return pluginDirs().map(dir => ({ scope: 'global', dir }));
 }
 
-export function pluginTargetDir({ global, cwd }) {
-  return global
-    ? path.join(bahulamHome(), 'plugins')
-    : path.join(cwd, '.bahulam', 'plugins');
+/**
+ * Where a plugin install lands: always the global root.
+ *
+ * The old `{global, cwd}` options are accepted and ignored — `global: false`
+ * no longer selects a project directory, because there isn't one.
+ */
+export function pluginTargetDir() {
+  return pluginInstallDir();
 }
 
 function readManifest(dir) {
@@ -73,8 +77,12 @@ function scanInstalled(cwd) {
       // else in the plugins/ dir is stray (readManifest returns null).
       if (!parsed && !disabled) continue;
       const stamp = readStamp(pluginDir);
-      const agentSlugs = (parsed?.manifest?.config?.agents || [])
-        .map(a => a.slug || a.name).filter(Boolean);
+      const agents = parsed?.manifest?.config?.agents || [];
+      const agentSlugs = agents.map(a => a.slug || a.name).filter(Boolean);
+      const entryAgentSlugs = agents
+        .filter(a => a.entry_agent === true)
+        .map(a => a.slug || a.name)
+        .filter(Boolean);
       found.push({
         scope,
         directory: pluginDir,
@@ -87,6 +95,7 @@ function scanInstalled(cwd) {
         views: parsed?.manifest?.config?.views?.length || 0,
         composes: parsed?.manifest?.config?.composes?.length || 0,
         agentSlugs,
+        entryAgentSlugs,
         disabled,
         origin: stamp?.origin || null,
         installed_at: stamp?.installed_at || null,
@@ -433,11 +442,12 @@ async function cmdList(args, cwd) {
   const plugins = scanInstalled(cwd);
   const pi = scanPiIngredients();
   const allowlist = new Set(await readAgentAllowlist(cwd));
-  // A pack is "enabled" for this session when at least one of its
-  // agents is in plugins.agent_allowlist (PRD-102 §6.2.1). Packs with
-  // no agents (tools-only packs) always count as enabled — the
-  // allowlist gate only exists for agents.
-  const enabled = (p) => p.agentSlugs.length === 0 || p.agentSlugs.some(s => allowlist.has(s));
+  // A pack is "enabled" for this session when it has no agents, exposes an
+  // entry agent, or has at least one agent explicitly allowlisted. Helpers
+  // without entry_agent stay workspace-scoped until allowlisted.
+  const enabled = (p) => p.agentSlugs.length === 0
+    || (p.entryAgentSlugs || []).length > 0
+    || p.agentSlugs.some(s => allowlist.has(s));
   const composerFor = (piName) => plugins.filter(p =>
     (p.composes > 0) && Boolean(p) // composes is a count; details need re-read
   );
@@ -460,6 +470,7 @@ async function cmdList(args, cwd) {
       ...p,
       enabled: enabled(p),
       allowlisted_agents: p.agentSlugs.filter(s => allowlist.has(s)),
+      entry_agents: p.entryAgentSlugs || [],
     }));
     process.stdout.write(JSON.stringify({
       ok: true,
@@ -497,7 +508,7 @@ async function cmdList(args, cwd) {
     const notEnabled = plugins.filter(p => !p.disabled && !enabled(p));
     if (notEnabled.length) {
       process.stderr.write(`\n${YELLOW}!${RESET} ${notEnabled.length} pack${notEnabled.length === 1 ? '' : 's'} installed but NOT enabled in this session.\n`);
-      process.stderr.write(`  Their plugin agents won't appear in the model's toolset until allowlisted.\n`);
+      process.stderr.write(`  Their plugin agents won't appear in the model's toolset until allowlisted or declared as entry_agent.\n`);
       process.stderr.write(`  Add to ${CYAN}.bahulam/settings.json${RESET}:\n`);
       const slugs = notEnabled.flatMap(p => p.agentSlugs);
       process.stderr.write(`  ${DIM}{ "plugins": { "agent_allowlist": ${JSON.stringify(slugs)} } }${RESET}\n`);

package/src/commands/plugin.mjs

@@ -31,13 +31,10 @@ const YELLOW = '\x1b[33m';
 const RED = '\x1b[31m';
 
 /**
- * Standard directories to search for plugins.
+ * The one and only directory to search for plugins.
  */
-function pluginSearchDirs(cwd = process.cwd()) {
-  return [
-    path.join(cwd, '.bahulam', 'plugins'),
-    path.join(bahulamHome(), 'plugins'),
-  ];
+function pluginSearchDirs() {
+  return [path.join(bahulamHome(), 'plugins')];
 }
 
 /**

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/paths.mjs

@@ -7,6 +7,9 @@
  *     history.jsonl            — prompt history
  *     hooks.json               — global hooks
  *     conversations/           — conversation JSONL files
+ *     plugins/                 — installed plugins (THE plugin root)
+ *     plugins-pi/              — pi ingredients (composed, not run directly)
+ *     data/{plugin}/           — per-plugin state (state.db)
  *     projects/
  *       {hash}/                — per-project data (hash of project path)
  *         index/               — BM25 search index
@@ -57,6 +60,27 @@ export function bahulamHome() {
     return resolveHome();
 }
 
+/**
+ * The one and only plugin root: `~/.bahulam/plugins`.
+ *
+ * Deliberately takes no `cwd`. There used to be a project-scoped second root
+ * (`<cwd>/.bahulam/plugins`), which meant the set of installed plugins
+ * depended on the directory you happened to launch from — the same command
+ * saw different plugins in different terminals. Plugins are global; only
+ * skills keep a project scope.
+ */
+export function pluginInstallDir() {
+    return path.join(bahulamHome(), 'plugins');
+}
+
+/**
+ * Directories the plugin registry scans. Exactly one entry, forever.
+ * @returns {string[]}
+ */
+export function pluginDirs() {
+    return [pluginInstallDir()];
+}
+
 /** ~/.bahulam/projects/{hash}/ for a given project path. */
 export function projectDir(projectPath) {
     return path.join(bahulamHome(), 'projects', projectHash(projectPath));

package/src/core/stream-client.mjs

@@ -203,12 +203,45 @@ export class BahulamStreamClient {
     }
 
     /**
-     * Plugin tools are intentionally not advertised as primary client_tools.
-     * They are executable by the local callback handler, but the primary model
-     * should reach them by delegating to an agent that declares them.
+     * Plugin tool schemas for tools that have NO owning agent.
+     * These are advertised as direct client_tools so the primary model can
+     * call them without going through delegate(). Tools already claimed by
+     * a plugin agent stay in client_agent_tools and are not duplicated.
      */
-    _getPluginToolSchemas() {
-        return [];
+    _getUnclaimedPluginToolSchemas(context = {}, clientAgents = []) {
+        if (!this.pluginRegistry) return [];
+        const pluginTools = this._getPluginToolMap();
+        if (!pluginTools.size) return [];
+
+        // Collect tool names declared by plugin agents that are actually
+        // advertised. Tools owned only by hidden/workspace-scoped helpers still
+        // need to be exposed as direct client_tools.
+        const clientAgentSlugs = new Set(this._getPluginAgentSchemas().map(a => a.slug));
+        const agentToolNames = new Set();
+        for (const agent of (this.pluginRegistry.listAgents?.() || [])) {
+            const slug = agent.slug || agent.name || '';
+            if (!clientAgentSlugs.has(slug)) continue;
+            for (const t of (agent.tools || [])) {
+                if (t) agentToolNames.add(String(t).trim());
+            }
+        }
+        for (const name of this._collectAgentScopedToolRefs(context, clientAgents).keys()) {
+            agentToolNames.add(name);
+        }
+
+        // Return schemas for tools NOT claimed by any agent
+        const schemas = [];
+        for (const [name, tool] of pluginTools) {
+            if (agentToolNames.has(name)) continue; // already in client_agent_tools
+            schemas.push({
+                name,
+                description: tool.description || '',
+                input_schema: tool.input_schema || { type: 'object', properties: {} },
+                source_scope: 'plugin',
+                plugin_name: tool._plugin_name || tool.plugin_name || null,
+            });
+        }
+        return schemas;
     }
 
     _collectAgentScopedToolRefs(context = {}, clientAgents = []) {
@@ -263,11 +296,11 @@ export class BahulamStreamClient {
      */
     _getPluginAgentSchemas() {
         if (!this.pluginRegistry) return [];
-        // Only plugin agents admitted to the main-loop registry (settings
-        // plugins.agent_allowlist, or the session plugin in workspace-channel
-        // executors) are advertised. Workspace-scoped plugin agents stay out
-        // of the main-turn payload; without an executor registry, fall back
-        // to advertising everything (legacy behavior).
+        // Only plugin agents admitted to the runtime registry are advertised:
+        // entry agents, settings plugins.agent_allowlist, or all plugin agents
+        // in workspace-channel executors. Other helpers stay out of the
+        // main-turn payload; without an executor registry, fall back to
+        // advertising everything (legacy behavior).
         const runnables = this.toolExecutor?.listRunnables?.();
         const admitted = Array.isArray(runnables)
             ? new Set(runnables.filter(a => a.source_scope === 'plugin').map(a => a.slug))
@@ -365,10 +398,13 @@ export class BahulamStreamClient {
         const body = { instruction, context };
         if (messages && messages.length > 0) body.messages = messages;
         if (this.sessionId) body.session_id = this.sessionId;
-        const clientTools = this._getPluginToolSchemas();
-        if (clientTools.length > 0) body.client_tools = clientTools;
+        // Plugin tools with no owning agent are advertised as direct client_tools
+        // so the primary model can call them. Agent-scoped tools stay in
+        // client_agent_tools — _getUnclaimedPluginToolSchemas excludes those.
         const clientAgents = this._getPluginAgentSchemas();
         if (clientAgents.length > 0) body.client_agents = clientAgents;
+        const clientTools = this._getUnclaimedPluginToolSchemas(context, clientAgents);
+        if (clientTools.length > 0) body.client_tools = clientTools;
         const clientAgentTools = this._getClientAgentToolSchemas(context, clientAgents);
         if (clientAgentTools.length > 0) body.client_agent_tools = clientAgentTools;
         const requestId = `cli-${_uuidLike()}`;