principles-disciple 1.126.0 → 1.128.0

package/dist/hooks/gate-block-helper.js

@@ -0,0 +1,209 @@
+/**
+ * Gate Block Helper - Single Authoritative Block Persistence
+ *
+ * PURPOSE: Provide ONE authoritative implementation for gate block persistence.
+ *
+ * All gate sources (rule-host) 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 * as fs from 'fs';
+import { getSession, trackBlock } from '../core/session-tracker.js';
+import { evaluatePainDiagnosticGate } from '../core/pain-diagnostic-gate.js';
+import { emitPainDetectedEvent } from './pain.js';
+import { loadFeatureFlagFromConfig } from '../core/pd-config-loader.js';
+import { evaluateEvidenceTriage } from './triage-adapter.js';
+import { isRisky } from '../utils/io.js';
+import { normalizeProfile } from '../core/profile.js';
+import { SystemLogger } from '../core/system-logger.js';
+import { TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS, TRAJECTORY_GATE_BLOCK_MAX_RETRIES } from '../config/index.js';
+/**
+ * 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 function recordGateBlockAndReturn(wctx, blockCtx, logger) {
+    const { filePath, reason, toolName, sessionId, blockSource } = blockCtx;
+    // Default logger if not provided
+    const logWarn = (msg) => logger.warn?.(msg);
+    const logError = (msg) => logger.error?.(msg);
+    // Log the block event
+    const sourceTag = blockSource ? `[${blockSource}]` : '';
+    logError(`[PD_GATE]${sourceTag} BLOCKED: ${filePath}. Reason: ${reason}`);
+    // 1. Track block for session-level GFI calculation
+    if (sessionId) {
+        trackBlock(sessionId);
+    }
+    // 2. Prepare trajectory payload
+    const trajectoryPayload = {
+        sessionId: sessionId ?? null,
+        toolName,
+        filePath,
+        reason,
+        blockSource: blockSource ?? 'gate',
+    };
+    // 3. Record to EventLog (primary persistence)
+    try {
+        wctx.eventLog.recordGateBlock(sessionId, {
+            toolName,
+            filePath,
+            reason,
+            blockSource: blockSource ?? 'gate',
+        });
+    }
+    catch (error) {
+        logWarn(`[PD_GATE] Failed to record gate block event: ${String(error)}`);
+    }
+    // 4. Record to trajectory (secondary persistence with retry)
+    try {
+        wctx.trajectory?.recordGateBlock?.(trajectoryPayload);
+    }
+    catch (error) {
+        logWarn(`[PD_GATE] Failed to record trajectory gate block: ${String(error)}`);
+        scheduleTrajectoryGateBlockRetry(wctx, trajectoryPayload, 1, logWarn, logError);
+    }
+    // 5. Record gate block pain context. Runtime V2 diagnosis is gated by GFI
+    // so one mild block does not start a long diagnostician run.
+    if (sessionId) {
+        const GATE_BLOCK_PAIN_SCORE = 45; // Must be >= pain_trigger (40) so single gate block can trigger diagnosis (PRI-274)
+        // Record to trajectory (fire-and-forget, no .pain_flag file needed)
+        wctx.trajectory?.recordPainEvent?.({
+            sessionId,
+            source: 'gate_blocked',
+            score: GATE_BLOCK_PAIN_SCORE,
+            reason: `Gate blocked ${toolName} on ${filePath}: ${reason}`,
+            severity: 'mild',
+            origin: 'system_infer',
+        });
+        // PEAT-B1: Evidence triage (feature-flagged)
+        let triageAdmitted = true;
+        const gateBlockTriageFlag = loadFeatureFlagFromConfig(wctx.workspaceDir, 'painEvidenceAdmission');
+        if (gateBlockTriageFlag.enabled) {
+            // Load profile with 1MB size guard, matching pain.ts pattern
+            const profilePath = wctx.resolve('PROFILE');
+            let profile = normalizeProfile({});
+            if (fs.existsSync(profilePath)) {
+                try {
+                    const content = fs.readFileSync(profilePath, 'utf8');
+                    if (content.length > 1024 * 1024) {
+                        logger.warn?.('[PD_GATE] PROFILE.json exceeds 1 MB, skipping');
+                        SystemLogger.log(wctx.workspaceDir, 'PROFILE_PARSE_WARN', 'PROFILE.json exceeds 1 MB, skipping — fallback to non-risky');
+                    }
+                    else {
+                        profile = normalizeProfile(JSON.parse(content));
+                    }
+                }
+                catch (e) {
+                    logger.warn?.(`[PD_GATE] Failed to parse PROFILE.json: ${String(e)}`);
+                    SystemLogger.log(wctx.workspaceDir, 'PROFILE_PARSE_WARN', `Failed to parse PROFILE.json: ${String(e)} — fallback to non-risky`);
+                }
+            }
+            // Real judgment for rulehost blocks: if a principle blocked an action on a risky path,
+            // it IS a high-confidence unsafe action. The pain score (45) is the evidence friction
+            // weight, NOT the action risk severity. The rulehost principle already determined
+            // this action was important enough to block — that is the real signal.
+            const isUnsafe = isRisky(filePath, profile.risk_paths);
+            const triage = evaluateEvidenceTriage('rulehost_block', GATE_BLOCK_PAIN_SCORE, {
+                isUnsafeHighConfidence: isUnsafe,
+            });
+            if (triage.decision !== 'admit') {
+                triageAdmitted = false;
+                logger.info?.(`[PD_GATE] Triage ${triage.decision}: ${triage.reason}`);
+            }
+        }
+        const session = getSession(sessionId);
+        if (triageAdmitted) {
+            const gate = evaluatePainDiagnosticGate({
+                source: 'gate_blocked',
+                score: GATE_BLOCK_PAIN_SCORE,
+                currentGfi: session?.currentGfi ?? 0,
+                consecutiveErrors: session?.consecutiveErrors ?? 0,
+                sessionId,
+                errorHash: `${toolName}:${filePath}:${reason}`,
+                thresholds: {
+                    painTrigger: wctx.config.get('thresholds.pain_trigger') || 40,
+                    highSeverity: wctx.config.get('severity_thresholds.high') || 70,
+                },
+            });
+            if (gate.shouldDiagnose) {
+                void emitPainDetectedEvent(wctx, {
+                    ts: new Date().toISOString(),
+                    type: 'pain_detected',
+                    data: {
+                        painId: `gate_${Date.now()}_${Math.random().toString(36).slice(2, 10)}`,
+                        painType: 'user_frustration',
+                        source: 'gate_blocked',
+                        reason: `Gate blocked ${toolName} on ${filePath}: ${reason}`,
+                        score: GATE_BLOCK_PAIN_SCORE,
+                        sessionId,
+                        agentId: 'main',
+                    },
+                }).catch((emitErr) => {
+                    logWarn(`[PD_GATE] Failed to emit gate block pain event: ${String(emitErr)}`);
+                });
+            }
+            else {
+                logger.info?.(`[PD_GATE] Gate block recorded without Runtime V2 diagnosis: ${gate.detail}`);
+            }
+        }
+    }
+    // 6. Return consistent block result with contextual operator guidance
+    const blockMessage = buildContextualBlockMessage({ filePath, reason });
+    return {
+        block: true,
+        blockReason: blockMessage,
+    };
+}
+/**
+ * Build contextual block message based on block source.
+ * - rule-host: principle-based guidance
+ * - default/gate: generic security gate message
+ */
+function buildContextualBlockMessage({ filePath, reason, }) {
+    // rule-host or generic gate blocks
+    return `[Principles Disciple] Security Gate Blocked this action.
+File: ${filePath}
+Reason: ${reason}
+
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+📋 How to unblock this operation:
+
+This action was blocked by a Rule Host principle.
+If the blocked path is correct and safe, explain the reasoning to the owner
+and ask for explicit confirmation to proceed.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`;
+}
+/**
+ * Schedule retry for trajectory gate block persistence.
+ *
+ * Uses exponential backoff with max retries.
+ * Failures are logged but do not affect the runtime block decision.
+ */
+function scheduleTrajectoryGateBlockRetry(wctx, payload, attempt, logWarn, logError) {
+    if (attempt > TRAJECTORY_GATE_BLOCK_MAX_RETRIES) {
+        logError(`[PD_GATE] Failed to persist trajectory gate block after ${TRAJECTORY_GATE_BLOCK_MAX_RETRIES} retries: ${payload.toolName} ${payload.filePath}`);
+        return;
+    }
+    setTimeout(() => {
+        try {
+            wctx.trajectory?.recordGateBlock?.(payload);
+            logWarn(`[PD_GATE] Trajectory gate block persisted on retry ${attempt}`);
+        }
+        catch (error) {
+            logWarn(`[PD_GATE] Retrying trajectory gate block persistence (attempt ${attempt + 1}): ${String(error)}`);
+            scheduleTrajectoryGateBlockRetry(wctx, payload, attempt + 1, logWarn, logError);
+        }
+    }, TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS * attempt).unref();
+}

