@bahulam/code 0.1.20 → 0.1.22

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bahulam/code",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "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/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/config/model-catalog-default.json

@@ -10,7 +10,7 @@
     {"value": "us.anthropic.claude-opus-4-6-v1", "label": "Claude Opus 4.6 (Bedrock)", "provider": "anthropic", "inputCost": 15, "outputCost": 75, "context": 200000, "maxOutput": 32000, "supportsTools": true, "supportsReasoning": true, "harnessValidated": false},
     {"value": "us.anthropic.claude-sonnet-4-6", "label": "Claude Sonnet 4.6 (Bedrock)", "provider": "anthropic", "inputCost": 3, "outputCost": 15, "context": 200000, "maxOutput": 64000, "supportsTools": true, "supportsReasoning": true, "harnessValidated": false},
     {"value": "us.anthropic.claude-haiku-4-5-20251001-v1:0", "label": "Claude Haiku 4.5 (Bedrock)", "provider": "anthropic", "inputCost": 0.8, "outputCost": 4, "context": 200000, "maxOutput": 8192, "supportsTools": true, "supportsReasoning": false, "harnessValidated": false},
-    {"value": "google/gemini-2.5-pro", "label": "Gemini 2.5 Pro", "provider": "google", "category": "image", "inputCost": 1.25, "outputCost": 10, "context": 1048576, "maxOutput": 65536, "supportsTools": true, "supportsReasoning": true, "harnessValidated": true, "platformAccessTier": ["pro", "tier_49", "tier_99"]},
+    {"value": "google/gemini-2.5-pro", "label": "Gemini 2.5 Pro", "provider": "google", "category": "multimodal", "inputModalities": ["text", "image", "file", "audio", "video"], "outputModalities": ["text"], "inputCost": 1.25, "outputCost": 10, "context": 1048576, "maxOutput": 65536, "supportsTools": true, "supportsReasoning": true, "harnessValidated": true, "platformAccessTier": ["pro", "tier_49", "tier_99"]},
     {"value": "google/gemini-2.5-flash", "label": "Gemini 2.5 Flash", "provider": "google", "inputCost": 0.15, "outputCost": 0.6, "context": 1048576, "maxOutput": 65535, "supportsTools": true, "supportsReasoning": true, "harnessValidated": true, "platformAccessTier": ["pro", "tier_49", "tier_99"]},
     {"value": "google/gemini-2.5-flash-lite", "label": "Gemini 2.5 Flash Lite", "provider": "google", "inputCost": 0.075, "outputCost": 0.3, "context": 1048576, "maxOutput": 65535, "supportsTools": true, "supportsReasoning": false, "harnessValidated": true, "platformAccessTier": ["pro", "tier_49", "tier_99"]},
     {"value": "openai/gpt-4.1", "label": "GPT-4.1", "provider": "openai", "inputCost": 2, "outputCost": 8, "context": 1047576, "maxOutput": 32768, "supportsTools": true, "supportsReasoning": false, "harnessValidated": true, "platformAccessTier": ["pro", "tier_49", "tier_99"]},
@@ -19,7 +19,7 @@
     {"value": "openai/codex-mini", "label": "Codex Mini", "provider": "openai", "inputCost": 1.5, "outputCost": 6, "context": 200000, "maxOutput": 100000, "supportsTools": true, "supportsReasoning": true, "harnessValidated": false},
     {"value": "deepseek/deepseek-v4-flash", "label": "DeepSeek V4 Flash", "provider": "deepseek", "inputCost": 0.098, "outputCost": 0.197, "context": 1048576, "maxOutput": 384000, "supportsTools": true, "supportsReasoning": true, "harnessValidated": true, "platformAccessTier": ["pro", "tier_49", "tier_99"]},
     {"value": "deepseek/deepseek-v4-flash-0731", "label": "DeepSeek V4 Flash (0731)", "provider": "deepseek", "inputCost": 0.098, "outputCost": 0.197, "context": 1310720, "maxOutput": 384000, "supportsTools": true, "supportsReasoning": true, "harnessValidated": true, "cacheProfile": "{\"type\": \"prefix_hash\", \"provider_hint\": \"DeepSeek\"}", "platformAccessTier": ["pro", "tier_49", "tier_99"]},
