agileflow 2.88.0 → 2.89.1

package/lib/validate.js

@@ -2,9 +2,12 @@
  * AgileFlow CLI - Input Validation Utilities
  *
  * Centralized validation patterns and helpers to prevent
- * command injection and invalid input handling.
+ * command injection, path traversal, and invalid input handling.
  */
 
+const path = require('node:path');
+const fs = require('node:fs');
+
 /**
  * Validation patterns for common input types.
  * All patterns use strict whitelisting approach.
@@ -320,7 +323,276 @@ function validateArgs(args, schema) {
   return { ok: true, data: result };
 }
 
+// =============================================================================
+// Path Traversal Protection
+// =============================================================================
+
+/**
+ * Path validation error with context.
+ */
+class PathValidationError extends Error {
+  /**
+   * @param {string} message - Error message
+   * @param {string} inputPath - The problematic path
+   * @param {string} reason - Reason for rejection
+   */
+  constructor(message, inputPath, reason) {
+    super(message);
+    this.name = 'PathValidationError';
+    this.inputPath = inputPath;
+    this.reason = reason;
+    Error.captureStackTrace(this, this.constructor);
+  }
+}
+
+/**
+ * Validate that a path is safe and within the allowed base directory.
+ * Prevents path traversal attacks by:
+ * 1. Resolving the path to absolute form
+ * 2. Ensuring it stays within the base directory
+ * 3. Rejecting symbolic links (optional)
+ *
+ * @param {string} inputPath - The path to validate (can be relative or absolute)
+ * @param {string} baseDir - The allowed base directory (must be absolute)
+ * @param {Object} options - Validation options
+ * @param {boolean} [options.allowSymlinks=false] - Allow symbolic links
+ * @param {boolean} [options.mustExist=false] - Path must exist on filesystem
+ * @returns {{ ok: boolean, resolvedPath?: string, error?: PathValidationError }}
+ *
+ * @example
+ * // Validate a file path within project directory
+ * const result = validatePath('./config.yaml', '/home/user/project');
+ * if (result.ok) {
+ *   console.log('Safe path:', result.resolvedPath);
+ * }
+ *
+ * @example
+ * // Reject path traversal attempt
+ * const result = validatePath('../../../etc/passwd', '/home/user/project');
+ * // result.ok === false
+ * // result.error.reason === 'path_traversal'
+ */
+function validatePath(inputPath, baseDir, options = {}) {
+  const { allowSymlinks = false, mustExist = false } = options;
+
+  // Input validation
+  if (!inputPath || typeof inputPath !== 'string') {
+    return {
+      ok: false,
+      error: new PathValidationError(
+        'Path is required and must be a string',
+        String(inputPath),
+        'invalid_input'
+      ),
+    };
+  }
+
+  if (!baseDir || typeof baseDir !== 'string') {
+    return {
+      ok: false,
+      error: new PathValidationError(
+        'Base directory is required and must be a string',
+        inputPath,
+        'invalid_base'
+      ),
+    };
+  }
+
+  // Base directory must be absolute
+  if (!path.isAbsolute(baseDir)) {
+    return {
+      ok: false,
+      error: new PathValidationError(
+        'Base directory must be an absolute path',
+        inputPath,
+        'relative_base'
+      ),
+    };
+  }
+
+  // Normalize the base directory
+  const normalizedBase = path.resolve(baseDir);
+
+  // Resolve the input path relative to base directory
+  let resolvedPath;
+  if (path.isAbsolute(inputPath)) {
+    resolvedPath = path.resolve(inputPath);
+  } else {
+    resolvedPath = path.resolve(normalizedBase, inputPath);
+  }
+
+  // Check for path traversal: resolved path must start with base directory
+  // Add trailing separator to prevent prefix attacks (e.g., /home/user vs /home/user2)
+  const baseWithSep = normalizedBase.endsWith(path.sep)
+    ? normalizedBase
+    : normalizedBase + path.sep;
+
+  const isWithinBase = resolvedPath === normalizedBase || resolvedPath.startsWith(baseWithSep);
+
+  if (!isWithinBase) {
+    return {
+      ok: false,
+      error: new PathValidationError(
+        `Path escapes base directory: ${inputPath}`,
+        inputPath,
+        'path_traversal'
+      ),
+    };
+  }
+
+  // Check if path exists (if required)
+  if (mustExist) {
+    try {
+      fs.accessSync(resolvedPath);
+    } catch {
+      return {
+        ok: false,
+        error: new PathValidationError(
+          `Path does not exist: ${resolvedPath}`,
+          inputPath,
+          'not_found'
+        ),
+      };
+    }
+  }
+
+  // Check for symbolic links (if not allowed)
+  if (!allowSymlinks) {
+    try {
+      const stats = fs.lstatSync(resolvedPath);
+      if (stats.isSymbolicLink()) {
+        return {
+          ok: false,
+          error: new PathValidationError(
+            `Symbolic links are not allowed: ${inputPath}`,
+            inputPath,
+            'symlink_rejected'
+          ),
+        };
+      }
+    } catch {
+      // Path doesn't exist yet, which is fine if mustExist is false
+      // Check parent directories for symlinks
+      const parts = path.relative(normalizedBase, resolvedPath).split(path.sep);
+      let currentPath = normalizedBase;
+
+      for (const part of parts) {
+        currentPath = path.join(currentPath, part);
+        try {
+          const stats = fs.lstatSync(currentPath);
+          if (stats.isSymbolicLink()) {
+            return {
+              ok: false,
+              error: new PathValidationError(
+                `Path contains symbolic link: ${currentPath}`,
+                inputPath,
+                'symlink_in_path'
+              ),
+            };
+          }
+        } catch {
+          // Part of path doesn't exist, stop checking
+          break;
+        }
+      }
+    }
+  }
+
+  return {
+    ok: true,
+    resolvedPath,
+  };
+}
+
+/**
+ * Synchronous version that throws on invalid paths.
+ * Use when you want exceptions rather than result objects.
+ *
+ * @param {string} inputPath - The path to validate
+ * @param {string} baseDir - The allowed base directory
+ * @param {Object} options - Validation options
+ * @returns {string} The validated absolute path
+ * @throws {PathValidationError} If path is invalid
+ */
+function validatePathSync(inputPath, baseDir, options = {}) {
+  const result = validatePath(inputPath, baseDir, options);
+  if (!result.ok) {
+    throw result.error;
+  }
+  return result.resolvedPath;
+}
+
+/**
+ * Check if a path contains dangerous patterns without resolving.
+ * Useful for quick pre-validation before expensive operations.
+ *
+ * @param {string} inputPath - The path to check
+ * @returns {{ safe: boolean, reason?: string }}
+ */
+function hasUnsafePathPatterns(inputPath) {
+  if (!inputPath || typeof inputPath !== 'string') {
+    return { safe: false, reason: 'invalid_input' };
+  }
+
+  // Check for null bytes (can bypass security in some systems)
+  if (inputPath.includes('\0')) {
+    return { safe: false, reason: 'null_byte' };
+  }
+
+  // Check for obvious traversal patterns
+  if (inputPath.includes('..')) {
+    return { safe: false, reason: 'dot_dot_sequence' };
+  }
+
+  // Check for absolute paths on Unix when expecting relative
+  if (inputPath.startsWith('/') && !path.isAbsolute(inputPath)) {
+    return { safe: false, reason: 'unexpected_absolute' };
+  }
+
+  // Check for Windows-style absolute paths
+  if (/^[a-zA-Z]:/.test(inputPath)) {
+    return { safe: false, reason: 'windows_absolute' };
+  }
+
+  return { safe: true };
+}
+
+/**
+ * Sanitize a filename by removing dangerous characters.
+ * Does NOT validate the full path - use with validatePath().
+ *
+ * @param {string} filename - The filename to sanitize
+ * @param {Object} options - Sanitization options
+ * @param {string} [options.replacement='_'] - Character to replace with
+ * @param {number} [options.maxLength=255] - Maximum filename length
+ * @returns {string} Sanitized filename
+ */
+function sanitizeFilename(filename, options = {}) {
+  const { replacement = '_', maxLength = 255 } = options;
+
+  if (!filename || typeof filename !== 'string') {
+    return '';
+  }
+
+  // Remove or replace dangerous characters
+  let sanitized = filename
+    .replace(/[<>:"/\\|?*\x00-\x1f]/g, replacement) // Control chars and reserved
+    .replace(/\.{2,}/g, replacement) // Multiple dots
+    .replace(/^\.+/, replacement) // Leading dots
+    .replace(/^-+/, replacement); // Leading dashes (prevent flag injection)
+
+  // Truncate if too long
+  if (sanitized.length > maxLength) {
+    const ext = path.extname(sanitized);
+    const base = path.basename(sanitized, ext);
+    sanitized = base.slice(0, maxLength - ext.length) + ext;
+  }
+
+  return sanitized;
+}
+
 module.exports = {
+  // Patterns and basic validators
   PATTERNS,
   isValidBranchName,
   isValidStoryId,
@@ -334,4 +606,11 @@ module.exports = {
   parseIntBounded,
   isValidOption,
   validateArgs,
+
+  // Path traversal protection
+  PathValidationError,
+  validatePath,
+  validatePathSync,
+  hasUnsafePathPatterns,
+  sanitizeFilename,
 };

package/lib/yaml-utils.js

@@ -0,0 +1,118 @@
+/**
+ * Centralized YAML parsing utilities with security guarantees.
+ *
+ * Security Note (js-yaml v4.x):
+ * - yaml.load() is SAFE by default in v4+ (unlike v3.x)
+ * - Dangerous JavaScript types (functions, regexps) are NOT supported
+ * - Only JSON-compatible types are parsed
+ * - See: https://github.com/nodeca/js-yaml/blob/master/migrate_v3_to_v4.md
+ *
+ * This wrapper provides:
+ * - Explicit security documentation
+ * - Input validation
+ * - Consistent error handling
+ * - Future-proofing for library changes
+ */
+
+const yaml = require('js-yaml');
+
+/**
+ * Safely parse YAML content. Uses js-yaml's DEFAULT_SCHEMA which is
+ * safe by default in v4+ (does not execute arbitrary JavaScript).
+ *
+ * @param {string} content - YAML string to parse
+ * @param {Object} options - Optional yaml.load options
+ * @returns {any} Parsed YAML content (object, array, or primitive)
+ * @throws {yaml.YAMLException} If YAML is malformed
+ */
+function safeLoad(content, options = {}) {
+  if (typeof content !== 'string') {
+    throw new TypeError('YAML content must be a string');
+  }
+
+  // In js-yaml v4+, load() uses DEFAULT_SCHEMA which is safe.
+  // Explicitly pass schema to make the security guarantee clear
+  // and protect against future library changes.
+  return yaml.load(content, {
+    schema: yaml.DEFAULT_SCHEMA,
+    ...options,
+  });
+}
+
+/**
+ * Safely parse all YAML documents in a multi-document file.
+ *
+ * @param {string} content - YAML string containing one or more documents
+ * @param {Object} options - Optional yaml.loadAll options
+ * @returns {any[]} Array of parsed YAML documents
+ * @throws {yaml.YAMLException} If YAML is malformed
+ */
+function safeLoadAll(content, options = {}) {
+  if (typeof content !== 'string') {
+    throw new TypeError('YAML content must be a string');
+  }
+
+  const documents = [];
+  yaml.loadAll(content, doc => documents.push(doc), { schema: yaml.DEFAULT_SCHEMA, ...options });
+  return documents;
+}
+
+/**
+ * Safely serialize data to YAML string.
+ *
+ * @param {any} data - Data to serialize
+ * @param {Object} options - Optional yaml.dump options
+ * @returns {string} YAML string representation
+ */
+function safeDump(data, options = {}) {
+  return yaml.dump(data, {
+    schema: yaml.DEFAULT_SCHEMA,
+    ...options,
+  });
+}
+
+/**
+ * Test if js-yaml is configured securely (no JavaScript type support).
+ * This function is used in security tests to verify the library version
+ * and configuration.
+ *
+ * @returns {boolean} True if the configuration is secure
+ */
+function isSecureConfiguration() {
+  // Attempt to parse YAML with JavaScript function syntax
+  // This should NOT execute any code in v4+
+  const maliciousYaml = `
+test: !!js/function 'function() { return "pwned"; }'
+regex: !!js/regexp /test/i
+undef: !!js/undefined ''
+`;
+
+  try {
+    const result = safeLoad(maliciousYaml);
+    // If we get here without executing code, and the values are
+    // either strings or undefined (not actual functions), we're safe
+    if (typeof result.test === 'function') {
+      return false; // Unsafe: function was instantiated
+    }
+    if (result.regex instanceof RegExp) {
+      return false; // Unsafe: regex was instantiated
+    }
+    // Values should be undefined or error out due to unknown tags
+    return true;
+  } catch (e) {
+    // YAMLException for unknown tags is the expected safe behavior
+    if (e.name === 'YAMLException') {
+      return true;
+    }
+    throw e;
+  }
+}
+
+module.exports = {
+  safeLoad,
+  safeLoadAll,
+  safeDump,
+  isSecureConfiguration,
+  // Re-export yaml module for edge cases that need direct access
+  yaml,
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "agileflow",
-  "version": "2.88.0",
+  "version": "2.89.1",
   "description": "AI-driven agile development system for Claude Code, Cursor, Windsurf, and more",
   "keywords": [
     "agile",

package/scripts/agileflow-welcome.js

@@ -18,6 +18,7 @@ const { execSync, spawnSync } = require('child_process');
 // Shared utilities
 const { c, box } = require('../lib/colors');
 const { getProjectRoot } = require('../lib/paths');
+const { readJSONCached, readFileCached } = require('../lib/file-cache');
 
 // Session manager path (relative to script location)
 const SESSION_MANAGER_PATH = path.join(__dirname, 'session-manager.js');
@@ -47,44 +48,29 @@ try {
 }
 
 /**
- * PERFORMANCE OPTIMIZATION: Load all project files once into cache
- * This eliminates duplicate file reads across multiple functions.
- * Estimated savings: 40-80ms
+ * PERFORMANCE OPTIMIZATION: Load all project files using LRU cache
+ * Uses file-cache module for automatic caching with 30s TTL.
+ * Files are cached across script invocations within TTL window.
+ * Estimated savings: 60-120ms on cache hits
  */
 function loadProjectFiles(rootDir) {
-  const cache = {
-    status: null,
-    metadata: null,
-    settings: null,
-    sessionState: null,
-    configYaml: null,
-    cliPackage: null,
-  };
-
   const paths = {
-    status: 'docs/09-agents/status.json',
-    metadata: 'docs/00-meta/agileflow-metadata.json',
-    settings: '.claude/settings.json',
-    sessionState: 'docs/09-agents/session-state.json',
-    configYaml: '.agileflow/config.yaml',
-    cliPackage: 'packages/cli/package.json',
+    status: path.join(rootDir, 'docs', '09-agents', 'status.json'),
+    metadata: path.join(rootDir, 'docs', '00-meta', 'agileflow-metadata.json'),
+    settings: path.join(rootDir, '.claude', 'settings.json'),
+    sessionState: path.join(rootDir, 'docs', '09-agents', 'session-state.json'),
+    configYaml: path.join(rootDir, '.agileflow', 'config.yaml'),
+    cliPackage: path.join(rootDir, 'packages', 'cli', 'package.json'),
   };
 
-  for (const [key, relPath] of Object.entries(paths)) {
-    const fullPath = path.join(rootDir, relPath);
-    try {
-      if (!fs.existsSync(fullPath)) continue;
-      if (key === 'configYaml') {
-        cache[key] = fs.readFileSync(fullPath, 'utf8');
-      } else {
-        cache[key] = JSON.parse(fs.readFileSync(fullPath, 'utf8'));
-      }
-    } catch (e) {
-      // Silently ignore - file not available or invalid
-    }
-  }
-
-  return cache;
+  return {
+    status: readJSONCached(paths.status),
+    metadata: readJSONCached(paths.metadata),
+    settings: readJSONCached(paths.settings),
+    sessionState: readJSONCached(paths.sessionState),
+    configYaml: readFileCached(paths.configYaml),
+    cliPackage: readJSONCached(paths.cliPackage),
+  };
 }
 
 /**
@@ -288,7 +274,7 @@ function runArchival(rootDir, cache = null) {
 }
 
 function clearActiveCommands(rootDir, cache = null) {
-  const result = { ran: false, cleared: 0, commandNames: [] };
+  const result = { ran: false, cleared: 0, commandNames: [], preserved: false };
 
   try {
     const sessionStatePath = path.join(rootDir, 'docs/09-agents/session-state.json');
@@ -305,6 +291,31 @@ function clearActiveCommands(rootDir, cache = null) {
       result.ran = true;
     }
 
+    // Check if PreCompact just ran (within last 30 seconds)
+    // If so, preserve active_commands instead of clearing them (post-compact session start)
+    if (state.last_precompact_at) {
+      const precompactTime = new Date(state.last_precompact_at).getTime();
+      const now = Date.now();
+      const secondsSincePrecompact = (now - precompactTime) / 1000;
+
+      if (secondsSincePrecompact < 30) {
+        // This is a post-compact session start - preserve active commands
+        result.preserved = true;
+        // Capture command names for display (but don't clear)
+        if (state.active_commands && state.active_commands.length > 0) {
+          for (const cmd of state.active_commands) {
+            if (cmd.name) result.commandNames.push(cmd.name);
+          }
+        }
+        // Clear the precompact timestamp so next true session start will clear
+        delete state.last_precompact_at;
+        fs.writeFileSync(sessionStatePath, JSON.stringify(state, null, 2) + '\n');
+        return result;
+      }
+      // Precompact was too long ago - clear as normal
+      delete state.last_precompact_at;
+    }
+
     // Handle new array format (active_commands)
     if (state.active_commands && state.active_commands.length > 0) {
       result.cleared = state.active_commands.length;
@@ -1075,10 +1086,18 @@ function formatTable(
   }
 
   // Session cleanup
-  const sessionStatus = session.cleared > 0 ? `cleared ${session.cleared} command(s)` : `clean`;
-  lines.push(
-    row('Session state', sessionStatus, c.lavender, session.cleared > 0 ? c.mintGreen : c.dim)
-  );
+  let sessionStatus, sessionColor;
+  if (session.preserved) {
+    sessionStatus = `preserved ${session.commandNames.length} command(s)`;
+    sessionColor = c.mintGreen;
+  } else if (session.cleared > 0) {
+    sessionStatus = `cleared ${session.cleared} command(s)`;
+    sessionColor = c.mintGreen;
+  } else {
+    sessionStatus = `clean`;
+    sessionColor = c.dim;
+  }
+  lines.push(row('Session state', sessionStatus, c.lavender, sessionColor));
 
   // PreCompact status with version check
   if (precompact.configured && precompact.scriptExists) {
@@ -1283,12 +1302,14 @@ async function main() {
   if (parallelSessions.cleaned > 0 && parallelSessions.cleanedSessions) {
     console.log('');
     console.log(`${c.amber}📋 Cleaned ${parallelSessions.cleaned} inactive session(s):${c.reset}`);
-    parallelSessions.cleanedSessions.forEach((sess) => {
+    parallelSessions.cleanedSessions.forEach(sess => {
       const name = sess.nickname ? `${sess.id} "${sess.nickname}"` : `Session ${sess.id}`;
       const reason = sess.reason === 'pid_dead' ? 'process ended' : sess.reason;
       console.log(`   ${c.dim}└─ ${name} (${reason}, PID ${sess.pid})${c.reset}`);
     });
-    console.log(`   ${c.slate}Sessions are cleaned when their Claude Code process is no longer running.${c.reset}`);
+    console.log(
+      `   ${c.slate}Sessions are cleaned when their Claude Code process is no longer running.${c.reset}`
+    );
   }
 
   // Story claiming: cleanup stale claims and show warnings

package/scripts/batch-pmap-loop.js

@@ -46,11 +46,14 @@ function saveSessionState(rootDir, state) {
 async function resolveGlob(pattern, rootDir) {
   // Use bash globbing for pattern expansion
   try {
-    const result = execSync(`bash -c 'shopt -s nullglob; for f in ${pattern}; do echo "$f"; done'`, {
-      cwd: rootDir,
-      encoding: 'utf8',
-      timeout: 10000,
-    });
+    const result = execSync(
+      `bash -c 'shopt -s nullglob; for f in ${pattern}; do echo "$f"; done'`,
+      {
+        cwd: rootDir,
+        encoding: 'utf8',
+        timeout: 10000,
+      }
+    );
     const files = result
       .split('\n')
       .filter(f => f.trim())
@@ -218,7 +221,9 @@ function handleBatchLoop(rootDir) {
       );
       console.log('');
       console.log(`${c.green}Pattern: ${loop.pattern}${c.reset}`);
-      console.log(`${c.dim}${summary.completed} items completed in ${iteration - 1} iterations${c.reset}`);
+      console.log(
+        `${c.dim}${summary.completed} items completed in ${iteration - 1} iterations${c.reset}`
+      );
       return;
     }
 
@@ -287,7 +292,9 @@ function handleBatchLoop(rootDir) {
       console.log(`${c.cyan}━━━ Next Item ━━━${c.reset}`);
       console.log(`${c.bold}${nextItem}${c.reset}`);
       console.log('');
-      console.log(`${c.dim}Progress: ${summary.completed}/${summary.total} items complete${c.reset}`);
+      console.log(
+        `${c.dim}Progress: ${summary.completed}/${summary.total} items complete${c.reset}`
+      );
       console.log('');
       console.log(`${c.brand}▶ Implement "${loop.action}" for this file${c.reset}`);
       console.log(`${c.dim}  Run tests when ready. Loop will validate and continue.${c.reset}`);
@@ -310,7 +317,9 @@ function handleBatchLoop(rootDir) {
       console.log('');
       console.log(`${c.green}Pattern: ${loop.pattern}${c.reset}`);
       console.log(`${c.green}Action: ${loop.action}${c.reset}`);
-      console.log(`${c.dim}${summary.completed} items completed in ${iteration} iterations${c.reset}`);
+      console.log(
+        `${c.dim}${summary.completed} items completed in ${iteration} iterations${c.reset}`
+      );
     }
   } else {
     // Tests failed - continue iterating
@@ -353,9 +362,7 @@ async function handleInit(args, rootDir) {
   }
 
   const pattern = patternArg.split('=').slice(1).join('=').replace(/"/g, '');
-  const action = actionArg
-    ? actionArg.split('=').slice(1).join('=').replace(/"/g, '')
-    : 'process';
+  const action = actionArg ? actionArg.split('=').slice(1).join('=').replace(/"/g, '') : 'process';
   const maxIterations = parseIntBounded(maxArg ? maxArg.split('=')[1] : null, 50, 1, 200);
 
   // Resolve glob pattern
@@ -432,7 +439,9 @@ function handleStatus(rootDir) {
   console.log(`  Pattern: ${loop.pattern}`);
   console.log(`  Action: ${loop.action}`);
   console.log(`  Current Item: ${loop.current_item || 'none'}`);
-  console.log(`  Progress: ${summary.completed}/${summary.total} (${summary.in_progress} in progress)`);
+  console.log(
+    `  Progress: ${summary.completed}/${summary.total} (${summary.in_progress} in progress)`
+  );
   console.log(`  Iteration: ${loop.iteration || 0}/${loop.max_iterations || 50}`);
 }
 

package/scripts/obtain-context.js

@@ -20,6 +20,7 @@ const path = require('path');
 const { execSync } = require('child_process');
 const { c: C, box } = require('../lib/colors');
 const { isValidCommandName } = require('../lib/validate');
+const { readJSONCached, readFileCached } = require('../lib/file-cache');
 
 // Claude Code's Bash tool truncates around 30K chars, but ANSI codes and
 // box-drawing characters (╭╮╰╯─│) are multi-byte UTF-8, so we need buffer.
@@ -131,11 +132,9 @@ function safeRead(filePath) {
 }
 
 function safeReadJSON(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, 'utf8'));
-  } catch {
-    return null;
-  }
+  // Use cached read for common JSON files
+  const absPath = path.resolve(filePath);
+  return readJSONCached(absPath);
 }
 
 function safeLs(dirPath) {
@@ -462,10 +461,10 @@ function generateFullContent() {
       'loop-mode': 'Autonomous epic execution (MODE=loop)',
       'multi-session': 'Multi-session coordination detected',
       'visual-e2e': 'Visual screenshot verification (VISUAL=true)',
-      'delegation': 'Expert spawning patterns (load when spawning)',
-      'stuck': 'Research prompt guidance (load after 2 failures)',
+      delegation: 'Expert spawning patterns (load when spawning)',
+      stuck: 'Research prompt guidance (load after 2 failures)',
       'plan-mode': 'Planning workflow details (load when entering plan mode)',
-      'tools': 'Tool usage guidance (load when needed)',
+      tools: 'Tool usage guidance (load when needed)',
     };
 
     content += `\n${C.dim}Section meanings:${C.reset}\n`;