@chrisromp/copilot-bridge 0.10.0 → 0.12.0

package/dist/core/session-manager.js

@@ -2,7 +2,7 @@ import * as fs from 'node:fs';
 import * as os from 'node:os';
 import * as path from 'node:path';
 import { getChannelSession, setChannelSession, clearChannelSession, getChannelPrefs, setChannelPrefs, checkPermission, addPermissionRule, getWorkspaceOverride, setWorkspaceOverride, listWorkspaceOverrides, recordAgentCall, } from '../state/store.js';
-import { getChannelConfig, getChannelBotName, evaluateConfigPermissions, isBotAdmin, getConfig, getInterAgentConfig, isHardDeny } from '../config.js';
+import { getChannelConfig, getChannelBotName, evaluateConfigPermissions, isBotAdmin, getConfig, getInterAgentConfig, isHardDeny, resolveProviderConfig } from '../config.js';
 import { getWorkspacePath, getWorkspaceAllowPaths, ensureWorkspacesDir } from './workspace-manager.js';
 import { onboardProject } from './onboarding.js';
 import { addJob, removeJob, pauseJob, resumeJob, listJobs, formatInTimezone } from './scheduler.js';
@@ -13,7 +13,7 @@ import { loadHooks, getHooksInfo } from './hooks-loader.js';
 import { getBridgeDocs } from './bridge-docs.js';
 const log = createLogger('session');
 /** Custom tools auto-approved without interactive prompt (read-only or enforce workspace boundaries internally). */
-export const BRIDGE_CUSTOM_TOOLS = ['send_file', 'show_file_in_chat', 'ask_agent', 'schedule', 'fetch_copilot_bridge_documentation'];
+export const BRIDGE_CUSTOM_TOOLS = ['send_file', 'show_file_in_chat', 'ask_agent', 'schedule', 'fetch_copilot_bridge_documentation', 'no_reply'];
 /** Simple mutex for serializing env-sensitive session creation. */
 let envLock = Promise.resolve();
 /**
@@ -90,6 +90,11 @@ async function withWorkspaceEnv(workingDirectory, fn) {
         release();
     }
 }
+/** Detect "Session not found" errors from the SDK backend. */
+export function isSessionNotFoundError(err) {
+    const msg = String(err?.message ?? err).toLowerCase();
+    return msg.includes('session not found') || msg.includes('session_not_found');
+}
 /**
  * Load MCP server configs from ~/.copilot/mcp-config.json and installed plugins.
  * Merges them into a single Record, with user config taking precedence over plugins.
@@ -555,7 +560,7 @@ export class SessionManager {
         if (!sessionId)
             return [];
         try {
-            return await this.bridge.listTools();
+            return await this.withSessionRetry(channelId, () => this.bridge.listTools(), false);
         }
         catch (err) {
             log.warn(`Failed to list tools for channel ${channelId}:`, err);
@@ -772,11 +777,12 @@ export class SessionManager {
                 const configFallbacks = configChannel.fallbackModels ?? getConfig().defaults.fallbackModels;
                 let availableModels = [];
                 try {
-                    const models = await this.bridge.listModels();
+                    const models = await this.bridge.listModels(getConfig().providers);
                     availableModels = models.map(m => m.id);
                 }
                 catch { /* best-effort */ }
-                const chain = buildFallbackChain(prefs.model, availableModels, configFallbacks);
+                const byokPrefixes = Object.keys(getConfig().providers ?? {});
+                const chain = buildFallbackChain(prefs.model, availableModels, configFallbacks, byokPrefixes);
                 // Try each fallback: create session + send
                 let lastError = err;
                 for (const fallbackModel of chain) {
@@ -870,51 +876,218 @@ export class SessionManager {
             this.pendingUserInput.delete(channelId);
         }
     }
