principles-disciple 1.7.5 → 1.7.8

package/dist/core/workspace-context.js

@@ -3,7 +3,6 @@ import { PathResolver } from './path-resolver.js';
 import { ConfigService } from './config-service.js';
 import { EventLogService } from './event-log.js';
 import { DictionaryService } from './dictionary-service.js';
-import { TrustEngine } from './trust-engine.js';
 import { HygieneTracker } from './hygiene/tracker.js';
 import { EvolutionReducerImpl } from './evolution-reducer.js';
 import { TrajectoryRegistry } from './trajectory.js';
@@ -19,7 +18,6 @@ export class WorkspaceContext {
     _config;
     _eventLog;
     _dictionary;
-    _trust;
     _hygiene;
     _evolutionReducer;
     _trajectory;
@@ -54,15 +52,6 @@ export class WorkspaceContext {
         }
         return this._dictionary;
     }
-    /**
-     * Trust engine service bound to this workspace.
-     */
-    get trust() {
-        if (!this._trust) {
-            this._trust = new TrustEngine(this.workspaceDir);
-        }
-        return this._trust;
-    }
     /**
      * Hygiene tracking service for this workspace.
      */
@@ -148,7 +137,6 @@ export class WorkspaceContext {
         this._config = undefined;
         this._eventLog = undefined;
         this._dictionary = undefined;
-        this._trust = undefined;
         this._evolutionReducer = undefined;
         this._trajectory = undefined;
     }

package/dist/hooks/bash-risk.d.ts

@@ -0,0 +1,57 @@
+/**
+ * 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
+ */
+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 declare function analyzeBashCommand(command: string, safePatterns: string[], dangerousPatterns: string[], logger?: {
+    warn?: (message: string) => void;
+}): BashRiskLevel;
+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 declare function calculateDynamicThreshold(baseThreshold: number, epTier: number, lineChanges: number, config: DynamicThresholdConfig): number;

package/dist/hooks/bash-risk.js

@@ -0,0 +1,137 @@
+/**
+ * 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
+ */
+/**
+ * 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, safePatterns, dangerousPatterns, logger) {
+    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 = {
+        'а': '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';
+}
+/**
+ * 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, epTier, lineChanges, config) {
+    // 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/dist/hooks/edit-verification.d.ts

@@ -0,0 +1,62 @@
+/**
+ * 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 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 declare function normalizeLine(line: string): string;
+/**
+ * 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 declare function findFuzzyMatch(lines: string[], oldLines: string[], threshold?: number): number;
+/**
+ * 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 declare function tryFuzzyMatch(currentContent: string, oldText: string, threshold?: number): {
+    found: boolean;
+    correctedText?: string;
+};
+/**
+ * Generate a helpful error message for edit verification failure
+ */
+export declare function generateEditError(filePath: string, oldText: string, currentContent: string): string;
+/**
+ * Handle edit tool verification before allowing operation
+ * This enforces P-03 at the tool layer
+ */
+export declare function handleEditVerification(event: PluginHookBeforeToolCallEvent, wctx: WorkspaceContext, ctx: {
+    logger?: any;
+    sessionId?: string;
+}, config?: EditVerificationConfig): PluginHookBeforeToolCallResult | void;

package/dist/hooks/edit-verification.js

@@ -0,0 +1,256 @@
+/**
+ * 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';
+/**
+ * Normalize a line for fuzzy matching by collapsing whitespace
+ */
+export function normalizeLine(line) {
+    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, oldLines, threshold = 0.8) {
+    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, oldText, threshold = 0.8) {
+    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, oldText, currentContent) {
+    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, wctx, ctx, config = {}) {
+    // 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 = 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;
+    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.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;
+        try {
+            currentContent = fs.readFileSync(absolutePath, 'utf-8');
+        }
+        catch (readError) {
+            const errStr = readError instanceof Error ? readError.message : String(readError);
+            const errCode = readError.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;
+    }
+}

package/dist/hooks/gate-block-helper.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Gate Block Helper - Single Authoritative Block Persistence
+ *
+ * PURPOSE: Provide ONE authoritative implementation for gate block persistence.
+ *
+ * All gate modules (progressive-trust-gate, gfi-gate, etc.) must use this
+ * helper to ensure consistent block tracking, event logging, and retry behavior.
+ *
+ * This eliminates the "multi-truth source" problem where different modules
+ * had their own block persistence implementations.
+ */
+import type { WorkspaceContext } from '../core/workspace-context.js';
+import type { PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
+/**
+ * Block context containing all information needed for block persistence
+ */
+export interface BlockContext {
+    filePath: string;
+    reason: string;
+    toolName: string;
+    sessionId?: string;
+    /** Source module that triggered the block (for audit trail) */
+    blockSource?: string;
+}
+/**
+ * Single authoritative block helper.
+ *
+ * Responsibilities:
+ * 1. Call trackBlock() for session-level GFI tracking
+ * 2. Record to EventLog for operator visibility
+ * 3. Record to trajectory for analytics
+ * 4. Handle retry logic for trajectory persistence failures
+ * 5. Generate consistent operator-facing block message
+ *
+ * @param wctx - Workspace context
+ * @param blockCtx - Block context with file, reason, tool info
+ * @param logger - Logger instance
+ * @returns PluginHookBeforeToolCallResult with block=true
+ */
+export declare function recordGateBlockAndReturn(wctx: WorkspaceContext, blockCtx: BlockContext, logger: {
+    warn?: (message: string) => void;
+    error?: (message: string) => void;
+    info?: (message: string) => void;
+}): PluginHookBeforeToolCallResult;