language-operator 0.1.61 → 0.1.62

data/lib/language_operator/config/cluster_config.rb

@@ -2,19 +2,20 @@
 
 require 'yaml'
 require 'fileutils'
+require_relative '../utils/secure_path'
 
 module LanguageOperator
   module Config
     # Manages cluster configuration in ~/.aictl/config.yaml
     class ClusterConfig
-      CONFIG_DIR = File.expand_path('~/.aictl')
+      CONFIG_DIR = LanguageOperator::Utils::SecurePath.expand_home_path('.aictl')
       CONFIG_PATH = File.join(CONFIG_DIR, 'config.yaml')
 
       class << self
         def load
           return default_config unless File.exist?(CONFIG_PATH)
 
-          YAML.load_file(CONFIG_PATH) || default_config
+          YAML.safe_load_file(CONFIG_PATH, permitted_classes: [Symbol], aliases: true) || default_config
         rescue StandardError => e
           warn "Warning: Failed to load config from #{CONFIG_PATH}: #{e.message}"
           default_config

data/lib/language_operator/config.rb

@@ -75,16 +75,21 @@ module LanguageOperator
 
     # Convert a string value to the specified type
     #
+    # For integer and float types, uses strict conversion that raises ArgumentError
+    # for invalid input (e.g., non-numeric strings).
+    #
     # @param value [String, nil] Raw string value from environment
     # @param type [Symbol] Target type (:string, :integer, :boolean, :float, :array)
     # @param separator [String] Separator for array type (default: ',')
     # @return [Object] Converted value
+    # @raise [ArgumentError] When integer/float conversion fails
     #
     # @example String conversion
     #   Config.convert_type('hello', :string) # => "hello"
     #
     # @example Integer conversion
     #   Config.convert_type('42', :integer) # => 42
+    #   Config.convert_type('abc', :integer) # raises ArgumentError
     #
     # @example Boolean conversion
     #   Config.convert_type('true', :boolean) # => true
@@ -94,6 +99,7 @@ module LanguageOperator
     #
     # @example Float conversion
     #   Config.convert_type('3.14', :float) # => 3.14
+    #   Config.convert_type('xyz', :float) # raises ArgumentError
     #
     # @example Array conversion
     #   Config.convert_type('a,b,c', :array) # => ["a", "b", "c"]
@@ -104,9 +110,9 @@ module LanguageOperator
       when :string
         value.to_s
       when :integer
-        value.to_i
+        Integer(value)
       when :float
-        value.to_f
+        Float(value)
       when :boolean
         %w[true 1 yes on].include?(value.to_s.downcase)
       when :array
@@ -184,10 +190,22 @@ module LanguageOperator
     # @example
     #   Config.get_int('MAX_WORKERS', default: 4)
     def self.get_int(*keys, default: nil)
-      value = get(*keys)
-      return default if value.nil?
+      keys.each do |key|
+        value = ENV[key.to_s]
+        next unless value
+
+        begin
+          return Integer(value)
+        rescue ArgumentError, TypeError => e
+          suggestion = "Please set #{key} to a valid integer (e.g., export #{key}=4)"
+          raise ArgumentError, "Invalid integer value '#{value}' in environment variable '#{key}'. #{suggestion}. Error: #{e.message}"
+        end
+      end
+
+      return default if default
 
-      value.to_i
+      # No variables found
+      raise ArgumentError, "Missing required integer configuration. Checked environment variables: #{keys.join(', ')}. Please set one of these variables."
     end
 
     # Get environment variable as boolean
@@ -201,10 +219,14 @@ module LanguageOperator
     # @example
     #   Config.get_bool('USE_TLS', 'ENABLE_TLS', default: true)
     def self.get_bool(*keys, default: false)
-      value = get(*keys)
-      return default if value.nil?
+      keys.each do |key|
+        value = ENV[key.to_s]
+        next unless value
 
-      %w[true 1 yes on].include?(value.to_s.downcase)
+        return %w[true 1 yes on].include?(value.to_s.downcase)
+      end
+
+      default
     end
 
     # Get environment variable as array (split by separator)
@@ -217,10 +239,15 @@ module LanguageOperator
     # @example
     #   Config.get_array('ALLOWED_HOSTS', separator: ',')
     def self.get_array(*keys, default: [], separator: ',')