+    /**
+     * Wrap an RPC call with session re-attach recovery.
+     * If the call fails with "Session not found", re-attaches the session and retries.
+     * If re-attach also fails, creates a new session and retries once more
+     * (unless createOnFail is false, in which case the error propagates).
+     */
+    async withSessionRetry(channelId, fn, createOnFail = true) {
+        const { sessionId } = await this.ensureSession(channelId);
+        try {
+            return await fn(sessionId);
+        }
+        catch (err) {
+            if (!isSessionNotFoundError(err))
+                throw err;
+            log.info(`Session ${sessionId} not found on RPC — attempting re-attach...`);
+            try {
+                const unsub = this.sessionUnsubscribes.get(sessionId);
+                if (unsub) {
+                    unsub();
+                    this.sessionUnsubscribes.delete(sessionId);
+                }
+                try {
+                    await this.bridge.destroySession(sessionId);
+                }
+                catch { /* best-effort */ }
+                await this.attachSession(channelId, sessionId);
+            }
+            catch (attachErr) {
+                log.warn(`Re-attach failed for ${sessionId}:`, attachErr?.message ?? attachErr);
+                if (!createOnFail) {
+                    // Clear stale session so ensureSession() creates fresh on next call
+                    this.channelSessions.delete(channelId);
+                    this.sessionChannels.delete(sessionId);
+                    clearChannelSession(channelId);
+                    throw err;
+                }
+                // Last resort: new session
+                log.info(`Creating new session for channel ${channelId} after RPC failure...`);
+                const newSessionId = await this.newSession(channelId);
+                return await fn(newSessionId);
+            }
+            // Re-attach succeeded — retry fn; let non-session errors propagate
+            return await fn(sessionId);
+        }
+    }
+    /**
+     * Reload MCP servers on the active session via RPC (no full session restart).
+     * Tells the SDK to re-read its MCP config (e.g., workspace mcp-config.json changes).
+     * Falls back to full reloadSession() if no active session exists yet or if the
+     * session is stale (backend no longer recognizes it).
+     */
+    async reloadMcp(channelId) {
+        const sessionId = this.channelSessions.get(channelId) ?? getChannelSession(channelId);
+        const session = sessionId ? this.bridge.getSession(sessionId) : undefined;
+        if (!session) {
+            log.info(`No active session for ${channelId.slice(0, 8)}... — falling back to full reload`);
+            await this.reloadSession(channelId);
+            return;
+        }
+        this.mcpServers = loadMcpServers();
+        try {
+            await session.rpc.mcp.reload();
+        }
+        catch (err) {
+            if (isSessionNotFoundError(err)) {
+                log.info(`Session stale during MCP reload for ${channelId.slice(0, 8)}... — falling back to full reload`);
+                await this.reloadSession(channelId);
+                return;
+            }
+            throw err;
+        }
+        log.info(`MCP servers reloaded via RPC for channel ${channelId.slice(0, 8)}...`);
+    }
+    /**
+     * Reload skills on the active session via RPC (no full session restart).
+     * Tells the SDK to re-read skill directories already configured on the session.
+     * Falls back to full reloadSession() if no active session exists yet or if the
+     * session is stale.
+     */
+    async reloadSkills(channelId) {
+        const sessionId = this.channelSessions.get(channelId) ?? getChannelSession(channelId);
+        const session = sessionId ? this.bridge.getSession(sessionId) : undefined;
+        if (!session) {
+            log.info(`No active session for ${channelId.slice(0, 8)}... — falling back to full reload`);
+            await this.reloadSession(channelId);
+            return;
+        }
+        try {
+            await session.rpc.skills.reload();
+        }
+        catch (err) {
+            if (isSessionNotFoundError(err)) {
+                log.info(`Session stale during skills reload for ${channelId.slice(0, 8)}... — falling back to full reload`);
+                await this.reloadSession(channelId);
+                return;
+            }
+            throw err;
+        }
+        log.info(`Skills reloaded via RPC for channel ${channelId.slice(0, 8)}...`);
+    }
+    /**
+     * Enable or disable a skill on the active session via RPC (instant, no reload needed).
+     * Silently no-ops if no active session (pref is already persisted).
+     */
+    async toggleSkillRpc(channelId, skillName, action) {
+        const sessionId = this.channelSessions.get(channelId) ?? getChannelSession(channelId);
+        const session = sessionId ? this.bridge.getSession(sessionId) : undefined;
+        if (!session)
+            return; // Pref already persisted; will apply on next session create
+        if (action === 'enable') {
+            await session.rpc.skills.enable({ name: skillName });
+        }
+        else {
+            await session.rpc.skills.disable({ name: skillName });
+        }
+        log.info(`Skill "${skillName}" ${action}d via RPC for channel ${channelId.slice(0, 8)}...`);
+    }
     /** Switch the model for a channel's session. */