-    {"value": "deepseek/deepseek-v4-flash-vision-exp", "label": "DeepSeek V4 Flash Vision Exp", "provider": "deepseek", "category": "image", "inputCost": 0.22, "outputCost": 0.66, "context": 1048576, "maxOutput": 384000, "supportsTools": true, "supportsReasoning": true, "harnessValidated": true, "platformAccessTier": ["free", "pro", "tier_49", "tier_99"]},
+    {"value": "deepseek/deepseek-v4-flash-vision-exp", "label": "DeepSeek V4 Flash Vision Exp", "provider": "deepseek", "category": "multimodal", "inputModalities": ["text", "image"], "outputModalities": ["text"], "inputCost": 0.22, "outputCost": 0.66, "context": 1048576, "maxOutput": 384000, "supportsTools": true, "supportsReasoning": true, "harnessValidated": true, "platformAccessTier": ["free", "pro", "tier_49", "tier_99"]},
     {"value": "deepseek/deepseek-v4-pro", "label": "DeepSeek V4 Pro", "provider": "deepseek", "inputCost": 0.435, "outputCost": 0.87, "context": 1048576, "maxOutput": 384000, "supportsTools": true, "supportsReasoning": true, "harnessValidated": true, "cacheProfile": "{\"type\": \"prefix_hash\", \"provider_hint\": \"DeepSeek\"}", "platformAccessTier": ["pro", "tier_49", "tier_99"]},
     {"value": "deepseek/deepseek-chat-v3-0324", "label": "DeepSeek V3", "provider": "deepseek", "inputCost": 0.27, "outputCost": 1.1, "context": 163840, "maxOutput": 163840, "supportsTools": true, "supportsReasoning": false, "harnessValidated": false},
     {"value": "deepseek/deepseek-r1-0528", "label": "DeepSeek R1 0528", "provider": "deepseek", "inputCost": 0.8, "outputCost": 2.4, "context": 163840, "maxOutput": 32768, "supportsTools": true, "supportsReasoning": true, "harnessValidated": false},

package/src/config/model-catalog.mjs