-      value = get(*keys)
-      return default if value.nil? || value.empty?
+      keys.each do |key|
+        value = ENV[key.to_s]
+        next unless value
+        next if value.empty?
+
+        return value.split(separator).map(&:strip).reject(&:empty?)
+      end
 
-      value.split(separator).map(&:strip).reject(&:empty?)
+      default
     end
 
     # Check if environment variable is set (even if empty string)

data/lib/language_operator/constants/kubernetes_labels.rb

@@ -0,0 +1,80 @@
+# frozen_string_literal: true
+
+module LanguageOperator
+  module Constants
+    # Kubernetes label constants and builder methods for consistent metadata across all resources
+    module KubernetesLabels
+      # Standard Kubernetes labels
+      NAME = 'app.kubernetes.io/name'
+      COMPONENT = 'app.kubernetes.io/component'
+      MANAGED_BY = 'app.kubernetes.io/managed-by'
+      PART_OF = 'app.kubernetes.io/part-of'
+      VERSION = 'app.kubernetes.io/version'
+
+      # Language Operator specific values
+      PROJECT_NAME = 'language-operator'
+      MANAGED_BY_AICTL = 'aictl'
+      COMPONENT_AGENT = 'agent'
+      COMPONENT_TEST_AGENT = 'test-agent'
+
+      # Custom Language Operator labels
+      TOOL_LABEL = 'langop.io/tool'
+      LEARNING_DISABLED_LABEL = 'langop.io/learning-disabled'
+      KIND_LABEL = 'langop.io/kind'
+      CLUSTER_LABEL = 'langop.io/cluster'
+
+      class << self
+        # Build standard agent labels for deployments and pods
+        #
+        # @param agent_name [String] The name of the agent
+        # @return [Hash] Hash of labels for Kubernetes resources
+        def agent_labels(agent_name)
+          {
+            NAME => agent_name,
+            COMPONENT => COMPONENT_AGENT,
+            MANAGED_BY => MANAGED_BY_AICTL,
+            PART_OF => PROJECT_NAME
+          }
+        end
+
+        # Build test agent labels for temporary test pods
+        #
+        # @param name [String] The name of the test agent
+        # @return [Hash] Hash of labels for test Kubernetes resources
+        def test_agent_labels(name)
+          {
+            NAME => name,
+            COMPONENT => COMPONENT_TEST_AGENT,
+            MANAGED_BY => MANAGED_BY_AICTL,
+            PART_OF => PROJECT_NAME
+          }
+        end
+
+        # Build a label selector string for finding agent pods
+        #
+        # @param agent_name [String] The normalized agent name
+        # @return [String] Label selector string for kubectl commands
+        def agent_selector(agent_name)
+          "#{NAME}=#{agent_name}"
+        end
+
+        # Build a label selector string for finding tool pods
+        #
+        # @param tool_name [String] The tool name
+        # @return [String] Label selector string for kubectl commands  
+        def tool_selector(tool_name)
+          "#{TOOL_LABEL}=#{tool_name}"
+        end
+
+        # Common cluster management labels
+        #
+        # @return [Hash] Hash of labels for cluster management resources
+        def cluster_management_labels
+          {
+            MANAGED_BY => MANAGED_BY_AICTL
+          }
+        end
+      end
+    end
+  end
+end

data/lib/language_operator/constants.rb

@@ -33,6 +33,12 @@ module LanguageOperator
 
       mode_string = mode_string.to_s.downcase.strip
 
+      # Handle empty/whitespace mode strings with specific error message
+      if mode_string.empty?
+        raise ArgumentError, 'AGENT_MODE environment variable is required but is unset or empty. ' \
+                             "Please set AGENT_MODE to one of: #{ALL_MODE_ALIASES.join(', ')}"
+      end
+
       EXECUTION_MODES.each do |primary, aliases|
         return primary.to_s if aliases.include?(mode_string)
       end
@@ -50,5 +56,12 @@ module LanguageOperator
 
       ALL_MODE_ALIASES.include?(mode_string.to_s.downcase.strip)
     end
+
+    # Kubernetes Custom Resource Definitions (CRD) kinds
+    # These replace magic strings scattered across CLI commands
+    RESOURCE_AGENT = 'LanguageAgent'
+    RESOURCE_MODEL = 'LanguageModel'
+    RESOURCE_TOOL = 'LanguageTool'
+    RESOURCE_PERSONA = 'LanguagePersona'
   end
 end

