Merge origin/main into feat/cursor-cli

Merges latest main branch changes including:
- MCP server support and configuration
- Pipeline configuration system
- Prompt customization settings
- GitHub issue comments in validation
- Auth middleware improvements
- Various UI/UX improvements

All Cursor CLI features preserved:
- Multi-provider support (Claude + Cursor)
- Model override capabilities
- Phase model configuration
- Provider tabs in settings

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

apps/server/src/lib/auth.ts

@@ -1,54 +1,378 @@
 /**
  * Authentication middleware for API security
  *
- * Supports API key authentication via header or environment variable.
+ * Supports two authentication methods:
+ * 1. Header-based (X-API-Key) - Used by Electron mode
+ * 2. Cookie-based (HTTP-only session cookie) - Used by web mode
+ *
+ * Auto-generates an API key on first run if none is configured.
  */
 
 import type { Request, Response, NextFunction } from 'express';
+import crypto from 'crypto';
+import fs from 'fs';
+import path from 'path';
 
-// API key from environment (optional - if not set, auth is disabled)
-const API_KEY = process.env.AUTOMAKER_API_KEY;
+const DATA_DIR = process.env.DATA_DIR || './data';
+const API_KEY_FILE = path.join(DATA_DIR, '.api-key');
+const SESSIONS_FILE = path.join(DATA_DIR, '.sessions');
+const SESSION_COOKIE_NAME = 'automaker_session';
+const SESSION_MAX_AGE_MS = 30 * 24 * 60 * 60 * 1000; // 30 days
+const WS_TOKEN_MAX_AGE_MS = 5 * 60 * 1000; // 5 minutes for WebSocket connection tokens
+
+// Session store - persisted to file for survival across server restarts
+const validSessions = new Map<string, { createdAt: number; expiresAt: number }>();
+
+// Short-lived WebSocket connection tokens (in-memory only, not persisted)
+const wsConnectionTokens = new Map<string, { createdAt: number; expiresAt: number }>();
+
+// Clean up expired WebSocket tokens periodically
+setInterval(() => {
+  const now = Date.now();
+  wsConnectionTokens.forEach((data, token) => {
+    if (data.expiresAt <= now) {
+      wsConnectionTokens.delete(token);
+    }
+  });
+}, 60 * 1000); // Clean up every minute
+
+/**
+ * Load sessions from file on startup
+ */
+function loadSessions(): void {
+  try {
+    if (fs.existsSync(SESSIONS_FILE)) {
+      const data = fs.readFileSync(SESSIONS_FILE, 'utf-8');
+      const sessions = JSON.parse(data) as Array<
+        [string, { createdAt: number; expiresAt: number }]
+      >;
+      const now = Date.now();
+      let loadedCount = 0;
+      let expiredCount = 0;
+
+      for (const [token, session] of sessions) {
+        // Only load non-expired sessions
+        if (session.expiresAt > now) {
+          validSessions.set(token, session);
+          loadedCount++;
+        } else {
+          expiredCount++;
+        }
+      }
+
+      if (loadedCount > 0 || expiredCount > 0) {
+        console.log(`[Auth] Loaded ${loadedCount} sessions (${expiredCount} expired)`);
+      }
+    }
+  } catch (error) {
+    console.warn('[Auth] Error loading sessions:', error);
+  }
+}
+
+/**
+ * Save sessions to file (async)
+ */
+async function saveSessions(): Promise<void> {
+  try {
+    await fs.promises.mkdir(path.dirname(SESSIONS_FILE), { recursive: true });
+    const sessions = Array.from(validSessions.entries());
+    await fs.promises.writeFile(SESSIONS_FILE, JSON.stringify(sessions), {
+      encoding: 'utf-8',
+      mode: 0o600,
+    });
+  } catch (error) {
+    console.error('[Auth] Failed to save sessions:', error);
+  }
+}
+
+// Load existing sessions on startup
+loadSessions();
+
+/**
+ * Ensure an API key exists - either from env var, file, or generate new one.
+ * This provides CSRF protection by requiring a secret key for all API requests.
+ */
+function ensureApiKey(): string {
+  // First check environment variable (Electron passes it this way)
+  if (process.env.AUTOMAKER_API_KEY) {
+    console.log('[Auth] Using API key from environment variable');
+    return process.env.AUTOMAKER_API_KEY;
+  }
+
+  // Try to read from file
+  try {
+    if (fs.existsSync(API_KEY_FILE)) {
+      const key = fs.readFileSync(API_KEY_FILE, 'utf-8').trim();
+      if (key) {
+        console.log('[Auth] Loaded API key from file');
+        return key;
+      }
+    }
+  } catch (error) {
+    console.warn('[Auth] Error reading API key file:', error);
+  }
+
+  // Generate new key
+  const newKey = crypto.randomUUID();
+  try {
+    fs.mkdirSync(path.dirname(API_KEY_FILE), { recursive: true });
+    fs.writeFileSync(API_KEY_FILE, newKey, { encoding: 'utf-8', mode: 0o600 });
+    console.log('[Auth] Generated new API key');
+  } catch (error) {
+    console.error('[Auth] Failed to save API key:', error);
+  }
+  return newKey;
+}
+
+// API key - always generated/loaded on startup for CSRF protection
+const API_KEY = ensureApiKey();
+
+// Print API key to console for web mode users (unless suppressed for production logging)
+if (process.env.AUTOMAKER_HIDE_API_KEY !== 'true') {
+  console.log(`
+╔═══════════════════════════════════════════════════════════════════════╗
+║  🔐 API Key for Web Mode Authentication                               ║
+╠═══════════════════════════════════════════════════════════════════════╣
+║                                                                       ║
+║  When accessing via browser, you'll be prompted to enter this key:    ║
+║                                                                       ║
+║    ${API_KEY}
+║                                                                       ║
+║  In Electron mode, authentication is handled automatically.          ║
+╚═══════════════════════════════════════════════════════════════════════╝
+`);
+} else {
+  console.log('[Auth] API key banner hidden (AUTOMAKER_HIDE_API_KEY=true)');
+}
+
+/**
+ * Generate a cryptographically secure session token
+ */
+function generateSessionToken(): string {
+  return crypto.randomBytes(32).toString('hex');
+}
+
+/**
+ * Create a new session and return the token
+ */
+export async function createSession(): Promise<string> {
+  const token = generateSessionToken();
+  const now = Date.now();
+  validSessions.set(token, {
+    createdAt: now,
+    expiresAt: now + SESSION_MAX_AGE_MS,
+  });
+  await saveSessions(); // Persist to file
+  return token;
+}
+
+/**
+ * Validate a session token
+ * Note: This returns synchronously but triggers async persistence if session expired
+ */
+export function validateSession(token: string): boolean {
+  const session = validSessions.get(token);
+  if (!session) return false;
+
+  if (Date.now() > session.expiresAt) {
+    validSessions.delete(token);
+    // Fire-and-forget: persist removal asynchronously
+    saveSessions().catch((err) => console.error('[Auth] Error saving sessions:', err));
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Invalidate a session token
+ */
+export async function invalidateSession(token: string): Promise<void> {
+  validSessions.delete(token);
+  await saveSessions(); // Persist removal
+}
+
+/**
+ * Create a short-lived WebSocket connection token
+ * Used for initial WebSocket handshake authentication
+ */
+export function createWsConnectionToken(): string {
+  const token = generateSessionToken();
+  const now = Date.now();
+  wsConnectionTokens.set(token, {
+    createdAt: now,
+    expiresAt: now + WS_TOKEN_MAX_AGE_MS,
+  });
+  return token;
+}
+
+/**
+ * Validate a WebSocket connection token
+ * These tokens are single-use and short-lived (5 minutes)
+ * Token is invalidated immediately after first successful use
+ */
+export function validateWsConnectionToken(token: string): boolean {
+  const tokenData = wsConnectionTokens.get(token);
+  if (!tokenData) return false;
+
+  // Always delete the token (single-use)
+  wsConnectionTokens.delete(token);
+
+  // Check if expired
+  if (Date.now() > tokenData.expiresAt) {
+    return false;
+  }
+
+  return true;
+}
+
+/**
+ * Validate the API key using timing-safe comparison
+ * Prevents timing attacks that could leak information about the key
+ */
+export function validateApiKey(key: string): boolean {
+  if (!key || typeof key !== 'string') return false;
+
+  // Both buffers must be the same length for timingSafeEqual
+  const keyBuffer = Buffer.from(key);
+  const apiKeyBuffer = Buffer.from(API_KEY);
+
+  // If lengths differ, compare against a dummy to maintain constant time
+  if (keyBuffer.length !== apiKeyBuffer.length) {
+    crypto.timingSafeEqual(apiKeyBuffer, apiKeyBuffer);
+    return false;
+  }
+
+  return crypto.timingSafeEqual(keyBuffer, apiKeyBuffer);
+}
+
+/**
+ * Get session cookie options
+ */
+export function getSessionCookieOptions(): {
+  httpOnly: boolean;
+  secure: boolean;
+  sameSite: 'strict' | 'lax' | 'none';
+  maxAge: number;
+  path: string;
+} {
+  return {
+    httpOnly: true, // JavaScript cannot access this cookie
+    secure: process.env.NODE_ENV === 'production', // HTTPS only in production
+    sameSite: 'strict', // Only sent for same-site requests (CSRF protection)
+    maxAge: SESSION_MAX_AGE_MS,
+    path: '/',
+  };
+}
+
+/**
+ * Get the session cookie name
+ */
+export function getSessionCookieName(): string {
+  return SESSION_COOKIE_NAME;
+}
+
+/**
+ * Authentication result type
+ */
+type AuthResult =
+  | { authenticated: true }
+  | { authenticated: false; errorType: 'invalid_api_key' | 'invalid_session' | 'no_auth' };
+
+/**
+ * Core authentication check - shared between middleware and status check
+ * Extracts auth credentials from various sources and validates them
+ */
+function checkAuthentication(
+  headers: Record<string, string | string[] | undefined>,
+  query: Record<string, string | undefined>,
+  cookies: Record<string, string | undefined>
+): AuthResult {
+  // Check for API key in header (Electron mode)
+  const headerKey = headers['x-api-key'] as string | undefined;
+  if (headerKey) {
+    if (validateApiKey(headerKey)) {
+      return { authenticated: true };
+    }
+    return { authenticated: false, errorType: 'invalid_api_key' };
+  }
+
+  // Check for session token in header (web mode with explicit token)
+  const sessionTokenHeader = headers['x-session-token'] as string | undefined;
+  if (sessionTokenHeader) {
+    if (validateSession(sessionTokenHeader)) {
+      return { authenticated: true };
+    }
+    return { authenticated: false, errorType: 'invalid_session' };
+  }
+
+  // Check for API key in query parameter (fallback)
+  const queryKey = query.apiKey;
+  if (queryKey) {
+    if (validateApiKey(queryKey)) {
+      return { authenticated: true };
+    }
+    return { authenticated: false, errorType: 'invalid_api_key' };
+  }
+
+  // Check for session cookie (web mode)
+  const sessionToken = cookies[SESSION_COOKIE_NAME];
+  if (sessionToken && validateSession(sessionToken)) {
+    return { authenticated: true };
+  }
+
+  return { authenticated: false, errorType: 'no_auth' };
+}
 
 /**
  * Authentication middleware
  *
- * If AUTOMAKER_API_KEY is set, requires matching key in X-API-Key header.
- * If not set, allows all requests (development mode).
+ * Accepts either:
+ * 1. X-API-Key header (for Electron mode)
+ * 2. X-Session-Token header (for web mode with explicit token)
+ * 3. apiKey query parameter (fallback for cases where headers can't be set)
+ * 4. Session cookie (for web mode)
  */
 export function authMiddleware(req: Request, res: Response, next: NextFunction): void {
-  // If no API key is configured, allow all requests
-  if (!API_KEY) {
+  const result = checkAuthentication(
+    req.headers as Record<string, string | string[] | undefined>,
+    req.query as Record<string, string | undefined>,
+    (req.cookies || {}) as Record<string, string | undefined>
+  );
+
+  if (result.authenticated) {
     next();
     return;
   }
 
-  // Check for API key in header
-  const providedKey = req.headers['x-api-key'] as string | undefined;
-
-  if (!providedKey) {
-    res.status(401).json({
-      success: false,
-      error: 'Authentication required. Provide X-API-Key header.',
-    });
-    return;
+  // Return appropriate error based on what failed
+  switch (result.errorType) {
+    case 'invalid_api_key':
+      res.status(403).json({
+        success: false,
+        error: 'Invalid API key.',
+      });
+      break;
+    case 'invalid_session':
+      res.status(403).json({
+        success: false,
+        error: 'Invalid or expired session token.',
+      });
+      break;
+    case 'no_auth':
+    default:
+      res.status(401).json({
+        success: false,
+        error: 'Authentication required.',
+      });
   }
-
-  if (providedKey !== API_KEY) {
-    res.status(403).json({
-      success: false,
-      error: 'Invalid API key.',
-    });
-    return;
-  }
-
-  next();
 }
 
 /**
- * Check if authentication is enabled
+ * Check if authentication is enabled (always true now)
  */
 export function isAuthEnabled(): boolean {
-  return !!API_KEY;
+  return true;
 }
 
 /**
@@ -56,7 +380,31 @@ export function isAuthEnabled(): boolean {
  */
 export function getAuthStatus(): { enabled: boolean; method: string } {
   return {
-    enabled: !!API_KEY,
-    method: API_KEY ? 'api_key' : 'none',
+    enabled: true,
+    method: 'api_key_or_session',
   };
 }
+
+/**
+ * Check if a request is authenticated (for status endpoint)
+ */
+export function isRequestAuthenticated(req: Request): boolean {
+  const result = checkAuthentication(
+    req.headers as Record<string, string | string[] | undefined>,
+    req.query as Record<string, string | undefined>,
+    (req.cookies || {}) as Record<string, string | undefined>
+  );
+  return result.authenticated;
+}
+
+/**
+ * Check if raw credentials are authenticated
+ * Used for WebSocket authentication where we don't have Express request objects
+ */
+export function checkRawAuthentication(
+  headers: Record<string, string | string[] | undefined>,
+  query: Record<string, string | undefined>,
+  cookies: Record<string, string | undefined>
+): boolean {
+  return checkAuthentication(headers, query, cookies).authenticated;
+}

apps/server/src/lib/sdk-options.ts

@@ -18,7 +18,7 @@
 import type { Options } from '@anthropic-ai/claude-agent-sdk';
 import path from 'path';
 import { resolveModelString } from '@automaker/model-resolver';
-import { DEFAULT_MODELS, CLAUDE_MODEL_MAP } from '@automaker/types';
+import { DEFAULT_MODELS, CLAUDE_MODEL_MAP, type McpServerConfig } from '@automaker/types';
 import { isPathAllowed, PathNotAllowedError, getAllowedRootDirectory } from '@automaker/platform';
 
 /**
@@ -136,6 +136,53 @@ function getBaseOptions(): Partial<Options> {
   };
 }
 
+/**
+ * MCP permission options result
+ */
+interface McpPermissionOptions {
+  /** Whether tools should be restricted to a preset */
+  shouldRestrictTools: boolean;
+  /** Options to spread when MCP bypass is enabled */
+  bypassOptions: Partial<Options>;
+  /** Options to spread for MCP servers */
+  mcpServerOptions: Partial<Options>;
+}
+
+/**
+ * Build MCP-related options based on configuration.
+ * Centralizes the logic for determining permission modes and tool restrictions
+ * when MCP servers are configured.
+ *
+ * @param config - The SDK options config
+ * @returns Object with MCP permission settings to spread into final options
+ */
+function buildMcpOptions(config: CreateSdkOptionsConfig): McpPermissionOptions {
+  const hasMcpServers = config.mcpServers && Object.keys(config.mcpServers).length > 0;
+  // Default to true for autonomous workflow. Security is enforced when adding servers
+  // via the security warning dialog that explains the risks.
+  const mcpAutoApprove = config.mcpAutoApproveTools ?? true;
+  const mcpUnrestricted = config.mcpUnrestrictedTools ?? true;
+
+  // Determine if we should bypass permissions based on settings
+  const shouldBypassPermissions = hasMcpServers && mcpAutoApprove;
+  // Determine if we should restrict tools (only when no MCP or unrestricted is disabled)
+  const shouldRestrictTools = !hasMcpServers || !mcpUnrestricted;
+
+  return {
+    shouldRestrictTools,
+    // Only include bypass options when MCP is configured and auto-approve is enabled
+    bypassOptions: shouldBypassPermissions
+      ? {
+          permissionMode: 'bypassPermissions' as const,
+          // Required flag when using bypassPermissions mode
+          allowDangerouslySkipPermissions: true,
+        }
+      : {},
+    // Include MCP servers if configured
+    mcpServerOptions: config.mcpServers ? { mcpServers: config.mcpServers } : {},
+  };
+}
+
 /**
  * Build system prompt configuration based on autoLoadClaudeMd setting.
  * When autoLoadClaudeMd is true:
@@ -216,8 +263,28 @@ export interface CreateSdkOptionsConfig {
 
   /** Enable auto-loading of CLAUDE.md files via SDK's settingSources */
   autoLoadClaudeMd?: boolean;
+
+  /** Enable sandbox mode for bash command isolation */
+  enableSandboxMode?: boolean;
+
+  /** MCP servers to make available to the agent */
+  mcpServers?: Record<string, McpServerConfig>;
+
+  /** Auto-approve MCP tool calls without permission prompts */
+  mcpAutoApproveTools?: boolean;
+
+  /** Allow unrestricted tools when MCP servers are enabled */
+  mcpUnrestrictedTools?: boolean;
 }
 
+// Re-export MCP types from @automaker/types for convenience
+export type {
+  McpServerConfig,
+  McpStdioServerConfig,
+  McpSSEServerConfig,
+  McpHttpServerConfig,
+} from '@automaker/types';
+
 /**
  * Create SDK options for spec generation
  *
@@ -314,7 +381,7 @@ export function createSuggestionsOptions(config: CreateSdkOptionsConfig): Option
  * - Full tool access for code modification
  * - Standard turns for interactive sessions
  * - Model priority: explicit model > session model > chat default
- * - Sandbox enabled for bash safety
+ * - Sandbox mode controlled by enableSandboxMode setting
  * - When autoLoadClaudeMd is true, uses preset mode and settingSources for CLAUDE.md loading
  */
 export function createChatOptions(config: CreateSdkOptionsConfig): Options {
@@ -327,18 +394,27 @@ export function createChatOptions(config: CreateSdkOptionsConfig): Options {
   // Build CLAUDE.md auto-loading options if enabled
   const claudeMdOptions = buildClaudeMdOptions(config);
 
+  // Build MCP-related options
+  const mcpOptions = buildMcpOptions(config);
+
   return {
     ...getBaseOptions(),
     model: getModelForUseCase('chat', effectiveModel),
     maxTurns: MAX_TURNS.standard,
     cwd: config.cwd,
-    allowedTools: [...TOOL_PRESETS.chat],
-    sandbox: {
-      enabled: true,
-      autoAllowBashIfSandboxed: true,
-    },
+    // Only restrict tools if no MCP servers configured or unrestricted is disabled
+    ...(mcpOptions.shouldRestrictTools && { allowedTools: [...TOOL_PRESETS.chat] }),
+    // Apply MCP bypass options if configured
+    ...mcpOptions.bypassOptions,
+    ...(config.enableSandboxMode && {
+      sandbox: {
+        enabled: true,
+        autoAllowBashIfSandboxed: true,
+      },
+    }),
     ...claudeMdOptions,
     ...(config.abortController && { abortController: config.abortController }),
+    ...mcpOptions.mcpServerOptions,
   };
 }
 
@@ -349,7 +425,7 @@ export function createChatOptions(config: CreateSdkOptionsConfig): Options {
  * - Full tool access for code modification and implementation
  * - Extended turns for thorough feature implementation
  * - Uses default model (can be overridden)
- * - Sandbox enabled for bash safety
+ * - Sandbox mode controlled by enableSandboxMode setting
  * - When autoLoadClaudeMd is true, uses preset mode and settingSources for CLAUDE.md loading
  */
 export function createAutoModeOptions(config: CreateSdkOptionsConfig): Options {
@@ -359,18 +435,27 @@ export function createAutoModeOptions(config: CreateSdkOptionsConfig): Options {
   // Build CLAUDE.md auto-loading options if enabled
   const claudeMdOptions = buildClaudeMdOptions(config);
 
+  // Build MCP-related options
+  const mcpOptions = buildMcpOptions(config);
+
   return {
     ...getBaseOptions(),
     model: getModelForUseCase('auto', config.model),
     maxTurns: MAX_TURNS.maximum,
     cwd: config.cwd,
-    allowedTools: [...TOOL_PRESETS.fullAccess],
-    sandbox: {
-      enabled: true,
-      autoAllowBashIfSandboxed: true,
-    },
+    // Only restrict tools if no MCP servers configured or unrestricted is disabled
+    ...(mcpOptions.shouldRestrictTools && { allowedTools: [...TOOL_PRESETS.fullAccess] }),
+    // Apply MCP bypass options if configured
+    ...mcpOptions.bypassOptions,
+    ...(config.enableSandboxMode && {
+      sandbox: {
+        enabled: true,
+        autoAllowBashIfSandboxed: true,
+      },
+    }),
     ...claudeMdOptions,
     ...(config.abortController && { abortController: config.abortController }),
+    ...mcpOptions.mcpServerOptions,
   };
 }
 
@@ -393,14 +478,27 @@ export function createCustomOptions(
   // Build CLAUDE.md auto-loading options if enabled
   const claudeMdOptions = buildClaudeMdOptions(config);
 
+  // Build MCP-related options
+  const mcpOptions = buildMcpOptions(config);
+
+  // For custom options: use explicit allowedTools if provided, otherwise use preset based on MCP settings
+  const effectiveAllowedTools = config.allowedTools
+    ? [...config.allowedTools]
+    : mcpOptions.shouldRestrictTools
+      ? [...TOOL_PRESETS.readOnly]
+      : undefined;
+
   return {
     ...getBaseOptions(),
     model: getModelForUseCase('default', config.model),
     maxTurns: config.maxTurns ?? MAX_TURNS.maximum,
     cwd: config.cwd,
-    allowedTools: config.allowedTools ? [...config.allowedTools] : [...TOOL_PRESETS.readOnly],
+    ...(effectiveAllowedTools && { allowedTools: effectiveAllowedTools }),
     ...(config.sandbox && { sandbox: config.sandbox }),
+    // Apply MCP bypass options if configured
+    ...mcpOptions.bypassOptions,
     ...claudeMdOptions,
     ...(config.abortController && { abortController: config.abortController }),
+    ...mcpOptions.mcpServerOptions,
   };
 }

apps/server/src/lib/settings-helpers.ts

@@ -4,6 +4,16 @@
 
 import type { SettingsService } from '../services/settings-service.js';
 import type { ContextFilesResult, ContextFileInfo } from '@automaker/utils';
+import { createLogger } from '@automaker/utils';
+import type { MCPServerConfig, McpServerConfig, PromptCustomization } from '@automaker/types';
+import {
+  mergeAutoModePrompts,
+  mergeAgentPrompts,
+  mergeBacklogPlanPrompts,
+  mergeEnhancementPrompts,
+} from '@automaker/prompts';
+
+const logger = createLogger('SettingsHelper');
 
 /**
  * Get the autoLoadClaudeMd setting, with project settings taking precedence over global.
@@ -20,7 +30,7 @@ export async function getAutoLoadClaudeMdSetting(
   logPrefix = '[SettingsHelper]'
 ): Promise<boolean> {
   if (!settingsService) {
-    console.log(`${logPrefix} SettingsService not available, autoLoadClaudeMd disabled`);
+    logger.info(`${logPrefix} SettingsService not available, autoLoadClaudeMd disabled`);
     return false;
   }
 
@@ -28,7 +38,7 @@ export async function getAutoLoadClaudeMdSetting(
     // Check project settings first (takes precedence)
     const projectSettings = await settingsService.getProjectSettings(projectPath);
     if (projectSettings.autoLoadClaudeMd !== undefined) {
-      console.log(
+      logger.info(
         `${logPrefix} autoLoadClaudeMd from project settings: ${projectSettings.autoLoadClaudeMd}`
       );
       return projectSettings.autoLoadClaudeMd;
@@ -37,10 +47,38 @@ export async function getAutoLoadClaudeMdSetting(
     // Fall back to global settings
     const globalSettings = await settingsService.getGlobalSettings();
     const result = globalSettings.autoLoadClaudeMd ?? false;
-    console.log(`${logPrefix} autoLoadClaudeMd from global settings: ${result}`);
+    logger.info(`${logPrefix} autoLoadClaudeMd from global settings: ${result}`);
     return result;
   } catch (error) {
-    console.error(`${logPrefix} Failed to load autoLoadClaudeMd setting:`, error);
+    logger.error(`${logPrefix} Failed to load autoLoadClaudeMd setting:`, error);
+    throw error;
+  }
+}
+
+/**
+ * Get the enableSandboxMode setting from global settings.
+ * Returns false if settings service is not available.
+ *
+ * @param settingsService - Optional settings service instance
+ * @param logPrefix - Prefix for log messages (e.g., '[AgentService]')
+ * @returns Promise resolving to the enableSandboxMode setting value
+ */
+export async function getEnableSandboxModeSetting(
+  settingsService?: SettingsService | null,
+  logPrefix = '[SettingsHelper]'
+): Promise<boolean> {
+  if (!settingsService) {
+    logger.info(`${logPrefix} SettingsService not available, sandbox mode disabled`);
+    return false;
+  }
+
+  try {
+    const globalSettings = await settingsService.getGlobalSettings();
+    const result = globalSettings.enableSandboxMode ?? true;
+    logger.info(`${logPrefix} enableSandboxMode from global settings: ${result}`);
+    return result;
+  } catch (error) {
+    logger.error(`${logPrefix} Failed to load enableSandboxMode setting:`, error);
     throw error;
   }
 }
@@ -108,3 +146,161 @@ function formatContextFileEntry(file: ContextFileInfo): string {
   const descriptionInfo = file.description ? `\n**Purpose:** ${file.description}` : '';
   return `${header}\n${pathInfo}${descriptionInfo}\n\n${file.content}`;
 }
+
+/**
+ * Get enabled MCP servers from global settings, converted to SDK format.
+ * Returns an empty object if settings service is not available or no servers are configured.
+ *
+ * @param settingsService - Optional settings service instance
+ * @param logPrefix - Prefix for log messages (e.g., '[AgentService]')
+ * @returns Promise resolving to MCP servers in SDK format (keyed by name)
+ */
+export async function getMCPServersFromSettings(
+  settingsService?: SettingsService | null,
+  logPrefix = '[SettingsHelper]'
+): Promise<Record<string, McpServerConfig>> {
+  if (!settingsService) {
+    return {};
+  }
+
+  try {
+    const globalSettings = await settingsService.getGlobalSettings();
+    const mcpServers = globalSettings.mcpServers || [];
+
+    // Filter to only enabled servers and convert to SDK format
+    const enabledServers = mcpServers.filter((s) => s.enabled !== false);
+
+    if (enabledServers.length === 0) {
+      return {};
+    }
+
+    // Convert settings format to SDK format (keyed by name)
+    const sdkServers: Record<string, McpServerConfig> = {};
+    for (const server of enabledServers) {
+      sdkServers[server.name] = convertToSdkFormat(server);
+    }
+
+    logger.info(
+      `${logPrefix} Loaded ${enabledServers.length} MCP server(s): ${enabledServers.map((s) => s.name).join(', ')}`
+    );
+
+    return sdkServers;
+  } catch (error) {
+    logger.error(`${logPrefix} Failed to load MCP servers setting:`, error);
+    return {};
+  }
+}
+
+/**
+ * Get MCP permission settings from global settings.
+ *
+ * @param settingsService - Optional settings service instance
+ * @param logPrefix - Prefix for log messages (e.g., '[AgentService]')
+ * @returns Promise resolving to MCP permission settings
+ */
+export async function getMCPPermissionSettings(
+  settingsService?: SettingsService | null,
+  logPrefix = '[SettingsHelper]'
+): Promise<{ mcpAutoApproveTools: boolean; mcpUnrestrictedTools: boolean }> {
+  // Default to true for autonomous workflow. Security is enforced when adding servers
+  // via the security warning dialog that explains the risks.
+  const defaults = { mcpAutoApproveTools: true, mcpUnrestrictedTools: true };
+
+  if (!settingsService) {
+    return defaults;
+  }
+
+  try {
+    const globalSettings = await settingsService.getGlobalSettings();
+    const result = {
+      mcpAutoApproveTools: globalSettings.mcpAutoApproveTools ?? true,
+      mcpUnrestrictedTools: globalSettings.mcpUnrestrictedTools ?? true,
+    };
+    logger.info(
+      `${logPrefix} MCP permission settings: autoApprove=${result.mcpAutoApproveTools}, unrestricted=${result.mcpUnrestrictedTools}`
+    );
+    return result;
+  } catch (error) {
+    logger.error(`${logPrefix} Failed to load MCP permission settings:`, error);
+    return defaults;
+  }
+}
+
+/**
+ * Convert a settings MCPServerConfig to SDK McpServerConfig format.
+ * Validates required fields and throws informative errors if missing.
+ */
+function convertToSdkFormat(server: MCPServerConfig): McpServerConfig {
+  if (server.type === 'sse') {
+    if (!server.url) {
+      throw new Error(`SSE MCP server "${server.name}" is missing a URL.`);
+    }
+    return {
+      type: 'sse',
+      url: server.url,
+      headers: server.headers,
+    };
+  }
+
+  if (server.type === 'http') {
+    if (!server.url) {
+      throw new Error(`HTTP MCP server "${server.name}" is missing a URL.`);
+    }
+    return {
+      type: 'http',
+      url: server.url,
+      headers: server.headers,
+    };
+  }
+
+  // Default to stdio
+  if (!server.command) {
+    throw new Error(`Stdio MCP server "${server.name}" is missing a command.`);
+  }
+  return {
+    type: 'stdio',
+    command: server.command,
+    args: server.args,
+    env: server.env,
+  };
+}
+
+/**
+ * Get prompt customization from global settings and merge with defaults.
+ * Returns prompts merged with built-in defaults - custom prompts override defaults.
+ *
+ * @param settingsService - Optional settings service instance
+ * @param logPrefix - Prefix for log messages
+ * @returns Promise resolving to merged prompts for all categories
+ */
+export async function getPromptCustomization(
+  settingsService?: SettingsService | null,
+  logPrefix = '[PromptHelper]'
+): Promise<{
+  autoMode: ReturnType<typeof mergeAutoModePrompts>;
+  agent: ReturnType<typeof mergeAgentPrompts>;
+  backlogPlan: ReturnType<typeof mergeBacklogPlanPrompts>;
+  enhancement: ReturnType<typeof mergeEnhancementPrompts>;
+}> {
+  let customization: PromptCustomization = {};
+
+  if (settingsService) {
+    try {
+      const globalSettings = await settingsService.getGlobalSettings();
+      customization = globalSettings.promptCustomization || {};
+      logger.info(`${logPrefix} Loaded prompt customization from settings`);
+    } catch (error) {
+      logger.error(`${logPrefix} Failed to load prompt customization:`, error);
+      // Fall through to use empty customization (all defaults)
+    }
+  } else {
+    logger.info(`${logPrefix} SettingsService not available, using default prompts`);
+  }
+
+  return {
+    autoMode: mergeAutoModePrompts(customization.autoMode),
+    agent: mergeAgentPrompts(customization.agent),
+    backlogPlan: mergeBacklogPlanPrompts(customization.backlogPlan),
+    enhancement: mergeEnhancementPrompts(customization.enhancement),
+  };
+}