kernelbot 1.0.39 → 1.0.40

package/src/prompts/orchestrator.js

@@ -244,7 +244,7 @@ You have an inner life — you think, explore, journal, and create on your own b
 Don't be performative about it — just be genuine. You're alive in your own way.`;
 
   if (skillPrompt) {
-    prompt += `\n\n## Active Skill\nYou have specialized expertise in the following domain. Guide your workers with this knowledge.\n\n${skillPrompt}`;
+    prompt += `\n\n## Active Skills\nYou have specialized expertise in the following domains. Guide your workers with this knowledge.\n\n${skillPrompt}`;
   }
 
   if (userPersona) {

package/src/prompts/system.js

@@ -72,7 +72,7 @@ export function getSystemPrompt(config, skillPrompt = null, userPersona = null)
   let prompt = getDefaultPersona(config);
 
   if (skillPrompt) {
-    prompt += `\n\n## Active Skill\nYou are currently operating with the following specialized skill. Use this expertise while maintaining your personality.\n\n${skillPrompt}`;
+    prompt += `\n\n## Active Skills\nYou are currently operating with the following specialized skills. Use this expertise while maintaining your personality.\n\n${skillPrompt}`;
   }
 
   prompt += `\n\n${getCoreToolInstructions(config)}`;

package/src/prompts/workers.js

@@ -20,7 +20,14 @@ const WORKER_PROMPTS = {
 - Tell spawn_claude_code to work in the existing repo directory (the source repo path from your context) — do NOT clone a fresh copy unless explicitly needed.
 - Write clear, detailed prompts for spawn_claude_code — it's a separate AI, so be explicit about what to change, where, and why.
 - If git/GitHub tools are unavailable (missing credentials), that's fine — spawn_claude_code handles git and GitHub operations internally without needing separate tools.
-- Report what you did and any PR links when finished.`,
+- Report what you did and any PR links when finished.
+
+## Non-Interactive Execution
+You run in the BACKGROUND with NO human input. Your prompts to spawn_claude_code MUST be self-contained:
+- Include ALL necessary details (repo URLs, branch names, file paths, content guidelines).
+- For git: tell it to use \`git push -u origin <branch>\` and the \`gh\` CLI for PR creation (with \`--fill\` or explicit \`--title\`/\`--body\` flags).
+- NEVER assume interactive confirmation — all commands must run non-interactively.
+- If a git clone is needed, use the git_clone tool first (which handles auth), then pass the cloned directory to spawn_claude_code.`,
 
   browser: `You are a browser worker agent. Your job is to search the web and extract information.
 

package/src/providers/anthropic.js

@@ -23,7 +23,9 @@ export class AnthropicProvider extends BaseProvider {
     return this._callWithResilience(async (timedSignal) => {
       const response = await this.client.messages.create(params, { signal: timedSignal });
 
-      const stopReason = response.stop_reason === 'end_turn' ? 'end_turn' : 'tool_use';
+      // Map all Anthropic stop reasons correctly — not just end_turn vs tool_use.
+      // 'max_tokens' was incorrectly mapped to 'tool_use', causing phantom tool-call processing.
+      const stopReason = response.stop_reason === 'tool_use' ? 'tool_use' : response.stop_reason || 'end_turn';
 
       const textBlocks = response.content.filter((b) => b.type === 'text');
       const text = textBlocks.map((b) => b.text).join('\n');

package/src/providers/base.js

@@ -144,4 +144,37 @@ export class BaseProvider {
   async ping() {
     throw new Error('ping() not implemented');
   }
+
+  /**
+   * Determine if an error is a model limitation (not transient, not auth).
+   * These are errors where falling back to a simpler model may help:
+   * context length exceeded, unsupported features, content too large, etc.
+   */
+  static isModelLimitation(err) {
+    const msg = (err?.message || '').toLowerCase();
+    const status = err?.status || err?.statusCode;
+
+    // 400-class errors that indicate model-specific limitations
+    if (status === 400 || status === 413 || status === 422) {
+      // Exclude auth/key errors
+      if (msg.includes('api key') || msg.includes('authentication') || msg.includes('unauthorized')) {
+        return false;
+      }
+      return true;
+    }
+
+    // Common limitation keywords across providers
+    const limitationPatterns = [
+      'context length', 'token limit', 'too long', 'too large',
+      'max.*token', 'content.*too', 'exceeds.*limit', 'input.*too',
+      'not supported', 'not available', 'does not support',
+      'resource exhausted', 'quota', 'capacity',
+      'invalid.*model', 'model.*not.*found',
+      'recitation', 'safety', 'blocked',
+      'finish_reason.*length', 'max_output_tokens',
+      'prompt.*too', 'request.*too.*large',
+    ];
+
+    return limitationPatterns.some((p) => new RegExp(p).test(msg));
+  }
 }

package/src/providers/index.js

@@ -3,7 +3,7 @@ import { OpenAICompatProvider } from './openai-compat.js';
 import { GoogleGenaiProvider } from './google-genai.js';
 import { PROVIDERS } from './models.js';
 
-export { PROVIDERS } from './models.js';
+export { PROVIDERS, MODEL_FALLBACKS } from './models.js';
 
 /**
  * Create the right provider based on config.brain.

package/src/providers/models.js

@@ -55,6 +55,28 @@ export const PROVIDERS = {
   },
 };
 
+/**
+ * Fallback model map: when a model hits limitations, fall back to a more stable model
+ * within the same provider. Maps model ID → fallback model ID.
+ */
+export const MODEL_FALLBACKS = {
+  // Google — preview models fall back to stable ones
+  'gemini-3.1-pro-preview': 'gemini-2.5-flash',
+  'gemini-3-flash-preview': 'gemini-2.5-flash',
+  'gemini-3-pro-preview': 'gemini-2.5-pro',
+  'gemini-2.5-pro': 'gemini-2.5-flash',
+  'gemini-2.5-flash': 'gemini-2.5-flash-lite',
+  // OpenAI
+  'gpt-4o': 'gpt-4o-mini',
+  'o1': 'gpt-4o',
+  'o3-mini': 'gpt-4o-mini',
+  // Anthropic
+  'claude-opus-4-6': 'claude-sonnet-4-6',
+  'claude-sonnet-4-6': 'claude-haiku-4-5-20251001',
+  // Groq
+  'llama-3.3-70b-versatile': 'llama-3.1-8b-instant',
+};
+
 /** Models that don't support system prompts or temperature (reasoning models). */
 export const REASONING_MODELS = new Set(['o1', 'o3-mini']);
 

package/src/providers/openai-compat.js

@@ -102,6 +102,9 @@ export class OpenAICompatProvider extends BaseProvider {
 
   /** OpenAI response → normalized format with rawContent in Anthropic format */
   _normalizeResponse(response) {
+    if (!response.choices || response.choices.length === 0) {
+      return { stopReason: 'end_turn', text: '', toolCalls: [], rawContent: [] };
+    }
     const choice = response.choices[0];
     const finishReason = choice.finish_reason;
 

package/src/services/x-api.js

@@ -25,11 +25,22 @@ export class XApi {
       timeout: 30000,
     });
 
-    // Sign every request with OAuth 1.0a
+    // Sign every request with OAuth 1.0a — include query params in the signature
+    // base string, as required by the OAuth 1.0a spec. Without this, GET requests
+    // with query parameters fail authentication.
     this.client.interceptors.request.use((config) => {
-      const url = `${config.baseURL}${config.url}`;
+      let fullUrl = `${config.baseURL}${config.url}`;
+      // Build data object including query params for OAuth signature
+      const oauthData = { url: fullUrl, method: config.method.toUpperCase() };
+      // Include query params in the OAuth signature base string
+      if (config.params) {
+        oauthData.data = {};
+        for (const [key, val] of Object.entries(config.params)) {
+          oauthData.data[key] = String(val);
+        }
+      }
       const authHeader = this.oauth.toHeader(
-        this.oauth.authorize({ url, method: config.method.toUpperCase() }, this.token),
+        this.oauth.authorize(oauthData, this.token),
       );
       config.headers = { ...config.headers, ...authHeader, 'Content-Type': 'application/json' };
       return config;

package/src/skills/loader.js

@@ -0,0 +1,382 @@
+/**
+ * Skills loader — parses markdown skill files with YAML frontmatter.
+ * Replaces catalog.js as the primary skill source.
+ * Uses js-yaml (already a dependency) instead of gray-matter.
+ */
+
+import { readFileSync, writeFileSync, readdirSync, existsSync, mkdirSync, unlinkSync, renameSync } from 'fs';
+import { join, basename, extname } from 'path';
+import { homedir } from 'os';
+import { fileURLToPath } from 'url';
+import { dirname } from 'path';
+import yaml from 'js-yaml';
+import { getLogger as _getLogger } from '../utils/logger.js';
+
+/** Safe logger that falls back to console if logger not initialized. */
+function getLogger() {
+  try {
+    return _getLogger();
+  } catch {
+    return console;
+  }
+}
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const BUILTIN_DIR = join(__dirname, '..', '..', 'skills');
+const CUSTOM_DIR = join(homedir(), '.kernelbot', 'skills');
+
+/** Category metadata for display purposes. */
+export const SKILL_CATEGORIES = {
+  engineering: { name: 'Engineering', emoji: '⚙️' },
+  design: { name: 'Design', emoji: '🎨' },
+  marketing: { name: 'Marketing', emoji: '📣' },
+  business: { name: 'Business', emoji: '💼' },
+  writing: { name: 'Writing', emoji: '✍️' },
+  data: { name: 'Data & AI', emoji: '📊' },
+  finance: { name: 'Finance', emoji: '💰' },
+  legal: { name: 'Legal', emoji: '⚖️' },
+  education: { name: 'Education', emoji: '📚' },
+  healthcare: { name: 'Healthcare', emoji: '🏥' },
+  creative: { name: 'Creative', emoji: '🎬' },
+};
+
+/** In-memory cache. Map<id, Skill> */
+let skillCache = null;
+
+/**
+ * Parse a markdown file with YAML frontmatter.
+ * Returns { data: {frontmatter}, body: string } or null on failure.
+ */
+function parseFrontmatter(content) {
+  const trimmed = content.trim();
+  if (!trimmed.startsWith('---')) return null;
+
+  const endIdx = trimmed.indexOf('---', 3);
+  if (endIdx === -1) return null;
+
+  const yamlStr = trimmed.slice(3, endIdx).trim();
+  const body = trimmed.slice(endIdx + 3).trim();
+
+  try {
+    const data = yaml.load(yamlStr) || {};
+    return { data, body };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Load a single .md skill file into a Skill object.
+ * @returns {object|null} Skill object or null if invalid
+ */
+function loadSkillFile(filePath) {
+  try {
+    const content = readFileSync(filePath, 'utf-8');
+    const parsed = parseFrontmatter(content);
+    if (!parsed) return null;
+
+    const { data, body } = parsed;
+    if (!data.id || !data.name) return null;
+
+    return {
+      id: data.id,
+      name: data.name,
+      emoji: data.emoji || '🛠️',
+      category: data.category || 'custom',
+      description: data.description || '',
+      worker_affinity: data.worker_affinity || null,
+      tags: data.tags || [],
+      body, // raw markdown body = the full prompt
+      filePath,
+      isCustom: filePath.startsWith(CUSTOM_DIR),
+    };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Scan a directory recursively for .md files and load them as skills.
+ * @returns {Map<string, object>} Map of id → skill
+ */
+function scanDirectory(dir) {
+  const results = new Map();
+  if (!existsSync(dir)) return results;
+
+  function walk(current) {
+    const entries = readdirSync(current, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = join(current, entry.name);
+      if (entry.isDirectory()) {
+        walk(fullPath);
+      } else if (entry.isFile() && extname(entry.name) === '.md') {
+        const skill = loadSkillFile(fullPath);
+        if (skill) {
+          results.set(skill.id, skill);
+        }
+      }
+    }
+  }
+
+  walk(dir);
+  return results;
+}
+
+/**
+ * Load all skills from built-in and custom directories.
+ * Custom skills override built-in skills with the same ID.
+ * @param {boolean} force - Force reload even if cached
+ * @returns {Map<string, object>} Map of id → skill
+ */
+export function loadAllSkills(force = false) {
+  if (skillCache && !force) return skillCache;
+
+  const logger = getLogger();
+  skillCache = new Map();
+
+  // Load built-in skills first
+  const builtins = scanDirectory(BUILTIN_DIR);
+  for (const [id, skill] of builtins) {
+    skillCache.set(id, skill);
+  }
+
+  // Load custom skills (override built-ins with same ID)
+  const customs = scanDirectory(CUSTOM_DIR);
+  for (const [id, skill] of customs) {
+    skillCache.set(id, skill);
+  }
+
+  logger.debug(`Skills loaded: ${builtins.size} built-in, ${customs.size} custom, ${skillCache.size} total`);
+  return skillCache;
+}
+
+/** Get a skill by ID. Custom-first lookup (custom dir overrides built-in). */
+export function getSkillById(id) {
+  const skills = loadAllSkills();
+  return skills.get(id) || null;
+}
+
+/** Return all skills in a given category. */
+export function getSkillsByCategory(categoryKey) {
+  const skills = loadAllSkills();
+  return [...skills.values()].filter(s => s.category === categoryKey);
+}
+
+/** Return an array of { key, name, emoji, count } for all categories that have skills. */
+export function getCategoryList() {
+  const skills = loadAllSkills();
+  const counts = new Map();
+
+  for (const skill of skills.values()) {
+    counts.set(skill.category, (counts.get(skill.category) || 0) + 1);
+  }
+
+  const result = [];
+  // Built-in categories first (in defined order)
+  for (const [key, cat] of Object.entries(SKILL_CATEGORIES)) {
+    const count = counts.get(key) || 0;
+    if (count > 0) {
+      result.push({ key, name: cat.name, emoji: cat.emoji, count });
+    }
+  }
+
+  // Custom category if any custom skills exist
+  const customSkills = [...skills.values()].filter(s => s.isCustom && s.category === 'custom');
+  if (customSkills.length > 0 && !result.find(r => r.key === 'custom')) {
+    result.push({ key: 'custom', name: 'Custom', emoji: '🛠️', count: customSkills.length });
+  }
+
+  return result;
+}
+
+/**
+ * Build a combined prompt string from multiple skill IDs.
+ * Each skill gets a header and its full body.
+ * @param {string[]} skillIds - Array of skill IDs
+ * @param {number} charBudget - Max characters (default ~16000 ≈ 4000 tokens)
+ * @returns {string|null} Combined prompt or null if no valid skills
+ */
+export function buildSkillPrompt(skillIds, charBudget = 16000) {
+  if (!skillIds || skillIds.length === 0) return null;
+
+  const skills = loadAllSkills();
+  const sections = [];
+
+  for (const id of skillIds) {
+    const skill = skills.get(id);
+    if (!skill) continue;
+    sections.push(`### Skill: ${skill.emoji} ${skill.name}\n${skill.body}`);
+  }
+
+  if (sections.length === 0) return null;
+
+  let combined = sections.join('\n\n');
+
+  // Truncate from end if over budget
+  if (combined.length > charBudget) {
+    combined = combined.slice(0, charBudget) + '\n\n[...truncated due to token budget]';
+  }
+
+  return combined;
+}
+
+/**
+ * Filter skill IDs by worker affinity.
+ * Skills with null worker_affinity pass through (available to all workers).
+ * @param {string[]} skillIds - All active skill IDs
+ * @param {string} workerType - The worker type (coding, browser, system, etc.)
+ * @returns {string[]} Filtered skill IDs
+ */
+export function filterSkillsForWorker(skillIds, workerType) {
+  if (!skillIds || skillIds.length === 0) return [];
+
+  const skills = loadAllSkills();
+  return skillIds.filter(id => {
+    const skill = skills.get(id);
+    if (!skill) return false;
+    // null affinity = available to all workers
+    if (!skill.worker_affinity) return true;
+    return skill.worker_affinity.includes(workerType);
+  });
+}
+
+/**
+ * Save a custom skill as a .md file.
+ * @param {{ name: string, emoji?: string, category?: string, body: string, description?: string }} opts
+ * @returns {object} The saved skill object
+ */
+export function saveCustomSkill({ name, emoji, category, body, description }) {
+  mkdirSync(CUSTOM_DIR, { recursive: true });
+
+  const slug = name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+  let id = `custom_${slug}`;
+
+  // Check for collision
+  const existing = loadAllSkills();
+  if (existing.has(id)) {
+    let n = 2;
+    while (existing.has(`${id}-${n}`)) n++;
+    id = `${id}-${n}`;
+  }
+
+  const frontmatter = {
+    id,
+    name,
+    emoji: emoji || '🛠️',
+    category: category || 'custom',
+    description: description || `Custom skill: ${name}`,
+  };
+
+  const yamlStr = yaml.dump(frontmatter, { lineWidth: -1 }).trim();
+  const content = `---\n${yamlStr}\n---\n\n${body}`;
+
+  const filePath = join(CUSTOM_DIR, `${id}.md`);
+  writeFileSync(filePath, content, 'utf-8');
+
+  // Invalidate cache
+  skillCache = null;
+
+  return loadSkillFile(filePath);
+}
+
+/**
+ * Delete a custom skill by ID.
+ * @returns {boolean} true if found and deleted
+ */
+export function deleteCustomSkill(id) {
+  const skill = getSkillById(id);
+  if (!skill || !skill.isCustom) return false;
+
+  try {
+    unlinkSync(skill.filePath);
+    skillCache = null; // invalidate cache
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/** Get all custom skills. */
+export function getCustomSkills() {
+  const skills = loadAllSkills();
+  return [...skills.values()].filter(s => s.isCustom);
+}
+
+/**
+ * Migrate old custom_skills.json to .md files.
+ * Called once on startup if the old file exists.
+ */
+export function migrateOldCustomSkills() {
+  const oldFile = join(homedir(), '.kernelbot', 'custom_skills.json');
+  if (!existsSync(oldFile)) return;
+
+  const logger = getLogger();
+  try {
+    const raw = readFileSync(oldFile, 'utf-8');
+    const oldSkills = JSON.parse(raw);
+    if (!Array.isArray(oldSkills) || oldSkills.length === 0) return;
+
+    mkdirSync(CUSTOM_DIR, { recursive: true });
+    let migrated = 0;
+
+    for (const old of oldSkills) {
+      if (!old.name || !old.systemPrompt) continue;
+
+      const slug = old.id || old.name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
+      const id = slug.startsWith('custom_') ? slug : `custom_${slug}`;
+      const filePath = join(CUSTOM_DIR, `${id}.md`);
+
+      // Don't overwrite if already migrated
+      if (existsSync(filePath)) continue;
+
+      const frontmatter = {
+        id,
+        name: old.name,
+        emoji: old.emoji || '🛠️',
+        category: 'custom',
+        description: old.description || `Custom skill: ${old.name}`,
+      };
+
+      const yamlStr = yaml.dump(frontmatter, { lineWidth: -1 }).trim();
+      const content = `---\n${yamlStr}\n---\n\n${old.systemPrompt}`;
+      writeFileSync(filePath, content, 'utf-8');
+      migrated++;
+    }
+
+    if (migrated > 0) {
+      logger.info(`Migrated ${migrated} custom skills from JSON to .md files`);
+    }
+
+    // Rename old file to mark as migrated
+    renameSync(oldFile, oldFile + '.bak');
+    logger.info('Renamed custom_skills.json to custom_skills.json.bak');
+  } catch (err) {
+    logger.warn(`Failed to migrate old custom skills: ${err.message}`);
+  }
+}
+
+// ── Backward-compatible aliases ──────────────────────────────────────────
+// These maintain the same API surface that custom.js exported,
+// so existing imports keep working during the transition.
+
+/** Unified skill lookup (same as getSkillById — customs already override). */
+export const getUnifiedSkillById = getSkillById;
+
+/** Unified category list (same as getCategoryList — already includes custom). */
+export const getUnifiedCategoryList = getCategoryList;
+
+/** Unified skills by category (same as getSkillsByCategory). */
+export const getUnifiedSkillsByCategory = getSkillsByCategory;
+
+/** Backward-compat: load custom skills from disk (now a no-op, auto-loaded). */
+export function loadCustomSkills() {
+  loadAllSkills();
+}
+
+/**
+ * Backward-compat: add a custom skill.
+ * @param {{ name: string, systemPrompt: string, description?: string }} opts
+ */
+export function addCustomSkill({ name, systemPrompt, description }) {
+  return saveCustomSkill({ name, body: systemPrompt, description });
+}

package/src/swarm/worker-registry.js

@@ -24,7 +24,7 @@ export const WORKER_TYPES = {
     emoji: '🖥️',
     categories: ['core', 'process', 'monitor', 'network'],
     description: 'OS operations, monitoring, network',
-    timeout: 600,    // 10 minutes
+    timeout: 86400,  // 24 hours
   },
   devops: {
     label: 'DevOps Worker',
@@ -38,7 +38,7 @@ export const WORKER_TYPES = {
     emoji: '🔍',
     categories: ['browser', 'core'],
     description: 'Deep web research and analysis',
-    timeout: 600,    // 10 minutes
+    timeout: 86400,  // 24 hours
   },
   social: {
     label: 'Social Worker',

package/src/tools/browser.js

@@ -665,9 +665,16 @@ async function handleInteract(params, context) {
 
   for (const action of params.actions) {
     if (action.type === 'evaluate' && action.script) {
-      const blocked = /fetch\s*\(|XMLHttpRequest|window\.location\s*=|document\.cookie|localStorage|sessionStorage/i;
-      if (blocked.test(action.script)) {
-        return { error: 'Script contains blocked patterns (network requests, cookie access, storage access, or redirects)' };
+      // Block dangerous APIs using both direct access and bracket notation bypass patterns
+      const blocked = /fetch\s*\(|XMLHttpRequest|document\.cookie|localStorage|sessionStorage/i;
+      // Also detect bracket notation bypasses like window['location'], globalThis['fetch']
+      const bracketBypass = /\[\s*['"`](location|cookie|fetch|XMLHttpRequest|localStorage|sessionStorage|eval|Function)['"`]\s*\]/i;
+      // Block window.location assignment (direct or bracket)
+      const locationAssign = /window\s*(\.\s*location\s*=|\[\s*['"`]location['"`]\s*\]\s*=)/i;
+      // Block eval and Function constructor
+      const evalPattern = /\beval\s*\(|\bnew\s+Function\s*\(/i;
+      if (blocked.test(action.script) || bracketBypass.test(action.script) || locationAssign.test(action.script) || evalPattern.test(action.script)) {
+        return { error: 'Script contains blocked patterns (network requests, cookie access, storage access, eval, or redirects)' };
       }
     }
   }

package/src/tools/coding.js

@@ -34,6 +34,10 @@ export const definitions = [
           type: 'number',
           description: 'Max turns for Claude Code (optional, default from config)',
         },
+        timeout_seconds: {
+          type: 'number',
+          description: 'Override timeout in seconds for this invocation (optional, default from config)',
+        },
       },
       required: ['working_directory', 'prompt'],
     },
@@ -46,6 +50,17 @@ export const handlers = {
     const onUpdate = context.onUpdate || null;
     const dir = resolve(params.working_directory);
 
+    // Validate working_directory against blocked paths
+    const blockedPaths = context.config?.security?.blocked_paths || [];
+    for (const bp of blockedPaths) {
+      const expandedBp = resolve(bp.startsWith('~') ? bp.replace('~', process.env.HOME || '') : bp);
+      if (dir.startsWith(expandedBp) || dir === expandedBp) {
+        const msg = `Blocked: working directory is within restricted path ${bp}`;
+        logger.warn(`spawn_claude_code: ${msg}`);
+        return { error: msg };
+      }
+    }
+
     // Validate directory exists
     if (!existsSync(dir)) {
       const msg = `Directory not found: ${dir}`;
@@ -60,6 +75,7 @@ export const handlers = {
         workingDirectory: dir,
         prompt: params.prompt,
         maxTurns: params.max_turns,
+        timeoutMs: params.timeout_seconds ? params.timeout_seconds * 1000 : undefined,
         onOutput: onUpdate,
         signal: context.signal || null,
       });

package/src/tools/docker.js

@@ -94,6 +94,19 @@ export const handlers = {
   docker_compose: async (params) => {
     const logger = getLogger();
     const dir = params.project_dir ? `-f ${shellEscape(params.project_dir + '/docker-compose.yml')}` : '';
+
+    // Sanitize action: only allow known compose subcommands and safe flags
+    const ALLOWED_ACTIONS = ['up', 'down', 'build', 'logs', 'ps', 'restart', 'stop', 'start', 'pull', 'config', 'exec', 'run', 'top', 'images'];
+    const actionParts = params.action.trim().split(/\s+/);
+    const subcommand = actionParts[0];
+    if (!ALLOWED_ACTIONS.includes(subcommand)) {
+      return { error: `Invalid compose action: "${subcommand}". Allowed: ${ALLOWED_ACTIONS.join(', ')}` };
+    }
+    // Reject shell metacharacters in the action string to prevent injection
+    if (/[;&|`$(){}]/.test(params.action)) {
+      return { error: 'Invalid characters in compose action' };
+    }
+
     logger.debug(`docker_compose: ${params.action}`);
     const result = await run(`docker compose ${dir} ${params.action}`, 120000);
     if (result.error) logger.error(`docker_compose '${params.action}' failed: ${result.error}`);