data/lib/language_operator/dsl/http.rb

@@ -4,6 +4,8 @@ require 'English'
 require 'net/http'
 require 'uri'
 require 'json'
+require 'ipaddr'
+require 'socket'
 
 module LanguageOperator
   module Dsl
@@ -20,8 +22,10 @@ module LanguageOperator
     class HTTP
       # Perform a GET request
       def self.get(url, headers: {}, follow_redirects: true, timeout: 30)
-        uri = parse_uri(url)
-        return { error: "Invalid URL: #{url}" } unless uri
+        validation_result = validate_url(url)
+        return validation_result unless validation_result[:success]
+
+        uri = validation_result[:uri]
 
         http = build_http(uri, timeout: timeout)
         request = Net::HTTP::Get.new(uri)
@@ -32,8 +36,10 @@ module LanguageOperator
 
       # Perform a POST request
       def self.post(url, body: nil, json: nil, headers: {}, auth: nil, timeout: 30)
-        uri = parse_uri(url)
-        return { error: "Invalid URL: #{url}" } unless uri
+        validation_result = validate_url(url)
+        return validation_result unless validation_result[:success]
+
+        uri = validation_result[:uri]
 
         http = build_http(uri, timeout: timeout)
         request = Net::HTTP::Post.new(uri)
@@ -54,8 +60,10 @@ module LanguageOperator
 
       # Perform a PUT request
       def self.put(url, body: nil, json: nil, headers: {}, auth: nil, timeout: 30)
-        uri = parse_uri(url)
-        return { error: "Invalid URL: #{url}" } unless uri
+        validation_result = validate_url(url)
+        return validation_result unless validation_result[:success]
+
+        uri = validation_result[:uri]
 
         http = build_http(uri, timeout: timeout)
         request = Net::HTTP::Put.new(uri)
@@ -75,8 +83,10 @@ module LanguageOperator
 
       # Perform a DELETE request
       def self.delete(url, headers: {}, auth: nil, timeout: 30)
-        uri = parse_uri(url)
-        return { error: "Invalid URL: #{url}" } unless uri
+        validation_result = validate_url(url)
+        return validation_result unless validation_result[:success]
+
+        uri = validation_result[:uri]
 
         http = build_http(uri, timeout: timeout)
         request = Net::HTTP::Delete.new(uri)
@@ -89,8 +99,10 @@ module LanguageOperator
 
       # Get just the headers from a URL
       def self.head(url, headers: {}, timeout: 30)
-        uri = parse_uri(url)
-        return { error: "Invalid URL: #{url}" } unless uri
+        validation_result = validate_url(url)
+        return validation_result unless validation_result[:success]
+
+        uri = validation_result[:uri]
 
         http = build_http(uri, timeout: timeout)
         request = Net::HTTP::Head.new(uri)
@@ -111,12 +123,117 @@ module LanguageOperator
       class << self
         private
 
+        def validate_url(url)
+          return { error: 'URL cannot be nil', success: false } if url.nil?
+
+          begin
+            uri = URI.parse(url)
+          rescue URI::InvalidURIError
+            return { error: 'Invalid URL format', success: false }
+          end
+
+          return { error: 'URL cannot be empty', success: false } if uri.nil?
+
+          # Validate URL scheme
+          unless %w[http https].include?(uri.scheme&.downcase)
+            return {
+              error: "URL scheme '#{uri.scheme}' not allowed. Only HTTP and HTTPS are permitted for security reasons.",
+              success: false
+            }
+          end
+
+          # Validate host
+          host_validation = validate_host(uri.host)
+          return host_validation unless host_validation[:success]
+
+          { success: true, uri: uri }
+        end
+
         def parse_uri(url)
           URI.parse(url)
         rescue URI::InvalidURIError
           nil
         end
 
