principles-disciple 1.5.4

package/dist/hooks/gate.js

@@ -0,0 +1,487 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { isRisky, normalizePath, planStatus as getPlanStatus } from '../utils/io.js';
+import { matchesAnyPattern } from '../utils/glob-match.js';
+import { normalizeProfile } from '../core/profile.js';
+import { trackBlock, hasRecentThinking } from '../core/session-tracker.js';
+import { assessRiskLevel, estimateLineChanges } from '../core/risk-calculator.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import { checkEvolutionGate } from '../core/evolution-engine.js';
+export function handleBeforeToolCall(event, ctx) {
+    const logger = ctx.logger || console;
+    // 1. Identify tool type
+    const WRITE_TOOLS = ['write', 'edit', 'apply_patch', 'write_file', 'replace', 'insert', 'patch', 'edit_file', 'delete_file', 'move_file'];
+    const BASH_TOOLS = ['bash', 'run_shell_command', 'exec', 'execute', 'shell', 'cmd'];
+    const AGENT_TOOLS = ['pd_spawn_agent', 'sessions_spawn'];
+    const isBash = BASH_TOOLS.includes(event.toolName);
+    const isWriteTool = WRITE_TOOLS.includes(event.toolName);
+    const isAgentTool = AGENT_TOOLS.includes(event.toolName);
+    // Profile loaded first for config-driven behavior (see below)
+    if (!ctx.workspaceDir || (!isWriteTool && !isBash && !isAgentTool)) {
+        return;
+    }
+    const wctx = WorkspaceContext.fromHookContext(ctx);
+    // 2. Load Profile
+    const profilePath = wctx.resolve('PROFILE');
+    let profile = {
+        risk_paths: [],
+        gate: { require_plan_for_risk_paths: true },
+        progressive_gate: {
+            enabled: true,
+            plan_approvals: {
+                enabled: false,
+                max_lines_override: -1,
+                allowed_patterns: [],
+                allowed_operations: [],
+            }
+        },
+        edit_verification: {
+            enabled: true,
+            max_file_size_bytes: 10 * 1024 * 1024,
+            fuzzy_match_enabled: true,
+            fuzzy_match_threshold: 0.8,
+            skip_large_file_action: 'warn',
+        },
+        thinking_checkpoint: {
+            enabled: false, // Default OFF
+            window_ms: 5 * 60 * 1000,
+            high_risk_tools: ['run_shell_command', 'delete_file', 'move_file', 'pd_spawn_agent'],
+        }
+    };
+    if (fs.existsSync(profilePath)) {
+        try {
+            const rawProfile = JSON.parse(fs.readFileSync(profilePath, 'utf8'));
+            profile = normalizeProfile(rawProfile);
+        }
+        catch (e) {
+            logger?.error?.(`[PD_GATE] Failed to parse PROFILE.json: ${String(e)}`);
+        }
+    }
+    // ═══ THINKING OS CHECKPOINT (P-10) — Config-gated ═══
+    // Only enforced when thinking_checkpoint.enabled = true in PROFILE.json
+    const isHighRisk = profile.thinking_checkpoint?.high_risk_tools?.includes(event.toolName) ?? false;
+    if (profile.thinking_checkpoint?.enabled && isHighRisk && ctx.sessionId) {
+        const windowMs = profile.thinking_checkpoint.window_ms ?? 5 * 60 * 1000;
+        const hasThinking = hasRecentThinking(ctx.sessionId, windowMs);
+        if (!hasThinking) {
+            logger?.info?.(`[PD:THINKING_GATE] High-risk tool "${event.toolName}" called without recent deep thinking`);
+            return {
+                block: true,
+                blockReason: `[Thinking OS Checkpoint] 高风险操作 "${event.toolName}" 需要先进行深度思考。\n\n请先使用 deep_reflect 工具分析当前情况，然后再尝试此操作。\n\n这是强制性检查点，目的是确保决策质量。\n\n提示：调用 deep_reflect 后，${Math.round(windowMs / 60000)}分钟内的操作将自动放行。\n\n可在PROFILE.json中设置 thinking_checkpoint.enabled: false 来禁用此检查。`,
+            };
+        }
+    }
+    // Merge pluginConfig (OpenClaw UI settings)
+    const configRiskPaths = ctx.pluginConfig?.riskPaths ?? [];
+    if (configRiskPaths.length > 0) {
+        profile.risk_paths = [...new Set([...profile.risk_paths, ...configRiskPaths])];
+    }
+    // 3. Resolve the target file path
+    let filePath = event.params.file_path || event.params.path || event.params.file || event.params.target;
+    // Heuristic for bash mutation detection
+    if (isBash && !filePath) {
+        const command = String(event.params.command || event.params.args || "");
+        const mutationMatch = command.match(/(?:>|>>|sed\s+-i|rm|mv|mkdir|touch|cp)\s+(?:-[a-zA-Z]+\s+)*([^\s;&|<>]+)/);
+        if (mutationMatch) {
+            filePath = mutationMatch[1];
+        }
+        else {
+            const hasRiskPath = profile.risk_paths.some(rp => command.includes(rp));
+            const isMutation = /(?:>|>>|sed|rm|mv|mkdir|touch|cp|npm|yarn|pnpm|pip|cargo)/.test(command);
+            if (hasRiskPath && isMutation) {
+                filePath = command;
+            }
+            else {
+                return;
+            }
+        }
+    }
+    if (typeof filePath !== 'string')
+        return;
+    const relPath = normalizePath(filePath, ctx.workspaceDir);
+    const risky = (isBash && filePath.includes(' '))
+        ? profile.risk_paths.some(rp => filePath.includes(rp))
+        : isRisky(relPath, profile.risk_paths);
+    // ── PROGRESSIVE GATE LOGIC ──
+    if (profile.progressive_gate?.enabled) {
+        const trustEngine = wctx.trust;
+        const trustScore = trustEngine.getScore();
+        const stage = trustEngine.getStage();
+        const trustSettings = wctx.config.get('trust') || {
+            limits: { stage_2_max_lines: 50, stage_3_max_lines: 300 }
+        };
+        const riskLevel = assessRiskLevel(relPath, { toolName: event.toolName, params: event.params }, profile.risk_paths);
+        const lineChanges = estimateLineChanges({ toolName: event.toolName, params: event.params });
+        logger.info(`[PD_GATE] Trust: ${trustScore} (Stage ${stage}), Risk: ${riskLevel}, Path: ${relPath}`);
+        // Stage 1 (Bankruptcy): Block ALL writes to risk paths, and all medium+ writes
+        if (stage === 1) {
+            if (risky || riskLevel !== 'LOW') {
+                // Check if PLAN whitelist is enabled
+                if (profile.progressive_gate?.plan_approvals?.enabled) {
+                    const planApprovals = profile.progressive_gate.plan_approvals;
+                    const planStatus = getPlanStatus(ctx.workspaceDir);
+                    // Must have READY plan
+                    if (planStatus === 'READY') {
+                        // Check operation type
+                        if (planApprovals.allowed_operations?.includes(event.toolName)) {
+                            // Check path pattern
+                            if (matchesAnyPattern(relPath, planApprovals.allowed_patterns || [])) {
+                                // Check line limit (if configured)
+                                const maxLines = planApprovals.max_lines_override ?? -1;
+                                if (maxLines === -1 || lineChanges <= maxLines) {
+                                    // Record PLAN approval event
+                                    wctx.eventLog.recordPlanApproval(ctx.sessionId, {
+                                        toolName: event.toolName,
+                                        filePath: relPath,
+                                        pattern: relPath,
+                                        planStatus
+                                    });
+                                    logger.info(`[PD_GATE] Stage 1 PLAN approval: ${relPath}`);
+                                    return; // Allow the operation
+                                }
+                            }
+                        }
+                    }
+                }
+                // Block if not approved by whitelist
+                return block(relPath, `Trust score too low (${trustScore}). Stage 1 agents cannot modify risk paths or perform non-trivial edits.`, wctx, event.toolName);
+            }
+        }
+        // Stage 2 (Editor): Block writes to risk paths. Block large changes.
+        if (stage === 2) {
+            if (risky) {
+                return block(relPath, `Stage 2 agents are not authorized to modify risk paths.`, wctx, event.toolName);
+            }
+            const stage2Limit = trustSettings.limits?.stage_2_max_lines ?? 50;
+            if (lineChanges > stage2Limit) {
+                return block(relPath, `Modification too large (${lineChanges} lines) for Stage 2. Max allowed is ${stage2Limit}.`, wctx, event.toolName);
+            }
+        }
+        // Stage 3 (Developer): Allow normal writes. Require READY plan for risk paths.
+        if (stage === 3) {
+            if (risky) {
+                const planStatus = getPlanStatus(ctx.workspaceDir);
+                if (planStatus !== 'READY') {
+                    return block(relPath, `No READY plan found. Stage 3 requires a plan for risk path modifications.`, wctx, event.toolName);
+                }
+            }
+            const stage3Limit = trustSettings.limits?.stage_3_max_lines ?? 300;
+            if (lineChanges > stage3Limit) {
+                return block(relPath, `Modification too large (${lineChanges} lines) for Stage 3. Max allowed is ${stage3Limit}.`, wctx, event.toolName);
+            }
+        }
+        // Stage 4 (Architect): Full bypass
+        if (stage === 4) {
+            logger.info(`[PD_GATE] Trusted Architect bypass for ${relPath}`);
+            return;
+        }
+        // ── EP SIMULATION MODE (M6验证) ──
+        // 记录EP系统的模拟决策，但不生效（仅用于对比分析）
+        try {
+            const epDecision = checkEvolutionGate(ctx.workspaceDir, {
+                toolName: event.toolName,
+                content: event.params?.content,
+                lineCount: lineChanges,
+                isRiskPath: risky,
+            });
+            const epLogEntry = {
+                timestamp: new Date().toISOString(),
+                toolName: event.toolName,
+                filePath: relPath,
+                trustEngine: { score: trustScore, stage, decision: 'allow' },
+                epSystem: { tier: epDecision.currentTier ?? 'UNKNOWN', allowed: epDecision.allowed, reason: epDecision.reason },
+                conflict: epDecision.allowed === false, // Trust允许但EP拒绝（任何阶段）
+            };
+            const epLogPath = path.join(ctx.workspaceDir, '.state', 'ep_simulation.jsonl');
+            // 安全创建目录（如果失败则跳过日志写入，但不影响 Trust Engine 决策）
+            let canWriteEpLog = true;
+            try {
+                fs.mkdirSync(path.dirname(epLogPath), { recursive: true });
+            }
+            catch (mkdirErr) {
+                if (!mkdirErr || mkdirErr.code !== 'EEXIST') {
+                    logger.warn(`[PD_EP_SIM] Failed to create log dir: ${mkdirErr?.message ?? String(mkdirErr)}, skipping log`);
+                    canWriteEpLog = false;
+                }
+            }
+            if (canWriteEpLog) {
+                fs.appendFileSync(epLogPath, JSON.stringify(epLogEntry) + '\n');
+            }
+            logger.info(`[PD_EP_SIM] Tier: ${epDecision.currentTier}, Allowed: ${epDecision.allowed}, Trust: ${trustScore} (Stage ${stage})`);
+        }
+        catch (err) {
+            // EP 模拟失败不应该影响 Trust Engine 决策
+            const errMsg = err instanceof Error ? err.message : String(err);
+            logger.warn(`[PD_EP_SIM] Simulation failed: ${errMsg}, continuing with Trust Engine`);
+        }
+    }
+    else {
+        // FALLBACK: Legacy Gate Logic
+        if (risky && profile.gate?.require_plan_for_risk_paths) {
+            const planStatus = getPlanStatus(ctx.workspaceDir);
+            if (planStatus !== 'READY') {
+                return block(relPath, `No READY plan found in PLAN.md.`, wctx, event.toolName);
+            }
+        }
+    }
+    // ═══════════════════════════════════════════════════════════════
+    // P-03: Edit Tool Force Verification
+    // ═══════════════════════════════════════════════════════════════
+    // After all gate checks, verify edit operations (enforces P-03)
+    if (event.toolName === 'edit' && profile.edit_verification?.enabled !== false) {
+        const verifyResult = handleEditVerification(event, wctx, ctx, {
+            enabled: profile.edit_verification.enabled,
+            max_file_size_bytes: profile.edit_verification.max_file_size_bytes,
+            fuzzy_match_enabled: profile.edit_verification.fuzzy_match_enabled,
+            fuzzy_match_threshold: profile.edit_verification.fuzzy_match_threshold,
+            skip_large_file_action: profile.edit_verification.skip_large_file_action,
+        });
+        if (verifyResult) {
+            return verifyResult; // Block or modify params
+        }
+    }
+}
+function block(filePath, reason, wctx, toolName) {
+    const logger = console;
+    logger.error(`[PD_GATE] BLOCKED: ${filePath}. Reason: ${reason}`);
+    trackBlock(wctx.workspaceDir);
+    return {
+        block: true,
+        blockReason: `[Principles Disciple] Security Gate Blocked this action.\nFile: ${filePath}\nReason: ${reason}\n\nHint: You may need a READY plan or a higher trust score to perform this action.`,
+    };
+}
+// ═══════════════════════════════════════════════════════════════
+// P-03: Edit Tool Force Verification
+// ═══════════════════════════════════════════════════════════════
+/**
+ * Normalize a line for fuzzy matching by collapsing whitespace
+ */
+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
+ */
+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 the 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
+ */
+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
+ */
+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 the 'read' tool to get the current file content
+  2. Update your edit command with the exact text from the file
+  3. Retry the edit operation
+
+This is enforced by P-03 (精确匹配前验证原则).`;
+}
+/**
+ * Handle edit tool verification before allowing the operation
+ * This enforces P-03 at the tool layer
+ */
+function handleEditVerification(event, wctx, ctx, config = {}) {
+    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 the edit operation proceed (it will create the 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 the 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 the 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 the 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/lifecycle.d.ts

@@ -0,0 +1,5 @@
+import type { PluginHookBeforeResetEvent, PluginHookBeforeCompactionEvent, PluginHookAfterCompactionEvent, PluginHookAgentContext } from '../openclaw-sdk.js';
+export declare function handleBeforeReset(event: PluginHookBeforeResetEvent, ctx: PluginHookAgentContext): Promise<void>;
+export declare function extractPainFromSessionFile(sessionFile: string, ctx: PluginHookAgentContext): Promise<void>;
+export declare function handleBeforeCompaction(event: PluginHookBeforeCompactionEvent, ctx: PluginHookAgentContext): Promise<void>;
+export declare function handleAfterCompaction(event: PluginHookAfterCompactionEvent, ctx: PluginHookAgentContext): Promise<void>;

package/dist/hooks/lifecycle.js

@@ -0,0 +1,180 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import * as readline from 'readline';
+import { writePainFlag } from '../core/pain.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import { PD_DIRS } from '../core/paths.js';
+export async function handleBeforeReset(event, ctx) {
+    if (!ctx.workspaceDir || !event.messages || event.messages.length === 0) {
+        return;
+    }
+    const wctx = WorkspaceContext.fromHookContext(ctx);
+    // Auto-summarise pain points before the session is cleared
+    const painPoints = event.messages.filter((msg) => {
+        const m = msg;
+        return (m.role === 'assistant' &&
+            typeof m.content === 'string' &&
+            (m.content.includes('error') || m.content.includes('fail') || m.content.includes('blocked')));
+    });
+    if (painPoints.length > 0) {
+        const memoryPath = wctx.resolve('MEMORY_MD');
+        const summary = `\n## [${new Date().toISOString()}] Session Reset Summary (Reason: ${event.reason ?? 'Manual'})\n` +
+            `- Encountered ${painPoints.length} potential pain point(s) during this session.\n` +
+            `- Action: Consider running /reflection to solidify these into principles.\n`;
+        try {
+            fs.appendFileSync(memoryPath, summary, 'utf8');
+        }
+        catch (_e) {
+            console.error(`[PD:Lifecycle] Failed to write session reset summary: ${String(_e)}`);
+        }
+    }
+}
+export async function extractPainFromSessionFile(sessionFile, ctx) {
+    const painPoints = [];
+    const workspaceDir = ctx.workspaceDir;
+    if (!workspaceDir)
+        return;
+    const wctx = WorkspaceContext.fromHookContext(ctx);
+    if (!fs.existsSync(sessionFile)) {
+        if (ctx.logger?.debug)
+            ctx.logger.debug(`[Pain Extractor] Session file not found: ${sessionFile}`);
+        return;
+    }
+    if (ctx.logger)
+        ctx.logger.info(`[Pain Extractor] Scanning session transcript for pain signals: ${sessionFile}`);
+    const fileStream = fs.createReadStream(sessionFile);
+    const rl = readline.createInterface({
+        input: fileStream,
+        crlfDelay: Infinity
+    });
+    try {
+        for await (const line of rl) {
+            try {
+                if (!line.trim())
+                    continue;
+                const msg = JSON.parse(line);
+                if (msg.role !== 'assistant')
+                    continue;
+                let text = '';
+                if (typeof msg.content === 'string') {
+                    text = msg.content;
+                }
+                else if (Array.isArray(msg.content)) {
+                    text = msg.content
+                        .filter(c => c && c.type === 'text' && typeof c.text === 'string')
+                        .map(c => c.text)
+                        .join('\n');
+                }
+                else if (msg.usage && msg.usage.outputText) {
+                    text = msg.usage.outputText;
+                }
+                if (!text)
+                    continue;
+                if (msg.openclawAbort?.aborted) {
+                    const runIdSafe = msg.openclawAbort?.runId || 'unknown';
+                    if (ctx.logger)
+                        ctx.logger.info(`[Pain Extractor] Detected hard-abort snapshot (runId: ${runIdSafe})`);
+                    painPoints.push(`[FATAL INTERCEPT] 动作被沙箱防御机制强制击落。大模型被击落前的思考流 (未遂动机): ${text.substring(0, 250)}...`);
+                    continue;
+                }
+                if (msg.__openclaw?.truncated && msg.__openclaw?.reason === 'oversized') {
+                    if (ctx.logger)
+                        ctx.logger.info(`[Pain Extractor] Detected oversized data truncation placeholder`);
+                    painPoints.push(`[COGNITIVE OVERLOAD] 大模型尝试读取极大体积的输入，已被底层守护程序抹除/折叠防爆。请反思是否读取了不当的文件或日志: ${text.substring(0, 150)}...`);
+                    continue;
+                }
+                const lower = text.toLowerCase();
+                if (lower.includes('i\'m sorry, but i\'m still getting') ||
+                    lower.includes('i apologize for the confusion') ||
+                    lower.includes('this is taking longer than expected')) {
+                    if (ctx.logger?.debug)
+                        ctx.logger.debug(`[Pain Extractor] Detected semantic confusion string.`);
+                    painPoints.push(`[SEMANTIC CONFUSION] ${text.substring(0, 150)}...`);
+                }
+            }
+            catch (e) {
+                console.error(`[PD:Lifecycle] Error parsing message: ${String(e)}`);
+            }
+        }
+    }
+    finally {
+        try {
+            rl.close();
+            fileStream.destroy();
+        }
+        catch (_e) {
+            // Ignore cleanup errors
+        }
+    }
+    if (painPoints.length > 0) {
+        const dateStr = new Date().toISOString().split('T')[0];
+        const dailyLogPath = path.join(workspaceDir, PD_DIRS.MEMORY, `${dateStr}.md`);
+        const timestamp = new Date().toISOString();
+        let entry = `\n## [${timestamp}] Consolidated Pain (Pre-Compaction)\n\n`;
+        entry += `### Pain Signals extracted from session transcript\n`;
+        painPoints.slice(-5).forEach((p, idx) => {
+            entry += `- [Signal ${idx + 1}] ${p.replace(/\n/g, ' ')}\n`;
+        });
+        entry += `\n### Diagnosis (Pending)\n- Run /evolve-task to diagnose. Deep dive using memory_search if needed.\n`;
+        try {
+            const dir = path.dirname(dailyLogPath);
+            if (!fs.existsSync(dir))
+                fs.mkdirSync(dir, { recursive: true });
+            fs.appendFileSync(dailyLogPath, entry, 'utf8');
+            const semanticPath = wctx.resolve('SEMANTIC_PAIN');
+            const semanticDir = path.dirname(semanticPath);
+            if (!fs.existsSync(semanticDir))
+                fs.mkdirSync(semanticDir, { recursive: true });
+            let semanticEntry = `\n### Sample ${timestamp}\n- Source: compaction\n\n\`\`\`\n${painPoints.join('\n---\n')}\n\`\`\`\n`;
+            fs.appendFileSync(semanticPath, semanticEntry, 'utf8');
+            const hasFatal = painPoints.some(p => p.includes('[FATAL INTERCEPT]'));
+            if (hasFatal) {
+                writePainFlag(workspaceDir, {
+                    source: 'intercept_extraction',
+                    score: '100',
+                    time: new Date().toISOString(),
+                    reason: 'Hard intercept detected in session history compaction.',
+                    is_risky: 'true',
+                    trigger_text_preview: painPoints.find(p => p.includes('[FATAL INTERCEPT]'))?.substring(0, 150) || 'Fatal intercept'
+                });
+            }
+        }
+        catch (err) {
+            console.error(`[PD:Lifecycle] Failed to write pain signals: ${String(err)}`);
+        }
+    }
+}
+export async function handleBeforeCompaction(event, ctx) {
+    if (!ctx.workspaceDir)
+        return;
+    const dateStr = new Date().toISOString().split('T')[0];
+    const checkpointPath = path.join(ctx.workspaceDir, PD_DIRS.MEMORY, `${dateStr}.md`);
+    const log = `\n## [${new Date().toISOString()}] Pre-Compaction Checkpoint\n` +
+        `- Compacting session with ${event.messageCount} messages.\n` +
+        `- Ensuring critical state is flushed to disk.\n`;
+    try {
+        const dir = path.dirname(checkpointPath);
+        if (!fs.existsSync(dir))
+            fs.mkdirSync(dir, { recursive: true });
+        fs.appendFileSync(checkpointPath, log, 'utf8');
+    }
+    catch (_e) {
+        console.error(`[PD:Lifecycle] Failed to write pre-compaction checkpoint: ${String(_e)}`);
+    }
+    if (event.sessionFile) {
+        await extractPainFromSessionFile(event.sessionFile, ctx);
+    }
+}
+export async function handleAfterCompaction(event, ctx) {
+    if (!ctx.workspaceDir)
+        return;
+    const dateStr = new Date().toISOString().split('T')[0];
+    const checkpointPath = path.join(ctx.workspaceDir, PD_DIRS.MEMORY, `${dateStr}.md`);
+    const log = `- Post-Compaction Complete. Reduced active context to ${event.messageCount} messages.\n`;
+    try {
+        fs.appendFileSync(checkpointPath, log, 'utf8');
+    }
+    catch (_e) {
+        console.error(`[PD:Lifecycle] Failed to write post-compaction checkpoint: ${String(_e)}`);
+    }
+}

package/dist/hooks/llm.d.ts

@@ -0,0 +1,4 @@
+import { PluginHookLlmOutputEvent, PluginHookAgentContext } from '../openclaw-sdk.js';
+export declare function handleLlmOutput(event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext & {
+    workspaceDir?: string;
+}): void;