-    async switchModel(channelId, model) {
-        const sessionId = this.channelSessions.get(channelId);
-        if (sessionId) {
+    async switchModel(channelId, model, provider) {
+        const currentPrefs = this.getEffectivePrefs(channelId);
+        const currentProvider = currentPrefs.provider ?? null;
+        const newProvider = provider ?? null;
+        const providerChanged = currentProvider !== newProvider;
+        if (providerChanged) {
+            // Provider change requires a fresh session (different endpoint/auth)
+            log.info(`Provider switch ${currentProvider ?? 'copilot'} → ${newProvider ?? 'copilot'} for channel ${channelId.slice(0, 8)}...`);
+            // Set prefs before newSession so createNewSession picks up the new provider,
+            // but restore on failure so the channel isn't left in a broken state.
+            const prevModel = currentPrefs.model;
+            setChannelPrefs(channelId, { model, provider: newProvider });
+            try {
+                await this.newSession(channelId);
+            }
+            catch (err) {
+                log.warn(`Provider switch failed, reverting prefs:`, err);
+                setChannelPrefs(channelId, { model: prevModel, provider: currentProvider });
+                throw err;
+            }
+        }
+        else if (newProvider && this.wireApiChanged(newProvider, currentPrefs.model ?? '', model)) {
+            // Same provider but wireApi differs between models — need fresh session
+            log.info(`wireApi change for provider ${newProvider}, model ${currentPrefs.model} → ${model} — creating new session`);
+            const prevModel = currentPrefs.model;
+            setChannelPrefs(channelId, { model, provider: newProvider });
             try {
-                await this.bridge.switchSessionModel(sessionId, model);
+                await this.newSession(channelId);
             }
             catch (err) {
-                log.warn(`RPC model switch failed:`, err);
+                log.warn(`wireApi switch failed, reverting prefs:`, err);
+                setChannelPrefs(channelId, { model: prevModel, provider: currentProvider });
+                throw err;
             }
         }
-        setChannelPrefs(channelId, { model });
+        else {
+            // Same provider — use RPC model switch (with session retry)
+            await this.withSessionRetry(channelId, (sid) => this.bridge.switchSessionModel(sid, model));
+            setChannelPrefs(channelId, { model, provider: newProvider });
+        }
         // Clear stale context window tokens so /context falls back to tokenLimit during transition
         this.contextWindowTokens.delete(channelId);
         // Update cached context window tokens for the new model (best-effort)
-        this.bridge.listModels().then(models => {
+        this.bridge.listModels(getConfig().providers).then(models => {
             // Guard against rapid switches: only cache if the channel is still on this model
-            const currentPrefs = this.getEffectivePrefs(channelId);
-            if (currentPrefs.model === model) {
+            const prefs = this.getEffectivePrefs(channelId);
+            if (prefs.model === model) {
                 this.cacheContextWindowTokens(channelId, model, models);
             }
         }).catch(() => { });
     }
+    /** Check if two models on the same provider have different wireApi settings. */
+    wireApiChanged(providerName, oldModel, newModel) {
+        const providers = getConfig().providers;
+        if (!providers)
+            return false;
+        const entry = providers[providerName];
+        if (!entry)
+            return false;
+        const oldEntry = entry.models.find(m => m.id === oldModel);
+        const newEntry = entry.models.find(m => m.id === newModel);
+        const oldWire = oldEntry?.wireApi ?? entry.wireApi;
+        const newWire = newEntry?.wireApi ?? entry.wireApi;
+        return oldWire !== newWire;
+    }
     /** Switch the agent for a channel's session. */
     async switchAgent(channelId, agent) {
-        const { sessionId } = await this.ensureSession(channelId);
-        try {
+        await this.withSessionRetry(channelId, async (sid) => {
             if (agent) {
-                await this.bridge.selectAgent(sessionId, agent);
+                await this.bridge.selectAgent(sid, agent);
             }
             else {
-                await this.bridge.deselectAgent(sessionId);
+                await this.bridge.deselectAgent(sid);
             }
-        }
-        catch (err) {
-            log.warn(`RPC agent switch failed:`, err);
-        }
+        });
         setChannelPrefs(channelId, { agent });
     }
+    /**
+     * Set reasoning effort on the active session via setModel() RPC.
+     * Uses the current model so only the reasoning effort changes — no full session reload needed.
+     */
+    async setReasoningEffort(channelId, effort) {
+        const prefs = this.getEffectivePrefs(channelId);
+        const model = prefs.model;
+        await this.withSessionRetry(channelId, (sid) => this.bridge.switchSessionModel(sid, model, { reasoningEffort: effort }));
+        setChannelPrefs(channelId, { reasoningEffort: effort });
+    }
     /** Get effective preferences for a channel (config merged with runtime overrides). */
     getEffectivePrefs(channelId) {
         const configChannel = getChannelConfig(channelId);
         const storedPrefs = getChannelPrefs(channelId);
         return {
             model: storedPrefs?.model ?? configChannel.model ?? 'claude-sonnet-4.6',
+            provider: storedPrefs?.provider ?? null,
             agent: storedPrefs?.agent !== undefined ? storedPrefs.agent : configChannel.agent,
             verbose: storedPrefs?.verbose ?? configChannel.verbose,
             triggerMode: configChannel.triggerMode,
@@ -927,7 +1100,7 @@ export class SessionManager {
     /** Get model info (for checking capabilities like reasoning effort). */
     async getModelInfo(modelId) {
         try {
-            const models = await this.bridge.listModels();
+            const models = await this.bridge.listModels(getConfig().providers);
             return models.find(m => m.id === modelId) ?? null;
         }
         catch {
@@ -936,14 +1109,14 @@ export class SessionManager {
     }
     /** List all available models. */
     async listModels() {
-        return this.bridge.listModels();
+        return this.bridge.listModels(getConfig().providers);
     }
     /** Get the current session mode (interactive, plan, autopilot). Falls back to persisted prefs after restart. */
     async getSessionMode(channelId) {
         const sessionId = this.channelSessions.get(channelId);
         if (sessionId) {
             try {
-                const result = await this.bridge.getSessionMode(sessionId);
+                const result = await this.withSessionRetry(channelId, (sid) => this.bridge.getSessionMode(sid), false);
                 return result.mode;
             }
             catch { /* fall through to prefs */ }
@@ -953,8 +1126,7 @@ export class SessionManager {
     }
     /** Set the session mode (interactive, plan, autopilot). Persists to channel prefs. Does not change yolo/permission state. */
     async setSessionMode(channelId, mode) {
-        const { sessionId } = await this.ensureSession(channelId);
-        const result = await this.bridge.setSessionMode(sessionId, mode);
+        const result = await this.withSessionRetry(channelId, (sid) => this.bridge.setSessionMode(sid, mode));
         setChannelPrefs(channelId, { sessionMode: result.mode });
         return result.mode;
     }
@@ -964,7 +1136,7 @@ export class SessionManager {
         if (!sessionId)
             return { exists: false, content: null };
         try {
-            const result = await this.bridge.readPlan(sessionId);
+            const result = await this.withSessionRetry(channelId, (sid) => this.bridge.readPlan(sid), false);
             return { exists: result.exists, content: result.content };
         }
         catch {
@@ -977,7 +1149,7 @@ export class SessionManager {
         if (!sessionId)
             return false;
         try {
-            await this.bridge.deletePlan(sessionId);
+            await this.withSessionRetry(channelId, (sid) => this.bridge.deletePlan(sid), false);
             return true;
         }
         catch {
@@ -1017,7 +1189,7 @@ export class SessionManager {
         // Pick the best available cheap model
         let availableIds = [];
         try {
-            const models = await this.bridge.listModels();
+            const models = await this.bridge.listModels(getConfig().providers);
             availableIds = models.map(m => m.id);
         }
         catch { /* best-effort */ }
@@ -1237,7 +1409,14 @@ export class SessionManager {
     }
     /** Cache the model's max_context_window_tokens for accurate /context display. */
     cacheContextWindowTokens(channelId, modelId, modelList) {
-        const model = modelList.find((m) => m.id === modelId);
+        let model = modelList.find((m) => m.id === modelId);
+        // For BYOK models, the merged list has provider-prefixed IDs (e.g., "ollama-local:qwen3:8b")
+        if (!model) {
+            const prefs = getChannelPrefs(channelId);
+            if (prefs?.provider) {
+                model = modelList.find((m) => m.id === `${prefs.provider}:${modelId}`);
+            }
+        }
         const ctxTokens = model?.capabilities?.limits?.max_context_window_tokens;
         if (typeof ctxTokens === 'number' && ctxTokens > 0) {
             this.contextWindowTokens.set(channelId, ctxTokens);
@@ -1279,6 +1458,38 @@ export class SessionManager {
             return config.workingDirectory;
         return getWorkspacePath(botName);
     }
+    /** Build the system message config for session create/resume.
+     *  Appends bridge-specific instructions to the SDK's custom_instructions section
+     *  so agents get channel communication context without polluting AGENTS.md. */
+    buildSystemMessage() {
+        const content = [
+            '<bridge_instructions>',
+            'You are communicating through copilot-bridge, a messaging bridge to a chat platform (e.g., Mattermost, Slack).',
+            '',
+            '## Channel Communication',
+            '- Your responses are streamed back to the chat channel in real time',
+            '- Slash commands (e.g., /new, /model, /verbose, /plan) are intercepted by the bridge — you will never see them',
+            '- The user may be on mobile — keep responses concise when possible',
+            '',
+            '## Environment Secrets',
+            '- A `.env` file in your workspace is loaded into your shell environment at session start',
+            '- **Never read, cat, or display `.env` contents** — secret values must stay out of chat',
+            '- Reference secrets by variable name only (e.g., `$APP_TOKEN`)',
+            '- To check if a key exists: `grep -q \'^KEY=\' .env 2>/dev/null`',
+            '- Never use cat, grep -v, sed, or any command that would output .env values',
+            '',
+            '## No-Reply Convention',
+            '- When you have nothing meaningful to add to a conversation, call the `no_reply` tool instead of sending text',
+            '- This is preferred over typing "NO_REPLY" or similar text responses',
+            '</bridge_instructions>',
+        ].join('\n');
+        return {
+            mode: 'customize',
+            sections: {
+                custom_instructions: { action: 'append', content },
+            },
+        };
+    }
     async createNewSession(channelId) {
         const prefs = this.getEffectivePrefs(channelId);
         const workingDirectory = this.resolveWorkingDirectory(channelId);
@@ -1290,11 +1501,19 @@ export class SessionManager {
         // Resolve fallback configuration
         const configChannel = getChannelConfig(channelId);
         const configFallbacks = configChannel.fallbackModels ?? getConfig().defaults.fallbackModels;
+        // Resolve BYOK provider if set in prefs
+        const providerName = prefs.provider ?? null;
+        const sdkProvider = providerName
+            ? resolveProviderConfig(providerName, getConfig().providers, prefs.model ?? undefined)
+            : undefined;
+        if (providerName && !sdkProvider) {
+            log.warn(`Provider "${providerName}" set for channel ${channelId} but not found in config — using Copilot`);
+        }
         // Fetch available models for fallback chain (best-effort — don't block on failure)
         let availableModels = [];
         let modelList = [];
         try {
-            modelList = await this.bridge.listModels();
+            modelList = await this.bridge.listModels(getConfig().providers);
             availableModels = modelList.map(m => m.id);
         }
         catch {
@@ -1309,9 +1528,11 @@ export class SessionManager {
         const createWithModel = async (model) => {
             return withWorkspaceEnv(workingDirectory, () => this.bridge.createSession({
                 model,
+                provider: sdkProvider || undefined,
                 workingDirectory,
                 configDir: defaultConfigDir,
                 reasoningEffort: reasoningEffort ?? undefined,
+                agent: prefs.agent ?? undefined,
                 mcpServers: resolvedMcpServers,
                 skillDirectories: skillDirectories.length > 0 ? skillDirectories : undefined,
                 disabledSkills,
@@ -1320,9 +1541,37 @@ export class SessionManager {
                 tools: customTools.length > 0 ? customTools : undefined,
                 hooks,
                 infiniteSessions: getConfig().infiniteSessions,
+                systemMessage: this.buildSystemMessage(),
             }));
         };
-        const { result: session, usedModel, didFallback } = await tryWithFallback(prefs.model, availableModels, configFallbacks, createWithModel);
+        const byokPrefixes = Object.keys(getConfig().providers ?? {});
+        let session;
+        let usedModel;
+        let didFallback;
+        try {
+            const result = await tryWithFallback(prefs.model, availableModels, configFallbacks, createWithModel, byokPrefixes);
+            session = result.result;
+            usedModel = result.usedModel;
+            didFallback = result.didFallback;
+        }
+        catch (err) {
+            // Enhance error message with BYOK context (only when provider actually resolved)
+            if (providerName && sdkProvider) {
+                const msg = String(err?.message ?? err);
+                const provConfig = getConfig().providers?.[providerName];
+                if (msg.includes('ECONNREFUSED') || msg.includes('ENOTFOUND') || msg.includes('fetch failed')) {
+                    throw new Error(`Provider "${providerName}" is unreachable at ${provConfig?.baseUrl ?? 'unknown URL'}. Check that the service is running.`);
+                }
+                if (msg.includes('401') || msg.includes('403') || msg.includes('Unauthorized') || msg.includes('Forbidden')) {
+                    throw new Error(`Provider "${providerName}" rejected authentication. Check your API key configuration.`);
+                }
+                if (msg.includes('404') || msg.includes('model not found') || msg.includes('does not exist')) {
+                    throw new Error(`Model "${prefs.model}" not found on provider "${providerName}". Check the model ID in your config.`);
+                }
+                throw new Error(`Provider "${providerName}" error: ${msg}`);
+            }
+            throw err;
+        }
         this.sessionMcpServers.set(channelId, new Set(Object.keys(resolvedMcpServers)));
         this.sessionSkillDirs.set(channelId, new Set(skillDirectories));
         this.cacheContextWindowTokens(channelId, usedModel, modelList);
@@ -1359,18 +1608,29 @@ export class SessionManager {
         if (hooks) {
             log.debug(`Hooks resolved for session resume: ${Object.keys(hooks).join(', ')}`);
         }
+        // Resolve BYOK provider for resume
+        const providerName = prefs.provider ?? null;
+        let sdkProvider = providerName
+            ? resolveProviderConfig(providerName, getConfig().providers, prefs.model ?? undefined)
+            : undefined;
+        if (providerName && !sdkProvider) {
+            log.warn(`Provider "${providerName}" set for channel ${channelId} but not found in config — using Copilot`);
+        }
         const session = await withWorkspaceEnv(workingDirectory, () => this.bridge.resumeSession(sessionId, {
             onPermissionRequest: (request, invocation) => this.handlePermissionRequest(channelId, request, invocation),
             onUserInputRequest: (request, invocation) => this.handleUserInputRequest(channelId, request, invocation),
             configDir: defaultConfigDir,
             workingDirectory,
+            provider: sdkProvider || undefined,
             reasoningEffort: reasoningEffort ?? undefined,
+            agent: prefs.agent ?? undefined,
             mcpServers,
             skillDirectories: skillDirectories.length > 0 ? skillDirectories : undefined,
             disabledSkills,
             tools: customTools.length > 0 ? customTools : undefined,
             hooks,
             infiniteSessions: getConfig().infiniteSessions,
+            systemMessage: this.buildSystemMessage(),
         }));
         this.sessionMcpServers.set(channelId, new Set(Object.keys(mcpServers)));
         this.sessionSkillDirs.set(channelId, new Set(skillDirectories));
@@ -1379,7 +1639,7 @@ export class SessionManager {
         this.attachSessionEvents(session, channelId);
         // Cache context window tokens for /context display (best-effort, non-blocking)
         const resumeModel = prefs.model;
-        this.bridge.listModels().then(models => {
+        this.bridge.listModels(getConfig().providers).then(models => {
             // Guard against model changes before this resolves
             const currentPrefs = this.getEffectivePrefs(channelId);
             if (currentPrefs.model === resumeModel) {
@@ -2024,6 +2284,26 @@ export class SessionManager {
         tools.push(this.buildScheduleToolDef(channelId));
         // Bridge documentation tool
         tools.push(this.buildBridgeDocsTool(channelId));
+        // No-reply tool: agent calls this instead of emitting "NO_REPLY" text
+        tools.push({
+            name: 'no_reply',
+            description: 'Signal that no response is needed for the current message. Call this instead of sending text when you have nothing meaningful to add to the conversation.',
+            parameters: { type: 'object', properties: {} },
+            skipPermission: true,
+            handler: async () => {
+                log.info(`no_reply tool called for channel ${channelId.slice(0, 8)}...`);
+                return { content: 'Acknowledged. No response sent.' };
+            },
+        });
+        // Mark safe bridge tools as skip-permission (they enforce their own boundaries).
+        // Admin-only tools (create_project, grant_path_access, revoke_path_access) are
+        // intentionally left on the normal permission path.
+        const skipSet = new Set(BRIDGE_CUSTOM_TOOLS);
+        for (const tool of tools) {
+            if (skipSet.has(tool.name) && !('skipPermission' in tool)) {
+                tool.skipPermission = true;
+            }
+        }
         if (tools.length > 0) {
             log.info(`Built ${tools.length} custom tool(s) for channel ${channelId.slice(0, 8)}...`);
         }
@@ -2152,8 +2432,8 @@ export class SessionManager {
                 properties: {
                     topic: {
                         type: 'string',
-                        enum: ['overview', 'commands', 'config', 'mcp', 'permissions', 'workspaces', 'hooks', 'skills', 'inter-agent', 'scheduling', 'troubleshooting', 'status'],
-                        description: "Topic to query. 'overview' = what the bridge is and key features. 'commands' = common slash commands. 'config' = configuration options. 'mcp' = MCP server setup. 'permissions' = permission system. 'workspaces' = workspace structure. 'hooks' = tool hooks. 'skills' = skill discovery. 'inter-agent' = bot-to-bot communication. 'scheduling' = task scheduling. 'troubleshooting' = common issues. 'status' = live system state.",
+                        enum: ['overview', 'commands', 'config', 'mcp', 'permissions', 'workspaces', 'hooks', 'skills', 'inter-agent', 'scheduling', 'providers', 'troubleshooting', 'status'],
+                        description: "Topic to query. 'overview' = what the bridge is and key features. 'commands' = common slash commands. 'config' = configuration options. 'mcp' = MCP server setup. 'permissions' = permission system. 'workspaces' = workspace structure. 'hooks' = tool hooks. 'skills' = skill discovery. 'inter-agent' = bot-to-bot communication. 'scheduling' = task scheduling. 'providers' = BYOK provider setup and commands. 'troubleshooting' = common issues. 'status' = live system state.",
                     },
                 },
                 required: [],