+        def validate_host(host)
+          return { error: 'Host cannot be empty', success: false } if host.nil? || host.empty?
+
+          # Resolve hostname to IP if needed
+          begin
+            ip_addr = IPAddr.new(host)
+          rescue IPAddr::InvalidAddressError
+            # If it's a hostname, resolve it to IP
+            begin
+              resolved_ips = Addrinfo.getaddrinfo(host, nil, nil, :STREAM)
+              # Check all resolved IPs - if any are blocked, reject the request
+              resolved_ips.each do |addr_info|
+                ip_addr = IPAddr.new(addr_info.ip_address)
+                safe_result = safe_ip(ip_addr)
+                unless safe_result[:success]
+                  return {
+                    error: "Host '#{host}' resolves to blocked IP address #{ip_addr}: #{safe_result[:error]}",
+                    success: false
+                  }
+                end
+              end
+              return { success: true }
+            rescue SocketError
+              return { error: "Unable to resolve hostname: #{host}", success: false }
+            end
+          end
+
+          safe_result = safe_ip(ip_addr)
+          unless safe_result[:success]
+            return {
+              error: "IP address #{ip_addr} is blocked: #{safe_result[:error]}",
+              success: false
+            }
+          end
+
+          { success: true }
+        end
+
+        def safe_ip(ip_addr)
+          # Block private IP ranges (RFC 1918)
+          private_ranges = [
+            { range: IPAddr.new('10.0.0.0/8'), description: 'private IP range (RFC 1918)' },
+            { range: IPAddr.new('172.16.0.0/12'), description: 'private IP range (RFC 1918)' },
+            { range: IPAddr.new('192.168.0.0/16'), description: 'private IP range (RFC 1918)' }
+          ]
+
+          # Block loopback addresses
+          loopback_ranges = [
+            { range: IPAddr.new('127.0.0.0/8'), description: 'loopback address' },
+            { range: IPAddr.new('::1/128'), description: 'IPv6 loopback address' }
+          ]
+
+          # Block link-local addresses
+          link_local_ranges = [
+            { range: IPAddr.new('169.254.0.0/16'), description: 'link-local address (AWS metadata endpoint)' },
+            { range: IPAddr.new('fe80::/10'), description: 'IPv6 link-local address' }
+          ]
+
+          # Block broadcast address
+          broadcast_ranges = [
+            { range: IPAddr.new('255.255.255.255/32'), description: 'broadcast address' }
+          ]
+
+          # Check if IP is in any blocked range
+          all_blocked_ranges = private_ranges + loopback_ranges + link_local_ranges + broadcast_ranges
+          all_blocked_ranges.each do |blocked_range|
+            if blocked_range[:range].include?(ip_addr)
+              return {
+                error: "access to #{blocked_range[:description]} not allowed for security reasons",
+                success: false
+              }
+            end
+          end
+
+          { success: true }
+        rescue IPAddr::InvalidAddressError
+          { error: 'invalid IP address format', success: false }
+        end
+
         def build_http(uri, timeout: 30)
           http = Net::HTTP.new(uri.host, uri.port)
           http.use_ssl = (uri.scheme == 'https')

data/lib/language_operator/dsl.rb

@@ -98,16 +98,43 @@ module LanguageOperator
       #
       # @param file_path [String] Path to the tool definition file
       # @return [Registry] The global registry with loaded tools
+      # @raise [PathTraversalError] When the file path attempts path traversal
+      # @raise [FileNotFoundError] When the file doesn't exist
+      # @raise [FilePermissionError] When the file can't be read due to permissions
+      # @raise [FileSyntaxError] When the file contains invalid Ruby syntax
       #
       # @example
       #   LanguageOperator::Dsl.load_file("mcp/tools.rb")
       def load_file(file_path)
-        code = File.read(file_path)
+        # Validate file path to prevent path traversal attacks
+        validated_path = validate_file_path!(file_path, context: 'tool definition file loading')
+
+        # Check if file exists
+        raise FileNotFoundError, Errors.file_not_found(file_path, 'tool definition file') unless File.exist?(validated_path)
+
+        # Attempt to read the file
+        begin
+          code = File.read(validated_path)
+        rescue Errno::EACCES
+          raise FilePermissionError, Errors.file_permission_denied(file_path, 'tool definition file')
+        rescue Errno::EISDIR
+          raise FileNotFoundError, Errors.file_not_found(file_path, 'tool definition file')
+        rescue SystemCallError => e
+          raise FileLoadError, "Error reading tool definition file '#{file_path}': #{e.message}"
+        end
+
         context = Context.new(registry)
 
         # Execute in sandbox with validation
-        executor = Agent::Safety::SafeExecutor.new(context)
-        executor.eval(code, file_path)
+        begin
+          executor = Agent::Safety::SafeExecutor.new(context)
+          executor.eval(code, validated_path)
+        rescue SyntaxError => e
+          raise FileSyntaxError, Errors.file_syntax_error(file_path, e.message, 'tool definition file')
+        rescue StandardError => e
+          # Re-raise with additional context for other execution errors
+          raise FileLoadError, "Error executing tool definition file '#{file_path}': #{e.message}"
+        end
 
         registry
       end