@@ -37,6 +37,8 @@ function normalizeSnapshotRow(row) {
     provider: row.provider || (id.includes('/') ? id.split('/', 1)[0] : 'unknown'),
     label: row.label || id,
     category,
+    input_modalities: row.inputModalities ?? row.input_modalities ?? null,
+    output_modalities: row.outputModalities ?? row.output_modalities ?? null,
     input_cost_usd_per_m: row.inputCost ?? row.input_cost_usd_per_m ?? null,
     output_cost_usd_per_m: row.outputCost ?? row.output_cost_usd_per_m ?? null,
     context_length: row.context ?? row.context_length ?? null,

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()}`;

package/src/core/tool-executor.mjs

@@ -31,6 +31,7 @@ import { backgroundTasks } from './background-tasks.mjs';
 import { normalizeLintOutput, resolveLintCommand } from './lint-resolver.mjs';
 import { PluginRegistry } from '../plugins/registry.mjs';
 import { loadPluginTool } from '../plugins/executor.mjs';
+import { makePluginState } from '../plugins/state.mjs';
 import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
@@ -60,9 +61,9 @@ export function createToolExecutor({
     // no reactive pulse.
     stateEmit = null,
     delegateRunner = null,
-    // Execution channel. 'main' (REPL/headless/CLI): plugin agents are
-    // workspace-scoped and excluded from listings and the agent-context
-    // envelope unless allowlisted in settings plugins.agent_allowlist.
+    // Execution channel. 'main' (REPL/headless/CLI): plugin entry agents and
+    // allowlisted plugin agents are listed in the agent-context envelope.
+    // Other plugin helpers stay workspace-scoped.
     // 'workspace' (plugin workspace sessions via agent-relay): the
     // session plugin's agents are fully available.
     channel = 'main',
@@ -632,20 +633,82 @@ export function createToolExecutor({
         return true;
     }
 
-    // Per-plugin state handles are opened lazily on first tool call and
-    // cached process-wide. `makePluginState` itself dedupes on plugin
-    // name, so this Map only exists to avoid re-attaching stateEmit on
-    // every registered tool.
+    // Per-plugin state handles are opened lazily on first call and cached
+    // process-wide. `makePluginState` itself dedupes on plugin name, so
+    // this Map only exists to avoid re-attaching stateEmit on every
+    // registered tool — and to keep the agent-context summary reading the
+    // same connection a plugin tool writes through.
     const _pluginStateHandles = new Map(); // pluginName -> state proxy
-    async function _pluginStateFor(pluginName) {
+
+    /**
+     * The normalized `config.state` block a plugin declared, or null when
+     * it declared none. Declared tables are created and additively
+     * migrated when the DB opens, so this is also the schema the plugin's
+     * own handlers query via `state.query()`.
+     */
+    function pluginStateDecl(pluginName) {
+        if (!pluginName || typeof pluginRegistry?.list !== 'function') return null;
+        const plugin = pluginRegistry.list().find(p => p.metadata?.name === pluginName);
+        return plugin?.config?.state || null;
+    }
+
+    function _pluginStateFor(pluginName) {
         if (!pluginName) return null;
         if (_pluginStateHandles.has(pluginName)) return _pluginStateHandles.get(pluginName);
-        const { makePluginState } = await import('../plugins/state.mjs');
-        const state = makePluginState(pluginName, { emit: stateEmit });
+        const decl = pluginStateDecl(pluginName);
+        const state = makePluginState(pluginName, {
+            emit: stateEmit,
+            tables: decl?.tables || [],
+        });
         _pluginStateHandles.set(pluginName, state);
         return state;
     }
 
+    // ── Declared plugin state → agent context ────────────────────
+    // Tier 1 of the state-visibility contract. Plugins that declare
+    // `config.state.context_always` get exactly those keys and streams
+    // injected into the agent context each turn, so a fresh session opens
+    // already knowing what the previous one left behind — instead of
+    // spending a tool call to rediscover it, or silently redoing work.
+    //
+    // Opt-in by construction: a plugin that declares nothing contributes
+    // nothing, and an opted-in plugin that has recorded nothing yet is
+    // skipped rather than shipping an empty block.
+    //
+    // Reads are keyed on the state DB's size+mtime so the payload stays
+    // byte-identical between turns when nothing wrote. Same reasoning as
+    // the memory digest above: a context block that churns on every turn
+    // invalidates the backend's prompt cache on every ExecuteRequest.
+    const _pluginStateCache = new Map(); // pluginName -> { key, entry }
+
+    function pluginStateContext() {
+        if (typeof pluginRegistry?.list !== 'function') return [];
+        const out = [];
+        for (const plugin of pluginRegistry.list()) {
+            const name = plugin.metadata?.name;
+            const decl = plugin.config?.state;
+            if (!name || !decl?.context_always?.length) continue;
+            try {
+                const state = _pluginStateFor(name);
+                const stat = fs.existsSync(state.path) ? fs.statSync(state.path) : null;
+                const key = stat ? `${stat.size}:${Math.round(stat.mtimeMs)}` : 'missing';
+                const cached = _pluginStateCache.get(name);
+                if (cached && cached.key === key) {
+                    out.push(cached.entry);
+                    continue;
+                }
+                const summary = state.summary(decl.context_always);
+                const hasContent = Object.keys(summary.kv).length > 0
+                    || Object.values(summary.streams).some(rows => rows.length > 0);
+                if (!hasContent) continue;
+                const entry = { plugin: name, ...summary };
+                _pluginStateCache.set(name, { key, entry });
+                out.push(entry);
+            } catch { /* one broken plugin must never break the session */ }
+        }
+        return out;
+    }
+
     /**
      * Register one MCP tool under `<serverName>.<toolName>` (namespaced
      * to prevent collisions between plugins that ship servers with the
@@ -706,6 +769,56 @@ export function createToolExecutor({
             const name = String(toolDef.name || '').trim();
             if (!name || toolMap[name]) continue;
             const pluginName = toolDef._plugin_name || toolDef.plugin_name || null;
+            if (toolDef._state_tool) {
+                // Manifest-declared state query tool (config.state.context_tools).
+                // There is no module to import — the author declared a table
+                // and an optional WHERE clause; the CLI supplies the handler.
+                // `readTable` refuses undeclared tables, so author-supplied
+                // SQL can't be steered into arbitrary table access.
+                const spec = toolDef._state_tool;
+                registerPluginTool(name, async (args) => {
+                    try {
+                        const state = _pluginStateFor(spec.plugin || pluginName);
+                        if (!state) {
+                            return {
+                                success: false,
+                                output: `Plugin state unavailable for '${name}'.`,
+                                _tool: name,
+                                _plugin: pluginName,
+                            };
+                        }
+                        const bound = (spec.params || []).map(key => args?.[key] ?? null);
+                        // An unfiltered call should list everything, not match
+                        // nothing — `topic = NULL` is never true in SQL. Apply
+                        // the WHERE only once a declared param was supplied.
+                        const useWhere = Boolean(spec.where) && bound.some(v => v !== null);
+                        const rows = state.readTable(spec.table, {
+                            where: useWhere ? spec.where : '',
+                            params: useWhere ? bound : [],
+                            limit: args?.limit ?? spec.limit,
+                        });
+                        return {
+                            success: true,
+                            output: rows.length
+                                ? JSON.stringify(rows, null, 2)
+                                : `No rows in ${spec.table}${useWhere ? ' matching those filters' : ''}.`,
+                            rows,
+                            count: rows.length,
+                            _tool: name,
+                            _plugin: pluginName,
+                            _state_tool: true,
+                        };
+                    } catch (err) {
+                        return {
+                            success: false,
+                            output: `Plugin state tool error (${name}): ${err.message}`,
+                            _tool: name,
+                            _plugin: pluginName,
+                        };
+                    }
+                }, { pluginName, source: 'state', stateTool: spec });
+                continue;
+            }
             if (toolDef._composed?.kind === 'pi') {
                 // Composed pi tools resolve at invocation time: look up the
                 // installed pi package's directory, load the specific handler
@@ -2281,7 +2394,7 @@ export function createToolExecutor({
             const agents = filterLocalAgents(args).map(compactAgentMetadata);
             const payload = { agents, count: agents.length };
             if (agents.some(agent => agent.runnable === false)) {
-                payload.note = 'Agents with runnable:false are workspace-scoped plugin agents; add their slug to settings plugins.agent_allowlist to invoke them from the main loop.';
+                payload.note = 'Agents with runnable:false are workspace-scoped plugin helpers; declare an entry_agent or add their slug to settings plugins.agent_allowlist to invoke them from the main loop.';
             }
             return {
                 success: true,
@@ -2777,6 +2890,7 @@ export function createToolExecutor({
         getAgentContext() {
             const global = projectRegistry.getGlobalContext();
             const mem = _readMemorySnapshot();
+            const pluginState = pluginStateContext();
             return {
                 identity: global.identity,
                 preferences: global.preferences,
@@ -2804,6 +2918,14 @@ export function createToolExecutor({
                     spec: agent.spec,
                 })),
                 sub_agent_observability: agentRegistry.observability(),
+                // Cross-session plugin state. Only plugins that opted in via
+                // config.state.context_always appear here, and only the keys
+                // and streams they named — this is how a plugin's local app
+                // state survives a session boundary without the agent having
+                // to know to go looking for it.
+                ...(pluginState.length ? {
+                    plugin_state: pluginState,
+                } : {}),
                 // Background jobs the model should know about. Stable fields
                 // only (no durations) so the entry — and the prompt cache —
                 // changes on status transitions, not every turn.

package/src/local-service/server.mjs

@@ -640,10 +640,7 @@ function scanPlugins(session) {
   const dirs = new Map();
   try {
     const registry = new PluginRegistry({
-      pluginDirs: [
-        path.join(session.root_path || process.cwd(), '.bahulam', 'plugins'),
-        path.join(os.homedir(), '.bahulam', 'plugins'),
-      ],
+      pluginDirs: [path.join(os.homedir(), '.bahulam', 'plugins')],
     }).scan();
     for (const manifest of registry.list()) {
       const pluginName = manifest.metadata?.name || '';