agileflow 2.88.0 → 2.89.1

package/scripts/precompact-context.sh

@@ -121,3 +121,17 @@ cat << EOF
 3. Review docs/02-practices/ for implementation patterns
 4. Check git log for recent changes
 EOF
+
+# Mark that PreCompact just ran - tells SessionStart to preserve active_commands
+# This prevents the welcome script from clearing commands right after compact
+if [ -f "docs/09-agents/session-state.json" ]; then
+  node -e "
+    const fs = require('fs');
+    const path = 'docs/09-agents/session-state.json';
+    try {
+      const state = JSON.parse(fs.readFileSync(path, 'utf8'));
+      state.last_precompact_at = new Date().toISOString();
+      fs.writeFileSync(path, JSON.stringify(state, null, 2) + '\n');
+    } catch (e) {}
+  " 2>/dev/null
+fi

package/scripts/session-manager.js

@@ -228,9 +228,8 @@ function registerSession(nickname = null, threadType = null) {
   registry.next_id++;
 
   const isMain = cwd === ROOT;
-  const detectedType = threadType && THREAD_TYPES.includes(threadType)
-    ? threadType
-    : detectThreadType(null, !isMain);
+  const detectedType =
+    threadType && THREAD_TYPES.includes(threadType) ? threadType : detectThreadType(null, !isMain);
 
   registry.sessions[sessionId] = {
     path: cwd,
@@ -750,10 +749,10 @@ function getSessionPhase(session) {
 
     // Count commits since branch diverged from main
     const mainBranch = getMainBranch();
-    const commitCount = execSync(
-      `git rev-list --count ${mainBranch}..HEAD 2>/dev/null || echo 0`,
-      { cwd: sessionPath, encoding: 'utf8' }
-    ).trim();
+    const commitCount = execSync(`git rev-list --count ${mainBranch}..HEAD 2>/dev/null || echo 0`, {
+      cwd: sessionPath,
+      encoding: 'utf8',
+    }).trim();
 
     const commits = parseInt(commitCount, 10);
 
@@ -1037,7 +1036,9 @@ function main() {
         if (nickname) registry.sessions[sessionId].nickname = nickname;
         // Ensure thread_type exists (migration for old sessions)
         if (!registry.sessions[sessionId].thread_type) {
-          registry.sessions[sessionId].thread_type = registry.sessions[sessionId].is_main ? 'base' : 'parallel';
+          registry.sessions[sessionId].thread_type = registry.sessions[sessionId].is_main
+            ? 'base'
+            : 'parallel';
         }
         writeLock(sessionId, pid);
       } else {
@@ -1218,7 +1219,9 @@ function main() {
         const sessionId = args[2];
         const threadType = args[3];
         if (!sessionId || !threadType) {
-          console.log(JSON.stringify({ success: false, error: 'Usage: thread-type set <sessionId> <type>' }));
+          console.log(
+            JSON.stringify({ success: false, error: 'Usage: thread-type set <sessionId> <type>' })
+          );
           return;
         }
         const result = setSessionThreadType(sessionId, threadType);
@@ -1910,7 +1913,10 @@ function getSessionThreadType(sessionId = null) {
  */
 function setSessionThreadType(sessionId, threadType) {
   if (!THREAD_TYPES.includes(threadType)) {
-    return { success: false, error: `Invalid thread type: ${threadType}. Valid: ${THREAD_TYPES.join(', ')}` };
+    return {
+      success: false,
+      error: `Invalid thread type: ${threadType}. Valid: ${THREAD_TYPES.join(', ')}`,
+    };
   }
 
   const registry = loadRegistry();

package/scripts/test-session-boundary.js

@@ -63,8 +63,8 @@ console.log(`File Being Edited:   ${normalizedFile}`);
 console.log('');
 
 // Check if file is within active session path
-const isInsideSession = normalizedFile.startsWith(normalizedActive + path.sep) ||
-                        normalizedFile === normalizedActive;
+const isInsideSession =
+  normalizedFile.startsWith(normalizedActive + path.sep) || normalizedFile === normalizedActive;
 
 if (isInsideSession) {
   console.log('✅ ALLOWED - File is inside the active session directory');

package/tools/cli/commands/config.js

@@ -130,11 +130,7 @@ async function handleGet(status, key) {
   const handler = new ErrorHandler('config');
 
   if (!key) {
-    handler.warning(
-      'Missing key',
-      'Provide a config key to get',
-      'npx agileflow config get <key>'
-    );
+    handler.warning('Missing key', 'Provide a config key to get', 'npx agileflow config get <key>');
   }
 
   const validKeys = ['userName', 'ides', 'agileflowFolder', 'docsFolder', 'version'];

package/tools/cli/commands/setup.js

@@ -103,11 +103,7 @@ module.exports = {
 
       if (!coreResult.success) {
         const handler = new ErrorHandler('setup');
-        handler.warning(
-          'Core setup failed',
-          'Check directory permissions',
-          'npx agileflow doctor'
-        );
+        handler.warning('Core setup failed', 'Check directory permissions', 'npx agileflow doctor');
       }
 
       success(`Installed ${coreResult.counts.agents} agents`);

package/tools/cli/installers/core/installer.js

@@ -11,6 +11,7 @@ const ora = require('ora');
 const yaml = require('js-yaml');
 const { injectContent } = require('../../lib/content-injector');
 const { sha256Hex, toPosixPath, safeTimestampForPath } = require('../../lib/utils');
+const { validatePath, PathValidationError } = require('../../../../lib/validate');
 
 const TEXT_EXTENSIONS = new Set(['.md', '.yaml', '.yml', '.txt', '.json']);
 
@@ -191,6 +192,22 @@ class Installer {
     }
   }
 
+  /**
+   * Validate that a path is within the allowed installation directory.
+   * Prevents path traversal attacks when writing files.
+   *
+   * @param {string} filePath - Path to validate
+   * @param {string} baseDir - Allowed base directory
+   * @throws {PathValidationError} If path escapes base directory
+   */
+  validateInstallPath(filePath, baseDir) {
+    const result = validatePath(filePath, baseDir, { allowSymlinks: false });
+    if (!result.ok) {
+      throw result.error;
+    }
+    return result.resolvedPath;
+  }
+
   /**
    * Copy content from source to destination with placeholder replacement
    * @param {string} source - Source directory
@@ -201,10 +218,16 @@ class Installer {
   async copyContent(source, dest, agileflowFolder, policy = null) {
     const entries = await fs.readdir(source, { withFileTypes: true });
 
+    // Get base directory for validation (agileflowDir from policy or dest itself)
+    const baseDir = policy?.agileflowDir || dest;
+
     for (const entry of entries) {
       const srcPath = path.join(source, entry.name);
       const destPath = path.join(dest, entry.name);
 
+      // Validate destination path to prevent traversal attacks via malicious filenames
+      this.validateInstallPath(destPath, baseDir);
+
       if (entry.isDirectory()) {
         await fs.ensureDir(destPath);
         await this.copyContent(srcPath, destPath, agileflowFolder, policy);
@@ -688,18 +711,25 @@ class Installer {
    * @param {string} srcDir - Source directory
    * @param {string} destDir - Destination directory
    * @param {boolean} force - Overwrite existing files
+   * @param {string} [baseDir] - Base directory for path validation (defaults to destDir on first call)
    */
-  async copyScriptsRecursive(srcDir, destDir, force) {
+  async copyScriptsRecursive(srcDir, destDir, force, baseDir = null) {
     const entries = await fs.readdir(srcDir, { withFileTypes: true });
 
+    // Use destDir as base for validation on first call
+    const validationBase = baseDir || destDir;
+
     for (const entry of entries) {
       const srcPath = path.join(srcDir, entry.name);
       const destPath = path.join(destDir, entry.name);
 
+      // Validate destination path to prevent traversal via malicious filenames
+      this.validateInstallPath(destPath, validationBase);
+
       if (entry.isDirectory()) {
         // Recursively copy subdirectories
         await fs.ensureDir(destPath);
-        await this.copyScriptsRecursive(srcPath, destPath, force);
+        await this.copyScriptsRecursive(srcPath, destPath, force, validationBase);
       } else {
         // Copy file
         const destExists = await fs.pathExists(destPath);

package/tools/cli/installers/ide/_base-ide.js

@@ -7,6 +7,14 @@
 const path = require('node:path');
 const fs = require('fs-extra');
 const chalk = require('chalk');
+const {
+  IdeConfigNotFoundError,
+  CommandInstallationError,
+  FilePermissionError,
+  CleanupError,
+  ContentInjectionError,
+  withPermissionHandling,
+} = require('../../lib/ide-errors');
 
 /**
  * Base class for IDE-specific setup
@@ -99,9 +107,74 @@ class BaseIdeSetup {
     throw new Error(`setup() must be implemented by ${this.name} handler`);
   }
 
+  /**
+   * Standard setup flow shared by most IDE installers.
+   * Handles cleanup, command/agent installation, and logging.
+   *
+   * @param {string} projectDir - Project directory
+   * @param {string} agileflowDir - AgileFlow installation directory
+   * @param {Object} config - Configuration options
+   * @param {string} config.targetSubdir - Target subdirectory name under configDir (e.g., 'commands', 'workflows')
+   * @param {string} config.agileflowFolder - AgileFlow folder name (e.g., 'agileflow', 'AgileFlow')
+   * @param {string} [config.commandLabel='commands'] - Label for commands in output (e.g., 'workflows')
+   * @param {string} [config.agentLabel='agents'] - Label for agents in output
+   * @returns {Promise<{success: boolean, commands: number, agents: number}>}
+   */
+  async setupStandard(projectDir, agileflowDir, config) {
+    const {
+      targetSubdir,
+      agileflowFolder,
+      commandLabel = 'commands',
+      agentLabel = 'agents',
+    } = config;
+
+    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
+
+    // Clean up old installation first
+    await this.cleanup(projectDir);
+
+    // Create target directory (e.g., .cursor/commands/AgileFlow)
+    const ideDir = path.join(projectDir, this.configDir);
+    const targetDir = path.join(ideDir, targetSubdir);
+    const agileflowTargetDir = path.join(targetDir, agileflowFolder);
+
+    // Install commands using shared recursive method
+    const commandsSource = path.join(agileflowDir, 'commands');
+    const commandResult = await this.installCommandsRecursive(
+      commandsSource,
+      agileflowTargetDir,
+      agileflowDir,
+      true // Inject dynamic content
+    );
+
+    // Install agents as subdirectory
+    const agentsSource = path.join(agileflowDir, 'agents');
+    const agentsTargetDir = path.join(agileflowTargetDir, 'agents');
+    const agentResult = await this.installCommandsRecursive(
+      agentsSource,
+      agentsTargetDir,
+      agileflowDir,
+      false // No dynamic content for agents
+    );
+
+    console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
+    console.log(chalk.dim(`    - ${commandResult.commands} ${commandLabel} installed`));
+    console.log(chalk.dim(`    - ${agentResult.commands} ${agentLabel} installed`));
+    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowTargetDir)}`));
+
+    return {
+      success: true,
+      commands: commandResult.commands,
+      agents: agentResult.commands,
+      ideDir,
+      agileflowTargetDir,
+    };
+  }
+
   /**
    * Cleanup IDE configuration
    * @param {string} projectDir - Project directory
+   * @throws {CleanupError} If cleanup fails
    */
   async cleanup(projectDir) {
     if (this.configDir) {
@@ -109,10 +182,21 @@ class BaseIdeSetup {
       for (const folderName of ['agileflow', 'AgileFlow']) {
         const agileflowPath = path.join(projectDir, this.configDir, 'commands', folderName);
         if (await fs.pathExists(agileflowPath)) {
-          await fs.remove(agileflowPath);
-          console.log(
-            chalk.dim(`  Removed old ${folderName} configuration from ${this.displayName}`)
-          );
+          try {
+            await fs.remove(agileflowPath);
+            console.log(
+              chalk.dim(`  Removed old ${folderName} configuration from ${this.displayName}`)
+            );
+          } catch (error) {
+            if (error.code === 'EACCES' || error.code === 'EPERM') {
+              throw new CleanupError(
+                this.displayName,
+                agileflowPath,
+                `Permission denied: ${error.message}`
+              );
+            }
+            throw new CleanupError(this.displayName, agileflowPath, error.message);
+          }
         }
       }
     }
@@ -140,21 +224,27 @@ class BaseIdeSetup {
   }
 
   /**
-   * Write a file
+   * Write a file with permission error handling
    * @param {string} filePath - File path
    * @param {string} content - File content
+   * @throws {FilePermissionError} If permission denied
    */
   async writeFile(filePath, content) {
-    await fs.writeFile(filePath, content, 'utf8');
+    await withPermissionHandling(this.displayName, filePath, 'write', async () => {
+      await fs.writeFile(filePath, content, 'utf8');
+    });
   }
 
   /**
-   * Read a file
+   * Read a file with permission error handling
    * @param {string} filePath - File path
    * @returns {Promise<string>} File content
+   * @throws {FilePermissionError} If permission denied
    */
   async readFile(filePath) {
-    return fs.readFile(filePath, 'utf8');
+    return withPermissionHandling(this.displayName, filePath, 'read', async () => {
+      return fs.readFile(filePath, 'utf8');
+    });
   }
 
   /**
@@ -202,6 +292,8 @@ class BaseIdeSetup {
    * @param {string} agileflowDir - AgileFlow installation directory (for dynamic content)
    * @param {boolean} injectDynamic - Whether to inject dynamic content (only for top-level commands)
    * @returns {Promise<{commands: number, subdirs: number}>} Count of installed items
+   * @throws {CommandInstallationError} If command installation fails
+   * @throws {FilePermissionError} If permission denied
    */
   async installCommandsRecursive(sourceDir, targetDir, agileflowDir, injectDynamic = false) {
     let commandCount = 0;
@@ -211,7 +303,14 @@ class BaseIdeSetup {
       return { commands: 0, subdirs: 0 };
     }
 
-    await this.ensureDir(targetDir);
+    try {
+      await this.ensureDir(targetDir);
+    } catch (error) {
+      if (error.code === 'EACCES' || error.code === 'EPERM') {
+        throw new FilePermissionError(this.displayName, targetDir, 'write');
+      }
+      throw error;
+    }
 
     const entries = await fs.readdir(sourceDir, { withFileTypes: true });
 
@@ -220,19 +319,34 @@ class BaseIdeSetup {
       const targetPath = path.join(targetDir, entry.name);
 
       if (entry.isFile() && entry.name.endsWith('.md')) {
-        // Read and process .md file
-        let content = await this.readFile(sourcePath);
+        try {
+          // Read and process .md file
+          let content = await this.readFile(sourcePath);
 
-        // Inject dynamic content if enabled (for top-level commands)
-        if (injectDynamic) {
-          content = this.injectDynamicContent(content, agileflowDir);
-        }
+          // Inject dynamic content if enabled (for top-level commands)
+          if (injectDynamic) {
+            try {
+              content = this.injectDynamicContent(content, agileflowDir);
+            } catch (injectionError) {
+              throw new ContentInjectionError(this.displayName, sourcePath, injectionError.message);
+            }
+          }
 
-        // Replace docs/ references with custom folder name
-        content = this.replaceDocsReferences(content);
+          // Replace docs/ references with custom folder name
+          content = this.replaceDocsReferences(content);
 
-        await this.writeFile(targetPath, content);
-        commandCount++;
+          await this.writeFile(targetPath, content);
+          commandCount++;
+        } catch (error) {
+          // Re-throw typed errors as-is
+          if (error.name && error.name.includes('Error') && error.ideName) {
+            throw error;
+          }
+          throw new CommandInstallationError(this.displayName, entry.name, error.message, {
+            sourcePath,
+            targetPath,
+          });
+        }
       } else if (entry.isDirectory()) {
         // Recursively process subdirectory
         const subResult = await this.installCommandsRecursive(

package/tools/cli/installers/ide/claude-code.js

@@ -26,68 +26,31 @@ class ClaudeCodeSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
+    // Use standard setup for commands and agents
+    const result = await this.setupStandard(projectDir, agileflowDir, {
+      targetSubdir: this.commandsDir,
+      agileflowFolder: 'agileflow',
+    });
 
-    // Clean up old installation first
-    await this.cleanup(projectDir);
-
-    // Create .claude/commands/agileflow directory
-    const claudeDir = path.join(projectDir, this.configDir);
-    const commandsDir = path.join(claudeDir, this.commandsDir);
-    const agileflowCommandsDir = path.join(commandsDir, 'agileflow');
-
-    await this.ensureDir(agileflowCommandsDir);
-
-    // Recursively install all commands (including subdirectories like agents/, session/)
-    const commandsSource = path.join(agileflowDir, 'commands');
-    const commandResult = await this.installCommandsRecursive(
-      commandsSource,
-      agileflowCommandsDir,
-      agileflowDir,
-      true // Inject dynamic content for top-level commands
-    );
-
-    // Also install agents as slash commands (.claude/commands/agileflow/agents/)
+    const { ideDir, agileflowTargetDir } = result;
     const agentsSource = path.join(agileflowDir, 'agents');
-    const agentsTargetDir = path.join(agileflowCommandsDir, 'agents');
-    const agentResult = await this.installCommandsRecursive(
-      agentsSource,
-      agentsTargetDir,
-      agileflowDir,
-      false // No dynamic content for agents
-    );
-
-    // ALSO install agents as spawnable subagents (.claude/agents/agileflow/)
+
+    // Claude Code specific: Install agents as spawnable subagents (.claude/agents/agileflow/)
     // This allows Task tool to spawn them with subagent_type: "agileflow-ui"
-    const spawnableAgentsDir = path.join(claudeDir, 'agents', 'agileflow');
+    const spawnableAgentsDir = path.join(ideDir, 'agents', 'agileflow');
     await this.installCommandsRecursive(agentsSource, spawnableAgentsDir, agileflowDir, false);
     console.log(chalk.dim(`    - Spawnable agents: .claude/agents/agileflow/`));
 
-    // Create skills directory for user-generated skills (.claude/skills/)
+    // Claude Code specific: Create skills directory for user-generated skills
     // AgileFlow no longer ships static skills - users generate them via /agileflow:skill:create
-    const skillsTargetDir = path.join(claudeDir, 'skills');
+    const skillsTargetDir = path.join(ideDir, 'skills');
     await this.ensureDir(skillsTargetDir);
     console.log(chalk.dim(`    - Skills directory: .claude/skills/ (for user-generated skills)`));
 
-    // Setup damage control hooks
-    await this.setupDamageControl(projectDir, agileflowDir, claudeDir, options);
-
-    const totalCommands = commandResult.commands + agentResult.commands;
-    const totalSubdirs =
-      commandResult.subdirs + (agentResult.commands > 0 ? 1 : 0) + agentResult.subdirs;
-
-    console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${totalCommands} commands installed`));
-    if (totalSubdirs > 0) {
-      console.log(chalk.dim(`    - ${totalSubdirs} subdirectories`));
-    }
-    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowCommandsDir)}`));
+    // Claude Code specific: Setup damage control hooks
+    await this.setupDamageControl(projectDir, agileflowDir, ideDir, options);
 
-    return {
-      success: true,
-      commands: totalCommands,
-      subdirs: totalSubdirs,
-    };
+    return result;
   }
 
   /**

package/tools/cli/installers/ide/cursor.js

@@ -27,45 +27,10 @@ class CursorSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
-
-    // Clean up old installation first
-    await this.cleanup(projectDir);
-
-    // Create .cursor/commands/AgileFlow directory
-    const cursorDir = path.join(projectDir, this.configDir);
-    const commandsDir = path.join(cursorDir, this.commandsDir);
-    const agileflowCommandsDir = path.join(commandsDir, 'AgileFlow');
-
-    // Install commands using shared recursive method
-    const commandsSource = path.join(agileflowDir, 'commands');
-    const commandResult = await this.installCommandsRecursive(
-      commandsSource,
-      agileflowCommandsDir,
-      agileflowDir,
-      true // Inject dynamic content
-    );
-
-    // Install agents as subdirectory
-    const agentsSource = path.join(agileflowDir, 'agents');
-    const agentsTargetDir = path.join(agileflowCommandsDir, 'agents');
-    const agentResult = await this.installCommandsRecursive(
-      agentsSource,
-      agentsTargetDir,
-      agileflowDir,
-      false // No dynamic content for agents
-    );
-
-    console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${commandResult.commands} commands installed`));
-    console.log(chalk.dim(`    - ${agentResult.commands} agents installed`));
-    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowCommandsDir)}`));
-
-    return {
-      success: true,
-      commands: commandResult.commands,
-      agents: agentResult.commands,
-    };
+    return this.setupStandard(projectDir, agileflowDir, {
+      targetSubdir: this.commandsDir,
+      agileflowFolder: 'AgileFlow',
+    });
   }
 
   /**

package/tools/cli/installers/ide/windsurf.js

@@ -27,45 +27,12 @@ class WindsurfSetup extends BaseIdeSetup {
    * @param {Object} options - Setup options
    */
   async setup(projectDir, agileflowDir, options = {}) {
-    console.log(chalk.hex('#e8683a')(`  Setting up ${this.displayName}...`));
-
-    // Clean up old installation first
-    await this.cleanup(projectDir);
-
-    // Create .windsurf/workflows/agileflow directory
-    const windsurfDir = path.join(projectDir, this.configDir);
-    const workflowsDir = path.join(windsurfDir, this.workflowsDir);
-    const agileflowWorkflowsDir = path.join(workflowsDir, 'agileflow');
-
-    // Install commands using shared recursive method
-    const commandsSource = path.join(agileflowDir, 'commands');
-    const commandResult = await this.installCommandsRecursive(
-      commandsSource,
-      agileflowWorkflowsDir,
-      agileflowDir,
-      true // Inject dynamic content
-    );
-
-    // Install agents as subdirectory
-    const agentsSource = path.join(agileflowDir, 'agents');
-    const agentsTargetDir = path.join(agileflowWorkflowsDir, 'agents');
-    const agentResult = await this.installCommandsRecursive(
-      agentsSource,
-      agentsTargetDir,
-      agileflowDir,
-      false // No dynamic content for agents
-    );
-
-    console.log(chalk.green(`  ✓ ${this.displayName} configured:`));
-    console.log(chalk.dim(`    - ${commandResult.commands} workflows installed`));
-    console.log(chalk.dim(`    - ${agentResult.commands} agent workflows installed`));
-    console.log(chalk.dim(`    - Path: ${path.relative(projectDir, agileflowWorkflowsDir)}`));
-
-    return {
-      success: true,
-      commands: commandResult.commands,
-      agents: agentResult.commands,
-    };
+    return this.setupStandard(projectDir, agileflowDir, {
+      targetSubdir: this.workflowsDir,
+      agileflowFolder: 'agileflow',
+      commandLabel: 'workflows',
+      agentLabel: 'agent workflows',
+    });
   }
 
   /**

package/tools/cli/lib/content-injector.js

@@ -26,6 +26,7 @@ const path = require('path');
 
 // Use shared modules
 const { parseFrontmatter, normalizeTools } = require('../../../scripts/lib/frontmatter-parser');
+const { validatePath } = require('../../../lib/validate');
 const {
   countCommands,
   countAgents,
@@ -37,6 +38,18 @@ const {
 // List Generation Functions
 // =============================================================================
 
+/**
+ * Validate that a file path is within the expected directory.
+ * Prevents reading files outside the expected scope.
+ * @param {string} filePath - File path to validate
+ * @param {string} baseDir - Expected base directory
+ * @returns {boolean} True if path is safe
+ */
+function isPathSafe(filePath, baseDir) {
+  const result = validatePath(filePath, baseDir, { allowSymlinks: true });
+  return result.ok;
+}
+
 /**
  * Scan agents directory and generate formatted agent list
  * @param {string} agentsDir - Path to agents directory
@@ -50,6 +63,12 @@ function generateAgentList(agentsDir) {
 
   for (const file of files) {
     const filePath = path.join(agentsDir, file);
+
+    // Validate path before reading to prevent traversal via symlinks or malicious names
+    if (!isPathSafe(filePath, agentsDir)) {
+      continue;
+    }
+
     const content = fs.readFileSync(filePath, 'utf8');
     const frontmatter = parseFrontmatter(content);
 
@@ -94,6 +113,12 @@ function generateCommandList(commandsDir) {
   const mainFiles = fs.readdirSync(commandsDir).filter(f => f.endsWith('.md'));
   for (const file of mainFiles) {
     const filePath = path.join(commandsDir, file);
+
+    // Validate path before reading
+    if (!isPathSafe(filePath, commandsDir)) {
+      continue;
+    }
+
     const content = fs.readFileSync(filePath, 'utf8');
     const frontmatter = parseFrontmatter(content);
     const cmdName = path.basename(file, '.md');
@@ -114,10 +139,22 @@ function generateCommandList(commandsDir) {
   for (const entry of entries) {
     if (entry.isDirectory()) {
       const subDir = path.join(commandsDir, entry.name);
+
+      // Validate subdirectory path
+      if (!isPathSafe(subDir, commandsDir)) {
+        continue;
+      }
+
       const subFiles = fs.readdirSync(subDir).filter(f => f.endsWith('.md'));
 
       for (const file of subFiles) {
         const filePath = path.join(subDir, file);
+
+        // Validate file path within subdirectory
+        if (!isPathSafe(filePath, commandsDir)) {
+          continue;
+        }
+
         const content = fs.readFileSync(filePath, 'utf8');
         const frontmatter = parseFrontmatter(content);
         const cmdName = `${entry.name}:${path.basename(file, '.md')}`;