@@ -116,16 +143,43 @@ module LanguageOperator
       #
       # @param file_path [String] Path to the agent definition file
       # @return [AgentRegistry] The global agent registry
+      # @raise [PathTraversalError] When the file path attempts path traversal
+      # @raise [FileNotFoundError] When the file doesn't exist
+      # @raise [FilePermissionError] When the file can't be read due to permissions
+      # @raise [FileSyntaxError] When the file contains invalid Ruby syntax
       #
       # @example
       #   LanguageOperator::Dsl.load_agent_file("agents/news-summarizer.rb")
       def load_agent_file(file_path)
-        code = File.read(file_path)
+        # Validate file path to prevent path traversal attacks
+        validated_path = validate_file_path!(file_path, context: 'agent definition file loading')
+
+        # Check if file exists
+        raise FileNotFoundError, Errors.file_not_found(file_path, 'agent definition file') unless File.exist?(validated_path)
+
+        # Attempt to read the file
+        begin
+          code = File.read(validated_path)
+        rescue Errno::EACCES
+          raise FilePermissionError, Errors.file_permission_denied(file_path, 'agent definition file')
+        rescue Errno::EISDIR
+          raise FileNotFoundError, Errors.file_not_found(file_path, 'agent definition file')
+        rescue SystemCallError => e
+          raise FileLoadError, "Error reading agent definition file '#{file_path}': #{e.message}"
+        end
+
         context = AgentContext.new(agent_registry)
 
         # Execute in sandbox with validation
-        executor = Agent::Safety::SafeExecutor.new(context)
-        executor.eval(code, file_path)
+        begin
+          executor = Agent::Safety::SafeExecutor.new(context)
+          executor.eval(code, validated_path)
+        rescue SyntaxError => e
+          raise FileSyntaxError, Errors.file_syntax_error(file_path, e.message, 'agent definition file')
+        rescue StandardError => e
+          # Re-raise with additional context for other execution errors
+          raise FileLoadError, "Error executing agent definition file '#{file_path}': #{e.message}"
+        end
 
         agent_registry
       end
@@ -155,6 +209,99 @@ module LanguageOperator
       def create_server(server_name: 'langop-tools', server_context: {})
         Adapter.create_mcp_server(registry, server_name: server_name, server_context: server_context)
       end