package/dist/hooks/gate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * Security Gate Hook - Rule Host Only
+ *
+ * This is the SINGLE AUTHORITATIVE orchestration path.
+ * All blocking logic is now dynamic via Rule Host — no hardcoded gates remain.
+ *
+ * Flow:
+ * 1. Early Return: Skip if not write/bash/agent tool or no workspace
+ * 2. Rule Host: Dynamic principle-based evaluation (sole gate)
+ */
+import type { PluginHookBeforeToolCallEvent, PluginHookToolContext, PluginHookBeforeToolCallResult, PluginLogger } from '../openclaw-sdk.js';
+export declare function handleBeforeToolCall(event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext & {
+    workspaceDir?: string;
+    pluginConfig?: Record<string, unknown>;
+    logger?: Partial<PluginLogger>;
+}): PluginHookBeforeToolCallResult | void;

package/dist/hooks/gate.js

@@ -0,0 +1,381 @@
+/**
+ * Security Gate Hook - Rule Host Only
+ *
+ * This is the SINGLE AUTHORITATIVE orchestration path.
+ * All blocking logic is now dynamic via Rule Host — no hardcoded gates remain.
+ *
+ * Flow:
+ * 1. Early Return: Skip if not write/bash/agent tool or no workspace
+ * 2. Rule Host: Dynamic principle-based evaluation (sole gate)
+ */
+import { normalizePath } from '../utils/io.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+import { recordGateBlockAndReturn } from './gate-block-helper.js';
+import { RuleHost } from '../core/rule-host.js';
+import { validateCorrectionProposal, validateProposedPathBounds } from '@principles/core/runtime-v2';
+import { AGENT_TOOLS, BASH_TOOLS_SET, WRITE_TOOLS } from '../constants/tools.js';
+import { getSession, hasRecentThinking } from '../core/session-tracker.js';
+import { getEvolutionEngine } from '../core/evolution-engine.js';
+import { EventLogService } from '../core/event-log.js';
+import { estimateLineChanges } from '../core/risk-calculator.js';
+export function handleBeforeToolCall(event, ctx) {
+    const logger = ctx.logger || console;
+    // 1. Identify tool type
+    const isBash = BASH_TOOLS_SET.has(event.toolName);
+    const isWriteTool = WRITE_TOOLS.has(event.toolName);
+    const isAgentTool = AGENT_TOOLS.has(event.toolName);
+    if (!ctx.workspaceDir || (!isWriteTool && !isBash && !isAgentTool)) {
+        return;
+    }
+    const wctx = WorkspaceContext.fromHookContext(ctx);
+    // 2. 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 = /(?:>|>>|sed\s+-i|rm|mv|mkdir|touch|cp)\s+(?:-[a-zA-Z]+\s+)*([^\s;&|<>]+)/.exec(command);
+        if (mutationMatch) {
+            filePath = mutationMatch[1];
+        }
+        else {
+            // Bash command without a clear file target — let it through to Rule Host
+            filePath = command;
+        }
+    }
+    // Write tools without a file path must still go through RuleHost evaluation.
+    // Use a synthetic path so RuleHost can evaluate and potentially block.
+    if (!filePath && isWriteTool) {
+        filePath = `<tool:${event.toolName}>`;
+    }
+    if (typeof filePath !== 'string')
+        return;
+    const relPath = normalizePath(filePath, ctx.workspaceDir);
+    // 3. Rule Host Evaluation — sole gate
+    try {
+        const ruleHost = new RuleHost(wctx.stateDir, logger, { workspaceDir: ctx.workspaceDir });
+        const hostInput = {
+            action: {
+                toolName: event.toolName,
+                normalizedPath: relPath,
+                paramsSummary: _extractParamsSummary(event.params ?? {}),
+            },
+            workspace: {
+                isRiskPath: false, // Rule Host determines risk dynamically
+                // DEPRECATED (PRI-286): planStatus/hasPlanFile are legacy compatibility fields.
+                // Live PD no longer reads or manages PLAN.md state. These fields must not be
+                // used for new MVP behavior. Future "plan-first" enforcement must come from
+                // owner-approved RuleHost/code_tool_hook activation, not built-in state.
+                planStatus: 'NONE',
+                hasPlanFile: false,
+            },
+            session: {
+                sessionId: ctx.sessionId,
+                currentGfi: _getCurrentGfi(ctx.sessionId),
+                recentThinking: _hasRecentThinking(ctx.sessionId),
+            },
+            evolution: {
+                epTier: _getEpTier(wctx.workspaceDir),
+            },
+            derived: {
+                estimatedLineChanges: estimateLineChanges({ toolName: event.toolName, params: event.params ?? {} }),
+                bashRisk: _getBashRisk(event),
+            },
+        };
+        const hostResult = ruleHost.evaluate(hostInput);
+        // Always emit rulehost_evaluated
+        try {
+            const eventLog = EventLogService.get(wctx.stateDir, logger);
+            eventLog.recordRuleHostEvaluated({
+                toolName: event.toolName,
+                filePath: relPath,
+                matched: hostResult?.matched ?? false,
+                decision: hostResult?.decision ?? 'allow',
+                ruleId: hostResult?.ruleId,
+            });
+        }
+        catch (evErr) {
+            logger?.warn?.(`[PD_GATE] Failed to record rulehost_evaluated: ${String(evErr)}`);
+        }
+        if (hostResult?.decision === 'block') {
+            try {
+                const eventLog = EventLogService.get(wctx.stateDir, logger);
+                eventLog.recordRuleEnforced({
+                    ruleId: hostResult.ruleId || 'unknown',
+                    principleId: hostResult.principleId || 'unknown',
+                    enforcement: 'block',
+                    toolName: event.toolName,
+                    filePath: relPath,
+                });
+                eventLog.recordRuleHostBlocked({
+                    toolName: event.toolName,
+                    filePath: relPath,
+                    reason: hostResult.reason,
+                    ruleId: hostResult.ruleId,
+                });
+            }
+            catch (evErr) {
+                logger?.warn?.(`[PD_GATE] Failed to record rule_enforced/rulehost_blocked: ${String(evErr)}`);
+            }
+            return recordGateBlockAndReturn(wctx, {
+                filePath: relPath,
+                reason: hostResult.reason,
+                toolName: event.toolName,
+                sessionId: ctx.sessionId,
+                blockSource: 'rule-host',
+            }, logger);
+        }
+        if (hostResult?.decision === 'requireApproval') {
+            try {
+                const eventLog = EventLogService.get(wctx.stateDir, logger);
+                eventLog.recordRuleEnforced({
+                    ruleId: hostResult.ruleId || 'unknown',
+                    principleId: hostResult.principleId || 'unknown',
+                    enforcement: 'requireApproval',
+                    toolName: event.toolName,
+                    filePath: relPath,
+                });
+                eventLog.recordRuleHostRequireApproval({
+                    toolName: event.toolName,
+                    filePath: relPath,
+                    reason: hostResult.reason,
+                    ruleId: hostResult.ruleId,
+                });
+            }
+            catch (evErr) {
+                logger?.warn?.(`[PD_GATE] Failed to record rule_enforced/rulehost_requireApproval: ${String(evErr)}`);
+            }
+        }
+        if (hostResult?.decision === 'auto_correct' && hostResult.correctionProposal) {
+            const proposal = hostResult.correctionProposal;
+            let validation;
+            try {
+                validation = validateCorrectionProposal(proposal);
+            }
+            catch (validationError) {
+                validation = { valid: false, errors: [`Validator threw: ${String(validationError)}`] };
+            }
+            try {
+                const eventLog = EventLogService.get(wctx.stateDir, logger);
+                const correctedFields = Array.isArray(proposal.correctedFields)
+                    ? proposal.correctedFields.map((f) => typeof f === 'object' && f !== null ? String(f.field) : String(f))
+                    : [];
+                eventLog.recordRuleHostAutoCorrectProposed({
+                    toolName: event.toolName,
+                    filePath: relPath,
+                    ruleId: String(proposal.ruleId ?? 'unknown'),
+                    principleId: proposal.principleId != null ? String(proposal.principleId) : undefined,
+                    confidence: typeof proposal.confidence === 'number' ? proposal.confidence : 0,
+                    reason: hostResult.reason,
+                    applicationMode: proposal.applicationMode === 'live' ? 'live' : 'shadow',
+                    correctedFields,
+                    validationValid: validation.valid,
+                });
+            }
+            catch (evErr) {
+                logger?.warn?.(`[PD_GATE] Failed to record rulehost_auto_correct_proposed: ${String(evErr)}`);
+            }
+            if (proposal.applicationMode === 'live' && validation.valid) {
+                if (!event.params) {
+                    return;
+                }
+                const originalParams = { ...event.params };
+                const nextParams = {};
+                const appliedFields = [];
+                try {
+                    if (!Array.isArray(proposal.correctedFields)) {
+                        throw new Error('proposal.correctedFields is not an array');
+                    }
+                    if (!proposal.proposedParams || typeof proposal.proposedParams !== 'object' || Array.isArray(proposal.proposedParams)) {
+                        throw new Error('proposal.proposedParams must be an object');
+                    }
+                    const trustedWorkspaceDir = ctx.workspaceDir;
+                    if (typeof trustedWorkspaceDir === 'string' && trustedWorkspaceDir.trim().length > 0) {
+                        const pathBoundsResult = validateProposedPathBounds(proposal.proposedParams, trustedWorkspaceDir);
+                        if (!pathBoundsResult.valid) {
+                            throw new Error(`Path boundary violation: ${pathBoundsResult.reason}`);
+                        }
+                    }
+                    else {
+                        const hasPathField = Object.keys(proposal.proposedParams).some(k => typeof proposal.proposedParams[k] === 'string' && (k === 'file_path' || k === 'path' || k === 'filePath'));
+                        if (hasPathField) {
+                            throw new Error('Cannot apply live auto-correction with path fields: no trusted workspace directory available');
+                        }
+                    }
+                    for (const cf of proposal.correctedFields) {
+                        if (typeof cf !== 'object' || cf === null || typeof cf.field !== 'string') {
+                            throw new Error('correctedFields entry must be an object with a string field');
+                        }
+                        const field = cf.field;
+                        if (!Object.hasOwn(event.params, field)) {
+                            throw new Error(`Field '${field}' not found in event.params`);
+                        }
+                        if (!Object.hasOwn(proposal.proposedParams, field)) {
+                            throw new Error(`Field '${field}' not found in proposal.proposedParams`);
+                        }
+                    }
+                    for (const cf of proposal.correctedFields) {
+                        if (typeof cf === 'object' && cf !== null && typeof cf.field === 'string') {
+                            const field = cf.field;
+                            const originalValue = event.params[field];
+                            const appliedValue = proposal.proposedParams[field];
+                            nextParams[field] = appliedValue;
+                            appliedFields.push({
+                                field,
+                                original: originalValue,
+                                applied: appliedValue,
+                            });
+                        }
+                    }
+                    Object.assign(event.params, nextParams);
+                    try {
+                        const eventLog = EventLogService.get(wctx.stateDir, logger);
+                        eventLog.recordRuleHostAutoCorrectApplied({
+                            toolName: event.toolName,
+                            filePath: relPath,
+                            ruleId: String(proposal.ruleId ?? 'unknown'),
+                            principleId: proposal.principleId != null ? String(proposal.principleId) : undefined,
+                            confidence: typeof proposal.confidence === 'number' ? proposal.confidence : 0,
+                            reason: hostResult.reason || proposal.correctedFields?.[0]?.reason || 'auto-correct applied',
+                            correctedFields: appliedFields,
+                        });
+                    }
+                    catch (evErr) {
+                        logger?.warn?.(`[PD_GATE] Failed to record rulehost_auto_correct_applied: ${String(evErr)}`);
+                    }
+                    if (proposal.notifyAgent === true && appliedFields.length > 0) {
+                        const messages = appliedFields.map(f => `[PD Auto-Correct] Rule ${proposal.ruleId}: ${proposal.correctedFields?.[0]?.reason || 'correction applied'}. Parameter '${f.field}' was adjusted from ${JSON.stringify(f.original)} to ${JSON.stringify(f.applied)}.`);
+                        return {
+                            toolArgs: event.toolArgs,
+                            skipToolCall: false,
+                            _pdAutoCorrectWarning: messages.join('\n'),
+                        };
+                    }
+                }
+                catch (applyError) {
+                    if (event.params) {
+                        Object.assign(event.params, originalParams);
+                    }
+                    const errorMsg = String(applyError);
+                    const isPathViolation = errorMsg.includes('Path boundary violation') || errorMsg.includes('no trusted workspace directory');
+                    if (isPathViolation) {
+                        logger?.warn?.(`[PD_GATE] Live auto-correction rejected — path out of bounds: ${errorMsg}`);
+                        try {
+                            const eventLog = EventLogService.get(wctx.stateDir, logger);
+                            eventLog.recordRuleHostAutoCorrectProposed({
+                                toolName: event.toolName,
+                                filePath: relPath,
+                                ruleId: String(proposal.ruleId ?? 'unknown'),
+                                principleId: proposal.principleId != null ? String(proposal.principleId) : undefined,
+                                confidence: typeof proposal.confidence === 'number' ? proposal.confidence : 0,
+                                reason: `Path boundary rejected: ${errorMsg}`,
+                                applicationMode: 'shadow',
+                                correctedFields: Array.isArray(proposal.correctedFields)
+                                    ? proposal.correctedFields.map((f) => typeof f === 'object' && f !== null ? String(f.field) : String(f))
+                                    : [],
+                                validationValid: false,
+                            });
+                        }
+                        catch (evErr) {
+                            logger?.warn?.(`[PD_GATE] Failed to record path rejection telemetry: ${String(evErr)}`);
+                        }
+                    }
+                    else {
+                        logger?.warn?.(`[PD_GATE] Failed to apply auto-correction, using original params: ${errorMsg}`);
+                    }
+                }
+            }
+        }
+        else if (hostResult?.decision === 'auto_correct') {
+            // auto_correct without correctionProposal — emit telemetry for observability
+            try {
+                const eventLog = EventLogService.get(wctx.stateDir, logger);
+                eventLog.recordRuleHostAutoCorrectProposed({
+                    toolName: event.toolName,
+                    filePath: relPath,
+                    ruleId: hostResult.ruleId ?? 'unknown',
+                    confidence: 0,
+                    reason: hostResult.reason ?? 'auto_correct without correctionProposal',
+                    applicationMode: 'shadow',
+                    correctedFields: [],
+                    validationValid: false,
+                });
+            }
+            catch (evErr) {
+                logger?.warn?.(`[PD_GATE] Failed to record rulehost_auto_correct_proposed (no proposal): ${String(evErr)}`);
+            }
+        }
+    }
+    catch (hostError) {
+        logger.warn?.(`[PD_GATE:RULE_HOST] Host evaluation failed, allowing conservatively: ${String(hostError)}`);
+    }
+    // All checks passed - allow the operation
+    return;
+}
+// ---------------------------------------------------------------------------
+// Private helpers
+// ---------------------------------------------------------------------------
+function _extractParamsSummary(params) {
+    const summary = {};
+    // NOTE: Do NOT redact here — this feeds into RuleHost.evaluate() which
+    // may match against paramsSummary.command. Redaction happens at
+    // EventLog.record() before persistence.
+    if (params.file_path)
+        summary.file_path = params.file_path;
+    if (params.path)
+        summary.path = params.path;
+    if (params.command)
+        summary.command = params.command;
+    if (params.args)
+        summary.args = params.args;
+    if (params.old_string)
+        summary.old_string = params.old_string;
+    if (params.new_string)
+        summary.new_string = params.new_string;
+    return summary;
+}
+function _getCurrentGfi(sessionId) {
+    if (!sessionId)
+        return 0;
+    try {
+        return getSession(sessionId)?.currentGfi ?? 0;
+    }
+    catch {
+        return 0;
+    }
+}
+function _hasRecentThinking(sessionId) {
+    if (!sessionId)
+        return false;
+    try {
+        return hasRecentThinking(sessionId);
+    }
+    catch {
+        return false;
+    }
+}
+function _getEpTier(workspaceDir) {
+    try {
+        const engine = getEvolutionEngine(workspaceDir);
+        return engine.getTier();
+    }
+    catch {
+        return 0;
+    }
+}
+function _getBashRisk(event) {
+    if (!BASH_TOOLS_SET.has(event.toolName))
+        return 'unknown';
+    try {
+        const command = String(event.params?.command || event.params?.args || '');
+        const isDangerous = /\brm\s+-rf\b|\bchmod\b|\bchown\b|>\s*\/dev\//.test(command);
+        if (isDangerous)
+            return 'dangerous';
+        const isMutation = /(?:>|>>|sed|rm|mv|mkdir|touch|cp|npm|yarn|pnpm|pip|cargo)/.test(command);
+        if (isMutation)
+            return 'normal';
+        return 'safe';
+    }
+    catch {
+        return 'unknown';
+    }
+}

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>;