mixdog 1.2.6 → 1.3.1

package/src/runtime/agent/orchestrator/context/deferred-tools.mjs

@@ -1,5 +1,7 @@
 // Deferred-pool and MCP-instruction manifests injected into BP2.
-import { parseMcpToolName } from '../../../shared/tool-primitives.mjs';
+import { accountOfInstructions } from '../../../shared/connector-accounts.mjs';
+import { connectorTrigger } from '../../../shared/connector-triggers.mjs';
+import { parseMcpToolName, titleCaseMcpServer } from '../../../shared/tool-primitives.mjs';
 import { isToolBridgeEnabled, TOOL_BRIDGE_GUIDANCE } from '../runtime-core/tool-exposure.mjs';
 
 export function compactPromptManifestText(value, max = 250) {
@@ -100,11 +102,8 @@ function sanitizeMcpInstructionText(text, max = MCP_INSTRUCTION_MAX_CHARS) {
 /**
  * Per-server MCP initialize instructions for deferred-pool tools only.
  * Empty when no instructions or no matching deferred MCP tools → omit block.
- * Emits ONLY the server heading + instruction body: the per-server tool names
- * are deliberately NOT repeated here — every pool tool is already listed once
- * (with its description) in <available-deferred-tools>, and re-listing ~30
- * names per server doubled the MCP share of the BP2 prefix (2026-08-05 audit).
- * Server membership stays evident from the mcp__<server>__ name prefix.
+ * Emits ONLY the server heading + instruction body: tool names are never
+ * listed — <available-deferred-tools> names each server once (mcp__<server>).
  */
 function buildMcpInstructionsManifest(mcpServerInstructions, poolNames, catalog = []) {
   const map = mcpServerInstructions && typeof mcpServerInstructions === 'object' ? mcpServerInstructions : {};
@@ -163,18 +162,82 @@ function rebuildDeferredToolManifestBlock(text, manifest) {
   return out;
 }
 
-function deferredManifestEntries(session, pool) {
-  const descByName = new Map();
+function catalogByName(session) {
+  const byName = new Map();
   for (const tool of Array.isArray(session?.deferredToolCatalog) ? session.deferredToolCatalog : []) {
     const name = String(tool?.name || '').trim();
-    // Skill-style selection trigger when the tool declares one; else its description.
-    if (name && !descByName.has(name)) descByName.set(name, String(tool?.trigger || tool?.description || ''));
+    if (name && !byName.has(name)) byName.set(name, tool);
   }
+  return byName;
+}
+
+// MCP tools are listed once per server: load_tool loads every tool of
+// `mcp__<server>`. Tool definitions carry their server (shortened names
+// cannot be parsed).
+const mcpServerOf = (byName, name) => parseMcpToolName(byName.get(String(name).trim()) || name)?.server || '';
+const mcpServerLineName = (server) => `mcp__${server}`;
+const firstSentence = (text) => {
+  const flat = String(text || '')
+    .replace(/\s+/g, ' ')
+    .trim();
+  return (flat.split(/(?<=[.!?])\s/, 1)[0] || flat).replace(/[.!?]+$/, '');
+};
+
+// A catalog connector's curated trigger; else the server's MCP instructions;
+// else its tools' leading descriptions (name order); else its name. Derived
+// lines are compacted to at most 100 characters, ellipsis included.
+function mcpServerTrigger(server, tools, instructions) {
+  // A multi-account connector's server names its account (connector-accounts.mjs).
+  const account = accountOfInstructions(instructions?.[server]);
+  const curated = connectorTrigger(server);
+  if (curated) return account ? `${curated} Account: ${account}` : curated;
+  const instruction = String(instructions?.[server] || '').replace(/[<>]/g, '');
+  const described = [...tools]
+    .sort((a, b) => String(a?.name || '').localeCompare(String(b?.name || '')))
+    .map((tool) => firstSentence(String(tool?.description || '').replace(/[<>]/g, '')))
+    .filter(Boolean)
+    .join('; ');
+  const derived = instruction.trim() ? instruction : described;
+  return derived ? compactPromptManifestText(derived, 98) : `${titleCaseMcpServer(server)} MCP server tools.`;
+}
+
+function deferredManifestEntries(session, pool) {
+  const byName = catalogByName(session);
   const skillRoutedNames = skillRoutedToolNames(session.messages);
-  return pool.map((name) => ({
-    name,
-    description: skillRoutedNames.has(String(name).trim()) ? '' : descByName.get(String(name).trim()) || '',
-  }));
+  const entries = [];
+  const servers = new Map();
+  for (const name of pool) {
+    const key = String(name).trim();
+    const tool = byName.get(key);
+    const server = mcpServerOf(byName, name);
+    if (server) {
+      if (!servers.has(server)) servers.set(server, []);
+      servers.get(server).push(tool || { name: key });
+      continue;
+    }
+    // Skill-style selection trigger when the tool declares one; else its description.
+    entries.push({
+      name,
+      description: skillRoutedNames.has(key) ? '' : String(tool?.trigger || tool?.description || ''),
+    });
+  }
+  for (const [server, tools] of servers) {
+    entries.push({
+      name: mcpServerLineName(server),
+      description: mcpServerTrigger(server, tools, session.mcpServerInstructions),
+    });
+  }
+  return entries;
+}
+
+/** The pool names `rendered` lists: by their own line, or their MCP server's. */
+export function listedDeferredToolNames(session, poolNames, rendered) {
+  const byName = catalogByName(session);
+  const text = String(rendered || '');
+  return (Array.isArray(poolNames) ? poolNames : []).filter((name) => {
+    const server = mcpServerOf(byName, name);
+    return text.includes(server ? `- ${mcpServerLineName(server)}: ` : name);
+  });
 }
 
 function composeDeferredBp2Manifest(session, pool) {

package/src/runtime/agent/orchestrator/context/role-instructions.mjs

@@ -1,12 +1,15 @@
 // Agent-scoped role markdown and 4-BP system prompt composition.
 
+import { createHash } from 'node:crypto';
 import { existsSync, readdirSync } from 'node:fs';
-import { join } from 'node:path';
+import { basename, dirname, join } from 'node:path';
 import { compareCodePoints } from '../../../shared/code-point-order.mjs';
+import { BOTS_DIR, MIXY_BOT_ID, botStoreActive, isStoreBot, mixyIdentityDir } from '../../../shared/agent-store.mjs';
 import { mixdogRoot } from '../../../shared/plugin-paths.mjs';
 import { readMarkdownDocument } from '../../../shared/markdown-frontmatter.mjs';
 import { listHiddenAgentsByKind, getAgentCatalogShareAgents } from '../internal-agents.mjs';
 import { mixdogGlobalDir, mtimeWithTtl, readSafe } from './skill-catalog.mjs';
+import { mixyDisplayName } from '../session/mixy-name.mjs';
 
 // --- Agent-scoped instruction loader ---
 // Emits a BP2 agent/system block scoped to the calling agent:
@@ -45,6 +48,12 @@ const _scopedRoleInstructionsCache = new Map();
 const _scopedRoleInstructionsMtimeCache = new Map();
 const _ROLE_INSTRUCTIONS_MTIME_TTL_MS = 2000;
 
+/** A saved AGENT.md applies to the next composition, even inside the mtime TTL. */
+export function invalidateRoleInstructionsCache() {
+  _scopedRoleInstructionsCache.clear();
+  _scopedRoleInstructionsMtimeCache.clear();
+}
+
 function loadHiddenAgentSnippets(pluginRoot) {
   try {
     const agentRulesDir = join(pluginRoot, 'rules', 'agent');
@@ -81,9 +90,35 @@ function agentSectionDirs(pluginRoot) {
   } catch {
     /* unresolvable data dir — built-in roles still load */
   }
+  // Bots of the store (agent-store.mjs), last: a bot's own folder wins over
+  // the agents/ original the split left behind.
+  const root = userDataRoot();
+  if (root && botStoreActive(root)) dirs.push(join(root, BOTS_DIR));
   return dirs;
 }
 
+// The user data dir (parent of agents/), or '' when it cannot be resolved.
+function userDataRoot() {
+  try {
+    const userDir = mixdogGlobalDir('agents');
+    return userDir ? dirname(userDir) : '';
+  } catch {
+    return '';
+  }
+}
+
+// A store bot's own folder, or ''.
+function storeBotDir(agent) {
+  const root = userDataRoot();
+  return root && isStoreBot(root, agent) ? join(root, BOTS_DIR, agent) : '';
+}
+
+// Mixy's identity folder: bots/mixy with the store, agents/lead before.
+function mixyDir() {
+  const root = userDataRoot();
+  return root ? mixyIdentityDir(root) : '';
+}
+
 function loadAgentSections(pluginRoot) {
   // agents/ accepts both the compatibility flat layout and the current
   // nested agents/<agent>/AGENT.md layout.
@@ -106,7 +141,10 @@ function loadAgentSections(pluginRoot) {
         name = entry.name.replace(/\.md$/, '');
         raw = readSafe(join(agentsDir, entry.name));
       }
-      if (!name || !raw) continue;
+      // Mixy's own AGENT.md (agents/lead/) rides only Mixy's agent-mode
+      // prompt (loadMixyRoleSection), never another role catalog.
+      if (!name || !raw || name === 'lead') continue;
+      if (name === MIXY_BOT_ID && basename(agentsDir) === BOTS_DIR) continue;
       const { body } = readMarkdownDocument(raw);
       if (!body) continue;
       byName.set(name, roleSection(name, body));
@@ -225,6 +263,174 @@ export function loadScopedRoleInstructions(agent, provider = null) {
   }
 }
 
+// --- Agent persona (agents/<id>/PERSONA.md) ---
+// Optional tone/addressing/personality guide, rendered right after the
+// agent's role section. Read from the same directory that supplies the
+// agent's AGENT.md (user data dir first, then shipped); the Lead (`lead`,
+// Mixy) has no AGENT.md, so its persona is the first PERSONA.md found.
+// The text depends only on the file, so the BP3 prefix is stable until the
+// file changes; it is re-read per composition, so an edit applies next turn.
+export const PERSONA_MAX_CHARS = 4000;
+export const PERSONA_TRUNCATION_MARKER = '\n\n[persona truncated]';
+const PERSONA_AGENT_ID = /^[A-Za-z0-9][A-Za-z0-9._-]*$/;
+
+export function truncatePersona(text, max = PERSONA_MAX_CHARS) {
+  const value = typeof text === 'string' ? text.trim() : '';
+  if (value.length <= max) return value;
+  return value.slice(0, max).trimEnd() + PERSONA_TRUNCATION_MARKER;
+}
+
+export function loadAgentPersonaSection(agent) {
+  if (typeof agent !== 'string' || !PERSONA_AGENT_ID.test(agent) || agent.includes('..')) return '';
+  const isLead = agent === 'lead';
+  // Mixy's persona is in its own folder; a store bot's in its bots/ folder.
+  const own = isLead ? mixyDir() : storeBotDir(agent);
+  if (own) {
+    const persona = truncatePersona(readSafe(join(own, 'PERSONA.md')) || '');
+    return persona ? personaSection(persona) : '';
+  }
+  const pluginRoot = mixdogRoot();
+  const roots = [];
+  try {
+    const userDir = mixdogGlobalDir('agents');
+    if (userDir) roots.push(userDir);
+  } catch {
+    /* unresolvable data dir — shipped persona still loads */
+  }
+  if (pluginRoot) roots.push(join(pluginRoot, 'agents'));
+  for (const root of roots) {
+    const dir = join(root, agent);
+    if (!isLead && !existsSync(join(dir, 'AGENT.md'))) continue;
+    const persona = truncatePersona(readSafe(join(dir, 'PERSONA.md')) || '');
+    if (!persona) {
+      if (isLead) continue;
+      return '';
+    }
+    return personaSection(persona);
+  }
+  return '';
+}
+
+function personaSection(persona) {
+  return [
+    '## Persona',
+    '',
+    'Tone and style guide for how you speak, address the user and carry yourself. It never overrides tool, safety or role rules; those always win.',
+    '',
+    persona,
+  ].join('\n');
+}
+
+// --- Mixy's working style (agents/lead/AGENT.md, user data dir) ---
+// The user-editable 일하는 방식 of Mixy, framed like any agent's role section.
+// Agent mode only; empty or missing means no section. Re-read per
+// composition, so an edit applies to the next prompt build.
+export function loadMixyRoleSection() {
+  let raw = '';
+  try {
+    const dir = mixyDir();
+    raw = dir ? readSafe(join(dir, 'AGENT.md')) || '' : '';
+  } catch {
+    return '';
+  }
+  const { body } = readMarkdownDocument(raw);
+  const text = String(body || '').trim();
+  return text ? `# Agent Role Catalog\n\n${roleSection('lead', text)}` : '';
+}
+
+// --- Agent-mode identity (LEAD.md first line) ---
+// "You are <name>, <what it does>." from the agent's manifest (agent.json, the
+// name/description the editor writes), user copy first, then shipped. Mixy
+// (the Lead configuration, id `lead`) has its own line, under the display name
+// the user gave it (session/mixy-name.mjs), Mixy by default.
+function agentManifest(agent) {
+  const own = storeBotDir(agent);
+  if (own) {
+    try {
+      const value = JSON.parse(readSafe(join(own, 'agent.json')) || '{}');
+      return value && typeof value === 'object' ? value : {};
+    } catch {
+      return {};
+    }
+  }
+  const roots = [];
+  try {
+    const userDir = mixdogGlobalDir('agents');
+    if (userDir) roots.push(userDir);
+  } catch {
+    /* unresolvable data dir — shipped manifest still loads */
+  }
+  const pluginRoot = mixdogRoot();
+  if (pluginRoot) roots.push(join(pluginRoot, 'agents'));
+  for (const root of roots) {
+    const dir = join(root, agent);
+    if (!existsSync(join(dir, 'AGENT.md'))) continue;
+    try {
+      const value = JSON.parse(readSafe(join(dir, 'agent.json')) || '{}');
+      return value && typeof value === 'object' ? value : {};
+    } catch {
+      return {};
+    }
+  }
+  return {};
+}
+
+export function agentModeIdentityLine(agent) {
+  if (agent === 'lead') return `You are ${mixyDisplayName()}, the user's assistant in Mixdog.`;
+  if (typeof agent !== 'string' || !PERSONA_AGENT_ID.test(agent) || agent.includes('..')) return '';
+  const oneLine = (value) => (typeof value === 'string' ? value.replace(/\s+/g, ' ').trim() : '');
+  const manifest = agentManifest(agent);
+  const name = oneLine(manifest.name) || agent;
+  const role = oneLine(manifest.description).replace(/[.。]+$/, '');
+  return role ? `You are ${name}. Your role: ${role}.` : `You are ${name}.`;
+}
+
+// --- Agent profile revision ---
+// The files an agent's prompt sections (identity line, role, persona) are
+// read from — its agent.json, AGENT.md and PERSONA.md in the user data dir and
+// the shipped tree — as one hash. A session stamps it when its prompt is
+// composed; another value means the profile was edited since
+// (session-runtime/tool-policy-refresh.mjs refreshAgentProfile). '' for an
+// invalid id. A coding Lead (`lead` outside Mixy's own thread) embeds no
+// profile file at all, so its stamp is a constant: editing Mixy never
+// rebuilds a coding session's prompt.
+export const CODING_LEAD_PROFILE_REVISION = 'coding-lead';
+export function agentProfileRevision(agent, { mixy = true } = {}) {
+  if (typeof agent !== 'string' || !PERSONA_AGENT_ID.test(agent) || agent.includes('..')) return '';
+  if (agent === 'lead' && !mixy) return CODING_LEAD_PROFILE_REVISION;
+  const roots = [mixdogGlobalDir('agents')];
+  const pluginRoot = mixdogRoot();
+  if (pluginRoot) roots.push(join(pluginRoot, 'agents'));
+  const hash = createHash('sha256');
+  for (const root of roots) {
+    for (const file of ['agent.json', 'AGENT.md', 'PERSONA.md']) {
+      hash.update(`${root}\0${file}\0${readSafe(join(root, agent, file)) ?? '\u0001'}\0`);
+    }
+  }
+  // Mixy's or a store bot's own folder, when it has one.
+  const own = agent === 'lead' ? mixyDir() : storeBotDir(agent);
+  if (own && own !== join(roots[0] || '', agent)) {
+    for (const file of ['agent.json', 'AGENT.md', 'PERSONA.md']) {
+      hash.update(`${own}\0${file}\0${readSafe(join(own, file)) ?? '\u0001'}\0`);
+    }
+  }
+  return hash.digest('hex').slice(0, 24);
+}
+
+// --- Lead roster revision ---
+// The bot roster a Lead's prompt lists (workflow/context.mjs leadPromptParts:
+// the agent catalog and Mixy's contact catalog — never the orchestration
+// mode, a setting that applies to new sessions), as one hash, stamped beside
+// agentProfileRevision. A bot created, renamed, archived or restored changes
+// it for every Lead whose prompt lists that bot.
+export function leadRosterRevision(parts) {
+  const hash = createHash('sha256');
+  for (const slice of [parts?.agentCatalogContext, parts?.contactCatalogContext]) {
+    hash.update(`${slice || ''}\0`);
+  }
+  return hash.digest('hex').slice(0, 24);
+}
+
 // --- Compose system prompt — 4-BP cache layout ---
 // Returns the three stable system blocks and the BP3 core used for refreshes.
 // They map directly to the breakpoint plan:
@@ -262,32 +468,53 @@ export function composeSystemPrompt(opts) {
   ]);
 
   // ── BP3: workflow/role + session environment layer ─────────────────
-  const roleInstructionContext = opts.skipRoleCatalog
-    ? ''
-    : loadScopedRoleInstructions(opts.agent || null, opts.provider || null);
-  // Keep the active workflow first within BP3 so it leads the role and
-  // environment material that varies with the session.
+  let roleInstructionContext = '';
+  if (!opts.skipRoleCatalog) {
+    roleInstructionContext =
+      opts.agent === 'lead'
+        ? loadMixyRoleSection()
+        : loadScopedRoleInstructions(opts.agent || null, opts.provider || null);
+  }
+  // Persona follows the role; Mixy's own thread carries Mixy's persona
+  // (bots/mixy/PERSONA.md) — a coding Lead's prompt never does (skipPersona).
+  const personaContext = opts.agent && !opts.skipPersona ? loadAgentPersonaSection(opts.agent) : '';
   const coreMemory = skip.memory ? '' : trimmedPromptSlice(opts.coreMemoryContext);
   // User AGENTS.md / CLAUDE.md block (context/instruction-files.mjs), already
-  // headed `# Instruction Files`; rides right after core memory.
+  // headed `# Instruction Files`; rides right before core memory.
   const instructionFiles = skip.claudemd ? '' : trimmedPromptSlice(opts.instructionFilesContext);
+  // Ordered for the longest shared prefix (session-prompt-composition.mjs):
+  // 1. shared by every Lead — the workflow pack and LEAD.md's common lines;
+  // 2. the mode block — coding: orchestration mode, LEAD.md's two passages,
+  //    the full agent catalog; agent mode: the delegation block, their
+  //    variants, AGENT_MODE.md, the sub-agent catalog (the same for every
+  //    agent other than Mixy);
+  // 3. Mixy only — MIXY.md and its contact-agent catalog;
+  // 4. per session or agent, last — routine line, identity, caller prompt,
+  //    role, persona, instruction files and core memory (changes most).
   const sessionMarkerCore = joinPromptSlices([
     trimmedPromptSlice(opts.workflowContext),
     opts.roleRules || '',
+    trimmedPromptSlice(opts.orchestrationContext),
+    opts.leadModeRules || '',
+    opts.agentModeRules || '',
+    trimmedPromptSlice(opts.agentCatalogContext),
+    opts.mixyRules || '',
+    trimmedPromptSlice(opts.contactCatalogContext),
+    opts.routineRules || '',
+    opts.identityContext || '',
     opts.userPrompt || '',
     roleInstructionContext,
-    coreMemory ? `# Core Memory\n${coreMemory}` : '',
+    personaContext,
     instructionFiles,
+    coreMemory ? `# Core Memory\n${coreMemory}` : '',
   ]);
   // Response language is the LAST system text before the conversation. It
   // rides the environment block (not the tier3 core) because the `# Session`
   // / shell / git lines are English and would otherwise trail it, pulling the
   // pre-tool preamble toward English.
-  const environmentParts = [
-    opts.sessionStartContext,
-    opts.environmentContext,
-    opts.languageContext,
-  ].map(trimmedPromptSlice);
+  const environmentParts = [opts.sessionStartContext, opts.environmentContext, opts.languageContext].map(
+    trimmedPromptSlice
+  );
   // Volatile session/project environment. Kept OUT of sessionMarkerCore so
   // Anthropic providers can leave it as an UNMARKED system block (covered by
   // the messages-tail breakpoint) while prefix-order providers still see it

package/src/runtime/agent/orchestrator/context/skill-catalog.mjs

@@ -174,8 +174,10 @@ export function collectSkills(cwd) {
         } catch {
           continue;
         }
-        // Agent Skills requires the manifest name to match its folder.
-        if (basename(dirname(filePath)) !== skill.name) continue;
+        // Agent Skills requires the manifest name to match its folder. Plugins
+        // are exempt: they ship nested layouts (skills/<plugin>/<topic>/) and
+        // load by their declared name; `seen` still settles collisions.
+        if (source !== 'plugin' && basename(dirname(filePath)) !== skill.name) continue;
         if (seen.has(skill.name)) continue;
         seen.add(skill.name);
         skills.push({

package/src/runtime/agent/orchestrator/mcp/agent-connectors.mjs

@@ -0,0 +1,216 @@
+// Connector policy: which globally installed MCP servers (connectors) an agent
+// or a project may use. Every installed connector is on by default for every
+// agent and project, existing and future ones; a policy only switches some off:
+//   agents/<id>/agent.json   connectors: { off: [serverId…], tools?: { [serverId]: { [tool]: permission } } }
+//   <data>/project-connectors.json   { projects: { [projectRoot]: { off: [serverId…] } } }
+// `tools` keeps per-tool overrides (auto | needs_approval | disabled); a tool
+// without one is auto, except a catalog connector's high-risk tools, which
+// ask (connectorToolDefault). A legacy agent list (an array: only its enabled
+// entries were mounted) is enforced as written until the host converts it
+// (migrateLegacyConnectorPolicy). A policy that cannot be read, or has neither
+// shape, mounts nothing. Enforced at dispatch only: every session lists every
+// connected tool, so the schema and the BP2 manifest stay shared.
+import { readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+import { cwdWithinProjects } from '../../../shared/extension-scopes.mjs';
+import { resolvePluginData } from '../../../shared/plugin-paths.mjs';
+import { userDefinitionDir } from '../../../shared/agent-store.mjs';
+import { isSelfMcpToolName, parseMcpToolName } from '../../../shared/tool-primitives.mjs';
+import { connectorToolDefault } from '../../../shared/connector-catalog.mjs';
+import { serverConnector } from './server-connectors.mjs';
+
+export const CONNECTOR_PERMISSIONS = Object.freeze(['auto', 'needs_approval', 'disabled']);
+export const PROJECT_CONNECTORS_FILE = 'project-connectors.json';
+
+/** What an unreadable or malformed policy means: no connector is on. */
+export const DENY_ALL_CONNECTORS = Object.freeze({
+  allow: Object.freeze([]),
+  off: Object.freeze([]),
+  tools: Object.freeze({}),
+});
+
+const AGENT_DIR_ID = /^[a-z0-9][a-z0-9._-]*$/i;
+const POLICY_KEYS = new Set(['off', 'tools']);
+
+const isPlainObject = (value) => Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+const clean = (value) => (typeof value === 'string' ? value.trim() : '');
+const uniqueIds = (list) => [...new Set((Array.isArray(list) ? list : []).map(clean).filter(Boolean))].sort();
+
+function toolOverrides(value) {
+  const out = {};
+  for (const [server, tools] of Object.entries(isPlainObject(value) ? value : {})) {
+    const own = {};
+    for (const [tool, permission] of Object.entries(isPlainObject(tools) ? tools : {})) {
+      if (clean(tool) && CONNECTOR_PERMISSIONS.includes(permission)) own[clean(tool)] = permission;
+    }
+    if (clean(server) && Object.keys(own).length) out[clean(server)] = own;
+  }
+  return out;
+}
+
+/** A stored `connectors` field → `{ off, tools }`, or `{ allow, off, tools }`
+ *  for a legacy list; null when absent. Throws on any other shape. */
+export function parseConnectorPolicy(value) {
+  if (value == null) return null;
+  if (Array.isArray(value)) {
+    const allow = [];
+    const tools = {};
+    for (const item of value) {
+      const id = clean(item?.id);
+      if (!id) continue;
+      if (item.enabled === true) allow.push(id);
+      const own = toolOverrides({ [id]: item.tools })[id];
+      if (own) tools[id] = { ...tools[id], ...own };
+    }
+    return { allow: uniqueIds(allow), off: [], tools };
+  }
+  if (!isPlainObject(value) || Object.keys(value).some((key) => !POLICY_KEYS.has(key))) {
+    throw new Error('connectors must be { off: [connector id…], tools? }');
+  }
+  if (value.off != null && !Array.isArray(value.off)) throw new Error('connectors.off must be a list');
+  if (value.tools != null && !isPlainObject(value.tools)) throw new Error('connectors.tools must be an object');
+  return { off: uniqueIds(value.off), tools: toolOverrides(value.tools) };
+}
+
+/** The form a deny-list policy is saved in; null when it switches nothing off
+ *  (the same as no policy). A legacy list must be migrated first. */
+export function storedConnectorPolicy(policy) {
+  if (!policy) return null;
+  if (policy.allow) throw new Error('a legacy connector list must be migrated before it is saved');
+  const off = uniqueIds(policy.off);
+  const tools = toolOverrides(policy.tools);
+  if (!off.length && !Object.keys(tools).length) return null;
+  return { off, ...(Object.keys(tools).length ? { tools } : {}) };
+}
+
+/** A legacy list (or an unreadable policy) as the equivalent deny list over
+ *  the installed connectors `installedIds`: each one it did not enable is off.
+ *  A deny-list policy (or none) passes through. */
+export function migrateLegacyConnectorPolicy(policy, installedIds) {
+  if (!policy?.allow) return policy;
+  const allow = new Set(policy.allow);
+  const missing = uniqueIds(installedIds).filter((id) => !allow.has(id));
+  return { off: uniqueIds([...policy.off, ...missing]), tools: toolOverrides(policy.tools) };
+}
+
+/** Whether connector `serverId` is on under `policy` (null: every one is). */
+export function connectorEnabled(policy, serverId) {
+  if (!policy) return true;
+  if (policy.allow && !policy.allow.includes(serverId)) return false;
+  return !policy.off.includes(serverId);
+}
+
+// Policy files are stat-checked on every read (tiny files), so a save from
+// any process applies to the next dispatch without an explicit flush.
+const fileCache = new Map();
+
+function cachedRead(path, read) {
+  let stat;
+  try {
+    stat = statSync(path);
+  } catch (error) {
+    // No file is the "no policy" state; any other fault means it cannot be read.
+    return error?.code === 'ENOENT' || error?.code === 'ENOTDIR' ? null : unreadable(path, error);
+  }
+  const cached = fileCache.get(path);
+  if (cached && cached.mtimeMs === stat.mtimeMs && cached.size === stat.size) return cached.value;
+  const value = read(path);
+  fileCache.set(path, { mtimeMs: stat.mtimeMs, size: stat.size, value });
+  return value;
+}
+
+function readJson(path, parse) {
+  let text;
+  try {
+    text = readFileSync(path, 'utf8');
+  } catch (error) {
+    return error?.code === 'ENOENT' || error?.code === 'ENOTDIR' ? null : unreadable(path, error);
+  }
+  try {
+    return parse(JSON.parse(text));
+  } catch (error) {
+    return unreadable(path, error);
+  }
+}
+
+// A policy that exists but cannot be trusted mounts nothing.
+function unreadable(path, error) {
+  process.stderr.write(`[connectors] ${path} is unreadable (${error?.message || error}); denying all connectors\n`);
+  return DENY_ALL_CONNECTORS;
+}
+
+/** Uncached: the policy in the agent.json at `path` (see parseConnectorPolicy);
+ *  null without a file or field, DENY_ALL_CONNECTORS when it cannot be
+ *  trusted. The agent editor reads the policy through this too. */
+export function readConnectorsFile(path) {
+  return readJson(path, (manifest) => parseConnectorPolicy(manifest?.connectors));
+}
+
+/** The agent's saved policy under `dataDir`, or null when it has none. */
+export function agentConnectors(agentId, dataDir = resolvePluginData()) {
+  const id = clean(agentId);
+  if (!id || !AGENT_DIR_ID.test(id)) return null;
+  return cachedRead(join(userDefinitionDir(dataDir, id), 'agent.json'), readConnectorsFile);
+}
+
+/** Uncached: the project policy file → `[{ root, off }]`, null without one,
+ *  DENY_ALL_CONNECTORS when it cannot be trusted. */
+export function readProjectConnectorsFile(path) {
+  return readJson(path, (raw) => {
+    if (!isPlainObject(raw) || (raw.projects != null && !isPlainObject(raw.projects))) {
+      throw new Error('projects must be an object');
+    }
+    return Object.entries(raw.projects || {}).flatMap(([root, entry]) => {
+      if (!isPlainObject(entry) || (entry.off != null && !Array.isArray(entry.off))) {
+        throw new Error(`project "${root}" must be { off: [connector id…] }`);
+      }
+      const off = uniqueIds(entry.off);
+      return clean(root) && off.length ? [{ root: clean(root), off }] : [];
+    });
+  });
+}
+
+export function projectConnectorPolicies(dataDir = resolvePluginData()) {
+  return cachedRead(join(dataDir, PROJECT_CONNECTORS_FILE), readProjectConnectorsFile);
+}
+
+/** 'auto' | 'needs_approval' | 'disabled' for an MCP tool (definition or name)
+ *  under an agent's policy. Non-MCP tools and Mixdog's own self server are
+ *  not connectors: always 'auto'. */
+export function connectorToolPermission(policy, toolOrName) {
+  const mcp = parseMcpToolName(toolOrName);
+  if (!mcp || isSelfMcpToolName(toolOrName)) return 'auto';
+  if (policy && !connectorEnabled(policy, mcp.server)) return 'disabled';
+  // An explicit per-tool entry decides; otherwise a catalog connector's
+  // high-risk tools ask (connectorToolDefault) and any other tool is auto.
+  return policy?.tools?.[mcp.server]?.[mcp.tool] || connectorToolDefault(serverConnector(mcp.server), mcp.tool);
+}
+
+/** The permission `agentId` has for the MCP tool `toolOrName`. */
+export function agentMcpToolPermission(agentId, toolOrName) {
+  if (!parseMcpToolName(toolOrName)) return 'auto';
+  return connectorToolPermission(agentConnectors(agentId), toolOrName);
+}
+
+/** Where a session runs: its registered Project (a worktree Lead's too), and
+ *  its cwd (a delegated worker inside the project). */
+function sessionProjectPaths(session) {
+  return [session?.desktopSession?.projectPath, session?.workspace?.projectPath, session?.cwd]
+    .map(clean)
+    .filter(Boolean);
+}
+
+/** True when the project `session` runs in switched the tool's connector off
+ *  (or its policy file cannot be read). */
+export function projectMcpToolDisabled(session, toolOrName, dataDir = resolvePluginData()) {
+  const mcp = parseMcpToolName(toolOrName);
+  if (!mcp || isSelfMcpToolName(toolOrName)) return false;
+  const paths = sessionProjectPaths(session);
+  if (!paths.length) return false;
+  const policies = projectConnectorPolicies(dataDir);
+  if (!policies) return false;
+  if (policies === DENY_ALL_CONNECTORS) return true;
+  return policies.some(
+    ({ root, off }) => off.includes(mcp.server) && paths.some((path) => cwdWithinProjects(path, [root]))
+  );
+}