+
+      private
+
+      # Validate file path to prevent path traversal attacks
+      #
+      # @param file_path [String] The file path to validate
+      # @param context [String] Context for error messages
+      # @return [String] The validated and resolved absolute path
+      # @raise [PathTraversalError] When path traversal is detected
+      def validate_file_path!(file_path, context: 'file loading')
+        # Check for suspicious patterns before path resolution
+        raise PathTraversalError, Errors.path_traversal_blocked(context) if contains_path_traversal_patterns?(file_path)
+
+        # Resolve the path to handle relative paths and symlinks
+        begin
+          resolved_path = File.expand_path(file_path)
+        rescue ArgumentError => e
+          raise PathTraversalError, "Invalid file path during #{context}: #{e.message}"
+        end
+
+        # Get allowed base directories
+        allowed_bases = get_allowed_base_paths
+
+        # Check if resolved path is within any allowed base directory
+        raise PathTraversalError, Errors.path_traversal_blocked(context) unless allowed_bases.any? { |base| path_within_base?(resolved_path, base) }
+
+        resolved_path
+      end
+
+      # Check for common path traversal patterns in the raw path
+      #
+      # @param file_path [String] The file path to check
+      # @return [Boolean] True if suspicious patterns are detected
+      def contains_path_traversal_patterns?(file_path)
+        # List of suspicious patterns that indicate path traversal attempts
+        # Focus on actual traversal patterns, not just any relative path
+        patterns = [
+          /\.\./, # Parent directory references (classic traversal)
+          /\x00/, # Null byte injection
+          /%2e%2e/i,                # URL-encoded parent directory
+          /%2f/i,                   # URL-encoded path separator
+          /%5c/i,                   # URL-encoded backslash
+          /\\+\.\./,                # Windows-style parent directory with backslashes
+          %r{/\.\.+},                # Multiple dots after slash
+          %r{\.\.[/\\]}              # Parent directory followed by path separator
+        ]
+
+        patterns.any? { |pattern| file_path.match?(pattern) }
+      end
+
+      # Get list of allowed base directories for file operations
+      #
+      # @return [Array<String>] List of allowed base directory paths
+      def get_allowed_base_paths
+        # Start with current working directory
+        allowed_paths = [File.expand_path('.')]
+
+        # Add paths from environment variable if set
+        if ENV['LANGOP_ALLOWED_PATHS']
+          custom_paths = ENV['LANGOP_ALLOWED_PATHS'].split(':').map { |path| File.expand_path(path.strip) }
+          allowed_paths.concat(custom_paths)
+        end
+
+        # Add common subdirectories for typical usage patterns
+        %w[agents tools examples].each do |subdir|
+          subdir_path = File.expand_path(subdir)
+          allowed_paths << subdir_path if Dir.exist?(subdir_path)
+        end
+
+        # In test environment, be more permissive (allow /tmp and similar)
+        if defined?(RSpec) || ENV['RAILS_ENV'] == 'test' || ENV['RACK_ENV'] == 'test'
+          allowed_paths.concat([
+            '/tmp',
+            File.expand_path('spec'),
+            File.expand_path('test')
+          ].map { |path| File.expand_path(path) })
+        end
+
+        allowed_paths.uniq
+      end
+
+      # Check if a resolved path is within an allowed base directory
+      #
+      # @param resolved_path [String] The resolved absolute path to check
+      # @param base_path [String] The base directory path
+      # @return [Boolean] True if path is within the base directory
+      def path_within_base?(resolved_path, base_path)
+        # Ensure base path ends with separator for accurate prefix matching
+        normalized_base = File.join(base_path, '')
+
+        # Allow exact matches or paths that start with the base directory
+        resolved_path == base_path || resolved_path.start_with?(normalized_base)
+      end
     end
   end
 end

data/lib/language_operator/errors.rb

@@ -1,6 +1,19 @@
 # frozen_string_literal: true
 
 module LanguageOperator
+  # Base exception class for all Language Operator errors
+  class Error < StandardError; end
+
+  # File loading related errors
+  class FileLoadError < Error; end
+  class FileNotFoundError < FileLoadError; end
+  class FilePermissionError < FileLoadError; end
+  class FileSyntaxError < FileLoadError; end
+
+  # Security related errors
+  class SecurityError < Error; end
+  class PathTraversalError < SecurityError; end
+
   # Standardized error formatting module for consistent error messages across tools
   module Errors
     # Resource not found error
@@ -56,5 +69,42 @@ module LanguageOperator
     def self.empty_field(field_name)
       "Error: #{field_name} cannot be empty"
     end
+
+    # File not found error
+    # @param file_path [String] Path to the file that wasn't found
+    # @param context [String] Additional context about what the file is for
+    # @return [String] Formatted error message
+    def self.file_not_found(file_path, context = 'file')
+      "Error: #{context.capitalize} not found at '#{file_path}'. " \
+        'Please check the file path exists and is accessible.'
+    end
+
+    # File permission error
+    # @param file_path [String] Path to the file with permission issues
+    # @param context [String] Additional context about what the file is for
+    # @return [String] Formatted error message
+    def self.file_permission_denied(file_path, context = 'file')
+      "Error: Permission denied reading #{context} '#{file_path}'. " \
+        'Please check file permissions or run with appropriate access rights.'
+    end
+
+    # File syntax error
+    # @param file_path [String] Path to the file with syntax errors
+    # @param original_error [String] Original error message from parser
+    # @param context [String] Additional context about what the file is for
+    # @return [String] Formatted error message
+    def self.file_syntax_error(file_path, original_error, context = 'file')
+      "Error: Syntax error in #{context} '#{file_path}': #{original_error}. " \
+        'Please check the file for valid Ruby syntax.'
+    end
+
+    # Path traversal security error
+    # @param context [String] Context about what operation was attempted
+    # @return [String] Formatted error message
+    def self.path_traversal_blocked(context = 'file operation')
+      "Error: Path traversal attempt blocked during #{context}. " \
+        'File path must be within allowed directories. ' \
+        'Use relative paths or configure LANGOP_ALLOWED_PATHS if needed.'
+    end
   end
 end