principles-disciple 1.8.1 → 1.8.3

package/{dist/core/workspace-context.js → src/core/workspace-context.ts}

@@ -1,149 +1,173 @@
-import { resolvePdPath } from './paths.js';
+import { resolvePdPath, PD_FILES } from './paths.js';
 import { PathResolver } from './path-resolver.js';
 import { ConfigService } from './config-service.js';
-import { EventLogService } from './event-log.js';
+import { PainConfig } from './config.js';
+import { EventLogService, EventLog } from './event-log.js';
 import { DictionaryService } from './dictionary-service.js';
+import { PainDictionary } from './dictionary.js';
 import { HygieneTracker } from './hygiene/tracker.js';
 import { EvolutionReducerImpl } from './evolution-reducer.js';
-import { TrajectoryRegistry } from './trajectory.js';
+import { TrajectoryDatabase, TrajectoryRegistry, TrajectoryDatabaseOptions } from './trajectory.js';
+
 /**
  * WorkspaceContext - Centralized management of workspace-specific paths and services.
  * Implements a cached singleton pattern per workspace directory.
  */
 export class WorkspaceContext {
-    static instances = new Map();
-    static pathResolver = new PathResolver();
-    workspaceDir;
-    stateDir;
-    _config;
-    _eventLog;
-    _dictionary;
-    _hygiene;
-    _evolutionReducer;
-    _trajectory;
-    constructor(workspaceDir, stateDir) {
+    private static instances = new Map<string, WorkspaceContext>();
+    private static pathResolver = new PathResolver();
+
+    public readonly workspaceDir: string;
+    public readonly stateDir: string;
+
+    private _config?: PainConfig;
+    private _eventLog?: EventLog;
+    private _dictionary?: PainDictionary;
+    private _hygiene?: HygieneTracker;
+    private _evolutionReducer?: EvolutionReducerImpl;
+    private _trajectory?: TrajectoryDatabase;
+
+    private constructor(workspaceDir: string, stateDir: string) {
         this.workspaceDir = workspaceDir;
         this.stateDir = stateDir;
     }
+
     /**
      * Governance configuration for this workspace.
      */
-    get config() {
+    get config(): PainConfig {
         if (!this._config) {
             this._config = ConfigService.get(this.stateDir);
         }
         return this._config;
     }
+
     /**
      * Event logging service for this workspace.
      */
-    get eventLog() {
+    get eventLog(): EventLog {
         if (!this._eventLog) {
             this._eventLog = EventLogService.get(this.stateDir);
         }
         return this._eventLog;
     }
+
     /**
      * Pain dictionary service for this workspace.
      */
-    get dictionary() {
+    get dictionary(): PainDictionary {
         if (!this._dictionary) {
             this._dictionary = DictionaryService.get(this.stateDir);
         }
         return this._dictionary;
     }
+
     /**
      * Hygiene tracking service for this workspace.
      */
-    get hygiene() {
+    get hygiene(): HygieneTracker {
         if (!this._hygiene) {
             this._hygiene = new HygieneTracker(this.stateDir);
         }
         return this._hygiene;
     }
+
+
     /**
      * Evolution reducer singleton for this workspace.
      */
-    get evolutionReducer() {
+    get evolutionReducer(): EvolutionReducerImpl {
         if (!this._evolutionReducer) {
             this._evolutionReducer = new EvolutionReducerImpl({ workspaceDir: this.workspaceDir });
         }
         return this._evolutionReducer;
     }
+
     /**
      * Trajectory database for analytics and sample curation.
      */
-    get trajectory() {
+    get trajectory(): TrajectoryDatabase {
         if (!this._trajectory) {
             this._trajectory = TrajectoryRegistry.get(this.workspaceDir, this.getTrajectoryOptions());
         }
         return this._trajectory;
     }
-    getTrajectoryOptions() {
+
+    private getTrajectoryOptions(): Omit<TrajectoryDatabaseOptions, 'workspaceDir'> {
         const inlineThreshold = Number(this.config.get('trajectory.blob_inline_threshold_bytes'));
         const busyTimeoutMs = Number(this.config.get('trajectory.busy_timeout_ms'));
         const orphanBlobGraceDays = Number(this.config.get('trajectory.orphan_blob_grace_days'));
+
         return {
             blobInlineThresholdBytes: Number.isFinite(inlineThreshold) && inlineThreshold > 0 ? inlineThreshold : undefined,
             busyTimeoutMs: Number.isFinite(busyTimeoutMs) && busyTimeoutMs >= 0 ? busyTimeoutMs : undefined,
             orphanBlobGraceDays: Number.isFinite(orphanBlobGraceDays) && orphanBlobGraceDays >= 0 ? orphanBlobGraceDays : undefined,
         };
     }
+
     /**
      * Creates or retrieves a WorkspaceContext instance from an OpenClaw hook context.
      * Uses PathResolver to handle path normalization and fallback logic.
      * @throws Error if workspaceDir is missing and no fallback available.
      */
-    static fromHookContext(ctx) {
+    static fromHookContext(ctx: any): WorkspaceContext {
         const logger = ctx.logger;
-        const log = (msg) => logger?.info?.(msg) ?? console.log(msg);
-        const logWarn = (msg) => logger?.warn?.(msg) ?? console.warn(msg);
+        const log = (msg: string) => logger?.info?.(msg);
+        const logWarn = (msg: string) => logger?.warn?.(msg);
+
         let workspaceDir = ctx.workspaceDir;
+        
         if (!workspaceDir) {
             logWarn('[PD:WorkspaceContext] workspaceDir not provided in context, using PathResolver fallback');
             workspaceDir = this.pathResolver.getWorkspaceDir();
             log(`[PD:WorkspaceContext] Resolved workspaceDir to: ${workspaceDir}`);
-        }
-        else {
+        } else {
             const normalized = this.pathResolver.normalizeWorkspacePath(workspaceDir);
             if (normalized !== workspaceDir) {
                 log(`[PD:WorkspaceContext] Normalized workspaceDir: ${workspaceDir} -> ${normalized}`);
                 workspaceDir = normalized;
             }
         }
+
         const existing = this.instances.get(workspaceDir);
-        if (existing)
-            return existing;
+        if (existing) return existing;
+
         let stateDir = ctx.stateDir;
         if (!stateDir) {
             stateDir = resolvePdPath(workspaceDir, 'STATE_DIR');
             log(`[PD:WorkspaceContext] Computed stateDir: ${stateDir}`);
         }
+
         const instance = new WorkspaceContext(workspaceDir, stateDir);
         this.instances.set(workspaceDir, instance);
+        
         log(`[PD:WorkspaceContext] Created new context for workspace: ${workspaceDir}`);
+        
         return instance;
     }
+
     /**
      * Resolves a PD file path within the workspace.
      */
-    resolve(fileKey) {
+    resolve(fileKey: keyof typeof PD_FILES): string {
         return resolvePdPath(this.workspaceDir, fileKey);
     }
+
     /**
      * Resets internal caches for services and paths.
      */
-    invalidate() {
+    invalidate(): void {
         this._config = undefined;
         this._eventLog = undefined;
         this._dictionary = undefined;
         this._evolutionReducer = undefined;
         this._trajectory = undefined;
     }
+
     /**
      * Removes a workspace from the cache.
      */
-    static dispose(workspaceDir) {
+    static dispose(workspaceDir: string): void {
         const normalized = this.pathResolver.normalizeWorkspacePath(workspaceDir);
         const instance = this.instances.get(normalized);
         if (instance) {
@@ -152,10 +176,11 @@ export class WorkspaceContext {
         }
         TrajectoryRegistry.dispose(normalized);
     }
+
     /**
      * Clears the instance cache (primarily for testing).
      */
-    static clearCache() {
+    static clearCache(): void {
         for (const instance of this.instances.values()) {
             instance.invalidate();
         }

package/src/hooks/bash-risk.ts

@@ -0,0 +1,171 @@
+/**
+ * Bash Risk Analysis Module
+ *
+ * Analyzes bash command security risks and determines command categorization.
+ *
+ * **Responsibilities:**
+ * - De-obfuscate Unicode/Cyrillic lookalike characters (security bypass prevention)
+ * - Tokenize command chains to detect multi-command bypasses
+ * - Classify commands as: 'safe', 'dangerous', or 'normal'
+ * - Pattern matching against safe/dangerous regex patterns
+ * - Fail-closed behavior (invalid regex = dangerous)
+ *
+ * **Configuration:**
+ * - Bash safe patterns from gfi_gate.bash_safe_patterns
+ * - Bash dangerous patterns from gfi_gate.bash_dangerous_patterns
+ */
+
+// TODO: Extract types from gate.ts related to bash risk analysis
+export interface BashRiskConfig {
+  bash_safe_patterns?: string[];
+  bash_dangerous_patterns?: string[];
+}
+
+export type BashRiskLevel = 'safe' | 'dangerous' | 'normal';
+
+/**
+ * Analyzes a bash command to determine its risk level.
+ *
+ * Implements security features:
+ * - Unicode/Cyrillic de-obfuscation to detect homograph attacks
+ * - Command chain tokenization to catch multi-command bypasses
+ * - Pattern matching against safe/dangerous regex patterns
+ * - Fail-closed behavior (invalid dangerous regex = dangerous)
+ *
+ * @param command - The bash command to analyze
+ * @param safePatterns - Regex patterns that indicate safe commands
+ * @param dangerousPatterns - Regex patterns that indicate dangerous commands
+ * @param logger - Optional logger for warnings about invalid patterns
+ * @returns The risk level: 'safe', 'dangerous', or 'normal'
+ */
+export function analyzeBashCommand(
+  command: string,
+  safePatterns: string[],
+  dangerousPatterns: string[],
+  logger?: { warn?: (message: string) => void }
+): BashRiskLevel {
+  let normalizedCmd = command.trim().toLowerCase();
+
+  // Unicode de-obfuscation — convert Cyrillic/Unicode lookalikes to ASCII equivalents
+  // Common Cyrillic lookalikes that could bypass detection: аеорсух (Cyrillic) → aeopcyx (Latin)
+  const CYRILLIC_TO_LATIN: Record<string, string> = {
+    'а': 'a', 'е': 'e', 'о': 'o', 'р': 'p', 'с': 'c', 'у': 'y', 'х': 'x',
+    'А': 'a', 'Е': 'e', 'О': 'o', 'Р': 'p', 'С': 'c', 'У': 'y', 'Х': 'x',
+    // Additional confusable chars
+    'і': 'i', 'ј': 'j', 'ѕ': 's', 'ԁ': 'd', 'ɡ': 'g', 'һ': 'h', 'ⅰ': 'i',
+    'ƚ': 'l', 'м': 'm', 'п': 'n', 'ѵ': 'v', 'ѡ': 'w', 'ᴦ': 'r', 'ꜱ': 's',
+  };
+  normalizedCmd = normalizedCmd.replace(/[а-яА-Яіјѕԁɡһⅰƚмпеꜱѵѡᴦꜱ]/g, m => CYRILLIC_TO_LATIN[m] ?? m);
+
+  // Zero-width character detection — detect hidden characters that could bypass pattern matching
+  // Common zero-width characters used in command injection:
+  // - Zero-width space (U+200B)
+  // - Zero-width non-joiner (U+200C)
+  // - Zero-width joiner (U+200D)
+  // - Word joiner (U+2060)
+  // - Zero-width invisible separator (U+FEFF)
+  const ZERO_WIDTH_CHARS = /[\u200B\u200C\u200D\u2060\uFEFF]/g;
+  if (ZERO_WIDTH_CHARS.test(command)) {
+    logger?.warn?.(`[PD_GATE] Bash command contains zero-width characters — blocking as dangerous`);
+    return 'dangerous'; // Fail-closed: zero-width chars are suspicious
+  }
+
+  // Tokenize command chain before pattern matching to catch `cmd1 && cmd2` bypasses
+  // Only split on statement separators (; && ||), NOT on pipe (|) which is part of the command
+  const tokens = normalizedCmd
+    .split(/\s*(?:;|&&|\|\|)\s*/)
+    .map(t => t.trim())
+    .filter(t => t.length > 0);
+
+  // If no tokens (e.g., pure pipe-only), use the original
+  const segments = tokens.length > 0 ? tokens : [normalizedCmd];
+
+  // Also strip outer $() and backticks from each segment, but PRESERVE inner content
+  const cleanSegments = segments.map(seg => {
+    let s = seg;
+    // Extract inner content from $() or ${} or backtick-wrapped commands
+    // IMPORTANT: Preserve the inner command for analysis, don't drop it entirely
+    s = s.replace(/^\$\(([^)]+)\)$/, '$1').replace(/^\$\{([^}]+)\}$/, '$1').replace(/^`([^`]+)`$/, '$1');
+    return s.trim();
+  }).filter(s => s.length > 0);
+
+  // SECURITY: If original input was non-empty but we have no analyzable content, fail closed
+  if (cleanSegments.length === 0 && normalizedCmd.trim().length > 0) {
+    logger?.warn?.(`[PD_GATE] Bash command analysis produced empty segments from non-empty input, failing closed: ${normalizedCmd.substring(0, 100)}`);
+    return 'dangerous';
+  }
+
+  // 1. Check dangerous patterns against each segment
+  for (const seg of cleanSegments) {
+    for (const pattern of dangerousPatterns) {
+      try {
+        if (new RegExp(pattern, 'i').test(seg)) {
+          return 'dangerous';
+        }
+      } catch (error) {
+        logger?.warn?.(`[PD_GATE] Invalid dangerous bash regex "${pattern}": ${String(error)}. Failing closed.`);
+        return 'dangerous';
+        // Fail-closed: 无效的危险模式正则视为匹配危险命令
+      }
+    }
+  }
+
+  // 2. Check safe patterns (only if ALL segments are safe)
+  for (const seg of cleanSegments) {
+    let isSafe = false;
+    for (const pattern of safePatterns) {
+      try {
+        if (new RegExp(pattern, 'i').test(seg)) {
+          isSafe = true;
+          break;
+        }
+      } catch (error) {
+        logger?.warn?.(`[PD_GATE] Invalid safe bash regex "${pattern}": ${String(error)}. Ignoring safe override.`);
+      }
+    }
+    if (!isSafe) {
+      // Not all segments are safe → treat as normal
+      return 'normal';
+    }
+  }
+
+  // All segments are safe
+  return 'safe';
+}
+
+export interface DynamicThresholdConfig {
+  large_change_lines: number;
+  ep_tier_multipliers: Record<string, number>;
+}
+
+/**
+ * Calculates the dynamic GFI threshold based on EP tier and line changes.
+ *
+ * The threshold is adjusted by:
+ * 1. EP tier multiplier (higher tiers get higher thresholds)
+ * 2. Large change reduction (big edits lower the threshold to catch more issues)
+ *
+ * @param baseThreshold - The base GFI threshold (typically 50 for GFI)
+ * @param epTier - Current EP tier (1-5)
+ * @param lineChanges - Number of lines being changed
+ * @param config - Configuration with large_change_lines and ep_tier_multipliers
+ * @returns The adjusted threshold (minimum 0)
+ */
+export function calculateDynamicThreshold(
+  baseThreshold: number,
+  epTier: number,
+  lineChanges: number,
+  config: DynamicThresholdConfig
+): number {
+  // 1. EP Tier multiplier
+  const tierMultiplier = config.ep_tier_multipliers[epTier.toString()] || 1.0;
+  let threshold = baseThreshold * tierMultiplier;
+
+  // 2. Large scale modification reduces threshold
+  if (lineChanges > config.large_change_lines) {
+    const ratio = Math.min(lineChanges / 200, 0.5); // Reduce by up to 50%
+    threshold = threshold * (1 - ratio);
+  }
+
+  return Math.round(Math.max(threshold, 0));
+}

package/src/hooks/edit-verification.ts

@@ -0,0 +1,295 @@
+/**
+ * Edit Verification Module
+ *
+ * Enforces P-03 (precise verification principle) for edit tool operations.
+ *
+ * **Responsibilities:**
+ * - Verify oldText matches current file content before edit
+ * - Fuzzy matching for whitespace-agnostic comparison
+ * - File size limits and binary file detection
+ * - Automatic correction of whitespace mismatches
+ * - Detailed error messages with guidance for fix
+ *
+ * **Configuration:**
+ * - Edit verification settings from profile.edit_verification
+ * - Max file size threshold (default 10MB)
+ * - Fuzzy match threshold (default 0.8)
+ * - Skip action for large files (warn/block)
+ */
+
+import * as fs from 'fs';
+import * as path from 'path';
+import type { PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
+import type { WorkspaceContext } from '../core/workspace-context.js';
+
+export interface EditVerificationConfig {
+  enabled?: boolean;
+  max_file_size_bytes?: number;
+  fuzzy_match_enabled?: boolean;
+  fuzzy_match_threshold?: number;
+  skip_large_file_action?: 'warn' | 'block';
+}
+
+/**
+ * Normalize a line for fuzzy matching by collapsing whitespace
+ */
+export function normalizeLine(line: string): string {
+  return line.replace(/\s+/g, ' ').trim();
+}
+
+/**
+ * Find fuzzy match between oldText and current file content
+ * @param lines - File content split into lines
+ * @param oldLines - oldText split into lines
+ * @param threshold - Match threshold (0-1)
+ * @returns Match index or -1 if not found
+ */
+export function findFuzzyMatch(lines: string[], oldLines: string[], threshold: number = 0.8): number {
+  if (oldLines.length === 0) return -1;  // P2 fix: empty array boundary check
+
+  const normalizedLines = lines.map(normalizeLine);
+  const normalizedOldLines = oldLines.map(normalizeLine);
+
+  // Try to find matching sequence
+  for (let i = 0; i <= lines.length - oldLines.length; i++) {
+    let matchCount = 0;
+    for (let j = 0; j < oldLines.length; j++) {
+      if (normalizedLines[i + j] === normalizedOldLines[j]) {
+        matchCount++;
+      }
+    }
+
+    // Use threshold from config
+    if (matchCount >= oldLines.length * threshold) {
+      return i;
+    }
+  }
+
+  return -1;
+}
+
+/**
+ * Try to find a fuzzy match for oldText in current content
+ * @param currentContent - Current file content
+ * @param oldText - Text to match
+ * @param threshold - Match threshold (0-1)
+ * @returns Object with found status and corrected text if found
+ */
+export function tryFuzzyMatch(currentContent: string, oldText: string, threshold: number = 0.8): { found: boolean; correctedText?: string } {
+  const lines = currentContent.split('\n');
+  const oldLines = oldText.split('\n');
+
+  const matchIndex = findFuzzyMatch(lines, oldLines, threshold);
+
+  if (matchIndex !== -1) {
+    // Found fuzzy match, extract actual text from file
+    const correctedText = lines.slice(matchIndex, matchIndex + oldLines.length).join('\n');
+    return { found: true, correctedText };
+  }
+
+  return { found: false };
+}
+
+/**
+ * Generate a helpful error message for edit verification failure
+ */
+export function generateEditError(filePath: string, oldText: string, currentContent: string): string {
+  const expectedSnippet = oldText.split('\n').slice(0, 3).join('\n').substring(0, 200);
+  const actualSnippet = currentContent.substring(0, 200);
+
+  return `[P-03 Violation] Edit verification failed
+
+File: ${filePath}
+
+The text you're trying to replace does not match the current file content.
+
+Expected to find:
+${expectedSnippet}${oldText.length > 200 ? '...' : ''}
+
+Actual file contains:
+${actualSnippet}${currentContent.length > 200 ? '...' : ''}
+
+Possible reasons:
+  - File has been modified by another process
+  - Whitespace characters do not match (spaces, tabs, newlines)
+  - Context compression caused outdated information
+
+Solution:
+  1. Use 'read' tool to get current file content
+  2. Update your edit command with exact text from file
+  3. Retry edit operation
+
+This is enforced by P-03 (精确匹配前验证原则).`;
+}
+
+/**
+ * Handle edit tool verification before allowing operation
+ * This enforces P-03 at the tool layer
+ */
+export function handleEditVerification(
+  event: PluginHookBeforeToolCallEvent,
+  wctx: WorkspaceContext,
+  ctx: { logger?: any; sessionId?: string },
+  config: EditVerificationConfig = {}
+): PluginHookBeforeToolCallResult | void {
+  // Skip verification if disabled - return early without any processing or logging
+  if (config.enabled === false) {
+    return;
+  }
+
+  const logger = ctx.logger || console;
+  const maxSizeBytes = config.max_file_size_bytes ?? 10 * 1024 * 1024; // Default 10MB
+  const fuzzyMatchEnabled = config.fuzzy_match_enabled !== false;
+  const fuzzyMatchThreshold = config.fuzzy_match_threshold ?? 0.8;
+  const skipAction: 'warn' | 'block' = config.skip_large_file_action ?? 'warn';
+
+  // 1. Extract parameters (handle both parameter naming conventions)
+  const filePath = event.params.file_path || event.params.path || event.params.file;
+  const oldText = event.params.oldText || event.params.old_string;
+
+  if (!filePath || !oldText) {
+    // Missing required parameters, let it fail naturally
+    return;
+  }
+
+  // 2. Resolve and read file
+  let absolutePath: string;
+  try {
+    absolutePath = wctx.resolve(filePath);
+  } catch (error) {
+    // Path resolution error, let it fail naturally
+    return;
+  }
+
+  // 2.5. Skip verification for binary files
+  const BINARY_EXTENSIONS = ['.png', '.jpg', '.jpeg', '.gif', '.webp', '.bmp', '.svg',
+                           '.pdf', '.zip', '.tar', '.gz', '.7z', '.rar',
+                           '.exe', '.dll', '.so', '.dylib', '.bin',
+                           '.mp3', '.mp4', '.avi', '.mov', '.wav',
+                           '.ttf', '.otf', '.woff', '.woff2',
+                           '.doc', '.docx', '.xls', '.xlsx', '.ppt', '.pptx'];
+  const ext = path.extname(absolutePath).toLowerCase();
+  if (BINARY_EXTENSIONS.includes(ext)) {
+    logger?.info?.(`[PD_GATE:EDIT_VERIFY] Skipping verification for binary file: ${path.basename(filePath)}`);
+    return;
+  }
+
+  try {
+    // 2.6. Check file size before reading (P-03 improvement)
+    try {
+      const stats = fs.statSync(absolutePath);
+      const fileSizeBytes = stats.size;
+      const fileSizeMB = fileSizeBytes / (1024 * 1024);
+
+      if (fileSizeBytes > maxSizeBytes) {
+        const message = `[PD_GATE:EDIT_VERIFY] File size check: ${path.basename(filePath)} is ${fileSizeMB.toFixed(2)}MB (threshold: ${(maxSizeBytes / (1024 * 1024)).toFixed(2)}MB)`;
+
+        if (skipAction === 'block') {
+          logger?.warn?.(message + ' - BLOCKED');
+          return {
+            block: true,
+            blockReason: `${message}\n\nFile is too large for edit verification. Increase max_file_size_bytes in PROFILE.json or reduce file size.`
+          };
+        } else {
+          logger?.warn?.(message + ' - SKIPPING verification');
+          return; // Skip verification but allow operation
+        }
+      }
+
+      logger?.info?.(`[PD_GATE:EDIT_VERIFY] File size check passed: ${path.basename(filePath)} (${fileSizeMB.toFixed(2)}MB)`);
+    } catch (statError) {
+      // File stat error (e.g., permission denied)
+      const errStr = statError instanceof Error ? statError.message : String(statError);
+      const errCode = (statError as any).code;
+
+      if (errCode === 'EACCES' || errCode === 'EPERM') {
+        logger?.error?.(`[PD_GATE:EDIT_VERIFY] Permission denied accessing file: ${path.basename(filePath)} (${errStr})`);
+        return {
+          block: true,
+          blockReason: `[P-03 Error] Permission denied: Cannot access file ${absolutePath}\n\nError: ${errStr}\n\nSolution: Check file permissions or run with appropriate access rights.`
+        };
+      } else if (errCode === 'ENOENT') {
+        logger?.warn?.(`[PD_GATE:EDIT_VERIFY] File not found: ${path.basename(filePath)} (${errStr})`);
+        // File doesn't exist - let edit operation proceed (it will create file)
+        return;
+      } else {
+        logger?.warn?.(`[PD_GATE:EDIT_VERIFY] Stat error: ${errStr}`);
+        // Let it fail naturally on read attempt
+      }
+    }
+
+    // 3. Read current file content with improved error handling
+    let currentContent: string;
+    try {
+      currentContent = fs.readFileSync(absolutePath, 'utf-8');
+    } catch (readError) {
+      const errStr = readError instanceof Error ? readError.message : String(readError);
+      const errCode = (readError as any).code;
+
+      if (errCode === 'EACCES' || errCode === 'EPERM') {
+        logger?.error?.(`[PD_GATE:EDIT_VERIFY] Permission denied reading file: ${path.basename(filePath)} (${errStr})`);
+        return {
+          block: true,
+          blockReason: `[P-03 Error] Permission denied: Cannot read file ${absolutePath}\n\nError: ${errStr}\n\nSolution: Check file permissions or run with appropriate access rights.`
+        };
+      } else if (errCode === 'ENOENT') {
+        logger?.warn?.(`[PD_GATE:EDIT_VERIFY] File not found: ${path.basename(filePath)} (${errStr})`);
+        // File doesn't exist - let edit operation proceed
+        return;
+      } else if (errStr.includes('UTF-8') || errStr.includes('encoding')) {
+        logger?.error?.(`[PD_GATE:EDIT_VERIFY] Encoding error reading file: ${path.basename(filePath)} (${errStr})`);
+        return {
+          block: true,
+          blockReason: `[P-03 Error] Encoding error: Cannot read file ${absolutePath}\n\nError: ${errStr}\n\nThe file appears to use an encoding other than UTF-8. Edit verification requires UTF-8 readable text files.\n\nSolution: Ensure file is UTF-8 encoded text, or mark binary extensions to skip verification.`
+        };
+      } else {
+        logger?.warn?.(`[PD_GATE:EDIT_VERIFY] Read error: ${errStr}`);
+        // Let it fail naturally
+        return;
+      }
+    }
+
+    // 4. Verify oldText exists in current content
+    if (!currentContent.includes(oldText)) {
+      logger?.info?.(`[PD_GATE:EDIT_VERIFY] Exact match failed for ${path.basename(filePath)}, trying fuzzy match`);
+
+      // 5. Try fuzzy matching (if enabled)
+      if (fuzzyMatchEnabled) {
+        const fuzzyResult = tryFuzzyMatch(currentContent, oldText, fuzzyMatchThreshold);
+
+        if (fuzzyResult.found && fuzzyResult.correctedText) {
+          logger?.info?.(`[PD_GATE:EDIT_VERIFY] Fuzzy match found for ${path.basename(filePath)}, auto-correcting oldText`);
+
+          // Return corrected parameters
+          return {
+            params: {
+              ...event.params,
+              oldText: fuzzyResult.correctedText,
+              old_string: fuzzyResult.correctedText
+            }
+          };
+        }
+      }
+
+      // 6. No match found, block operation with helpful error
+      const errorMsg = generateEditError(absolutePath, oldText, currentContent);
+
+      logger?.error?.(`[PD_GATE:EDIT_VERIFY] Block edit on ${path.basename(filePath)}: oldText not found`);
+
+      return {
+        block: true,
+        blockReason: errorMsg
+      };
+    }
+
+    // 7. Verification passed, allow edit to proceed
+    logger?.info?.(`[PD_GATE:EDIT_VERIFY] Verified edit on ${path.basename(filePath)}`);
+    return;
+
+  } catch (error) {
+    // Unexpected error - let it fail naturally
+    const errorStr = error instanceof Error ? error.message : String(error);
+    logger?.warn?.(`[PD_GATE:EDIT_VERIFY] Unexpected error: ${errorStr}`);
+    return;
+  }
+}