principles-disciple 1.8.1 → 1.8.3

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

@@ -1,119 +0,0 @@
-/**
- * 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 { trackBlock } from '../core/session-tracker.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 = logger.warn?.bind(logger) ?? ((msg) => console.warn(msg));
-    const logError = logger.error?.bind(logger) ?? ((msg) => console.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. Return consistent block result with operator guidance
-    return {
-        block: true,
-        blockReason: `[Principles Disciple] Security Gate Blocked this action.
-File: ${filePath}
-Reason: ${reason}
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-📋 How to unblock this operation:
-
-1. Use the plan-script skill to create a PLAN.md:
-   → Invoke: skill:plan-script
-
-2. Fill in the plan with:
-   - Target Files: ${filePath}
-   - Steps: What you want to do (be specific)
-   - Metrics: How to verify success
-   - Active Mental Models: Select 2 relevant models from .principles/THINKING_OS.md
-   - Rollback: How to restore if it fails
-
-3. After completing the plan, set STATUS: READY in PLAN.md
-
-4. Retry the operation
-
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
-This is a mandatory security gate. The operation was blocked because the modification exceeds the allowed threshold for your current evolution tier.
-━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
-    };
-}
-/**
- * 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);
-}

package/dist/hooks/gate.d.ts

@@ -1,24 +0,0 @@
-/**
- * Security Gate Hook - Orchestration Layer
- *
- * HOOK CHAIN PRIORITY (short-circuits on first block):
- *
- * 1. Early Return: Skip if not write/bash/agent tool or no workspace
- * 2. Thinking OS Checkpoint (P-10): Deep reflection enforcement
- * 3. GFI Gate: Fatigue index-based blocking
- * 4. Bash Mutation Detection: Heuristic for bash file modifications
- * 5. Progressive Gate: EP tier-based access control
- * 6. Edit Verification (P-03): Exact/fuzzy match for edit operations
- *
- * IMPORTANT: This is the SINGLE AUTHORITATIVE orchestration path.
- * All policy modules (gfi-gate, progressive-trust-gate) use the shared
- * `recordGateBlockAndReturn` helper to ensure consistent block persistence.
- *
- * Zero-width character detection is handled in bash-risk.ts.
- */
-import type { PluginHookBeforeToolCallEvent, PluginHookToolContext, PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
-export declare function handleBeforeToolCall(event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext & {
-    workspaceDir?: string;
-    pluginConfig?: Record<string, unknown>;
-    logger?: any;
-}): PluginHookBeforeToolCallResult | void;

package/dist/hooks/gate.js

@@ -1,173 +0,0 @@
-/**
- * Security Gate Hook - Orchestration Layer
- *
- * HOOK CHAIN PRIORITY (short-circuits on first block):
- *
- * 1. Early Return: Skip if not write/bash/agent tool or no workspace
- * 2. Thinking OS Checkpoint (P-10): Deep reflection enforcement
- * 3. GFI Gate: Fatigue index-based blocking
- * 4. Bash Mutation Detection: Heuristic for bash file modifications
- * 5. Progressive Gate: EP tier-based access control
- * 6. Edit Verification (P-03): Exact/fuzzy match for edit operations
- *
- * IMPORTANT: This is the SINGLE AUTHORITATIVE orchestration path.
- * All policy modules (gfi-gate, progressive-trust-gate) use the shared
- * `recordGateBlockAndReturn` helper to ensure consistent block persistence.
- *
- * Zero-width character detection is handled in bash-risk.ts.
- */
-import * as fs from 'fs';
-import { isRisky, normalizePath, planStatus as getPlanStatus } from '../utils/io.js';
-import { normalizeProfile } from '../core/profile.js';
-import { estimateLineChanges } from '../core/risk-calculator.js';
-import { WorkspaceContext } from '../core/workspace-context.js';
-import { checkThinkingCheckpoint } from './thinking-checkpoint.js';
-import { handleEditVerification } from './edit-verification.js';
-import { checkGfiGate } from './gfi-gate.js';
-import { checkProgressiveTrustGate } from './progressive-trust-gate.js';
-import { recordGateBlockAndReturn } from './gate-block-helper.js';
-import { AGENT_TOOLS, BASH_TOOLS_SET, WRITE_TOOLS, } from '../constants/tools.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. 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'],
-        }
-    };
-    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)}`);
-        }
-    }
-    // ─────────────────────────────────────────────────────────────────────────────
-    // POLICY STEP 1: Thinking OS Checkpoint (P-10)
-    // ─────────────────────────────────────────────────────────────────────────────
-    // Only enforced when thinking_checkpoint.enabled = true in PROFILE.json
-    const thinkingResult = checkThinkingCheckpoint(event, profile.thinking_checkpoint || {}, ctx.sessionId, logger);
-    if (thinkingResult) {
-        return thinkingResult;
-    }
-    // ─────────────────────────────────────────────────────────────────────────────
-    // POLICY STEP 2: GFI Gate - Hard Intercept
-    // ─────────────────────────────────────────────────────────────────────────────
-    // 根据 GFI (疲劳指数) 精细化拦截工具调用
-    // 注意：TIER 0 (只读工具) 已在早期过滤中放行，此处不检查
-    const gfiGateConfig = wctx.config.get('gfi_gate');
-    const gfiResult = checkGfiGate(event, wctx, ctx.sessionId, gfiGateConfig, logger);
-    if (gfiResult) {
-        return gfiResult;
-    }
-    // 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);
-    // ─────────────────────────────────────────────────────────────────────────────
-    // POLICY STEP 3: Progressive Trust Gate (Stage 1-4 access control)
-    // ─────────────────────────────────────────────────────────────────────────────
-    // IMPORTANT: This step does NOT return early on allow.
-    // We must continue to edit verification for ALL allowed operations.
-    if (profile.progressive_gate?.enabled) {
-        const lineChanges = estimateLineChanges({ toolName: event.toolName, params: event.params });
-        const progressiveGateResult = checkProgressiveTrustGate(event, wctx, relPath, risky, lineChanges, logger, ctx, profile);
-        if (progressiveGateResult) {
-            return progressiveGateResult;
-        }
-        // NOTE: Do NOT return here! Continue to edit verification.
-        // All allowed operations (regardless of EP tier) should still run edit verification.
-    }
-    else {
-        // FALLBACK: Legacy Gate Logic (when progressive gate is disabled)
-        if (risky && profile.gate?.require_plan_for_risk_paths) {
-            const planStatus = getPlanStatus(ctx.workspaceDir);
-            if (planStatus !== 'READY') {
-                return recordGateBlockAndReturn(wctx, {
-                    filePath: relPath,
-                    reason: `No READY plan found in PLAN.md.`,
-                    toolName: event.toolName,
-                    sessionId: ctx.sessionId,
-                    blockSource: 'gate-legacy',
-                }, logger);
-            }
-        }
-    }
-    // ─────────────────────────────────────────────────────────────────────────────
-    // POLICY STEP 4: Edit Tool Verification (P-03)
-    // ─────────────────────────────────────────────────────────────────────────────
-    // This MUST run after all other gate checks for ALL tools.
-    // Edit verification ensures oldText matches the actual file content.
-    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
-        }
-    }
-    // All checks passed - allow the operation
-    return;
-}

package/dist/hooks/gfi-gate.d.ts

@@ -1,40 +0,0 @@
-/**
- * GFI Gate Module
- *
- * Handles Fatigue Index (GFI) based tool blocking with TIER 0-3 classification.
- *
- * **Responsibilities:**
- * - Calculate dynamic GFI thresholds based on EP tier and line changes
- * - Apply tier-based tool blocking:
- *   - TIER 0: Read-only tools (never blocked)
- *   - TIER 1: Low-risk writes (blocked when GFI >= low_risk_block threshold)
- *   - TIER 2: High-risk operations (blocked when GFI >= high_risk_block threshold)
- *   - TIER 3: Bash commands (content-dependent blocking)
- * - Prevent subagent spawn at critically high GFI (>=90)
- *
- * **Configuration:**
- * - GFI thresholds from config.gfi_gate
- * - EP tier multipliers for dynamic threshold calculation
- * - Large change adjustments
- *
- * **Block Persistence:**
- * - Uses shared `recordGateBlockAndReturn` from gate-block-helper.ts
- * - Ensures single authoritative block persistence path
- */
-import type { WorkspaceContext } from '../core/workspace-context.js';
-import type { PluginHookBeforeToolCallEvent, PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
-export interface GfiGateConfig {
-    enabled?: boolean;
-    thresholds?: {
-        low_risk_block?: number;
-        high_risk_block?: number;
-    };
-    large_change_lines?: number;
-    ep_tier_multipliers?: Record<string, number>;
-    bash_safe_patterns?: string[];
-    bash_dangerous_patterns?: string[];
-}
-export declare function checkGfiGate(event: PluginHookBeforeToolCallEvent, wctx: WorkspaceContext, sessionId: string | undefined, config: GfiGateConfig, logger?: {
-    info?: (message: string) => void;
-    warn?: (message: string) => void;
-}): PluginHookBeforeToolCallResult | undefined;

package/dist/hooks/gfi-gate.js

@@ -1,113 +0,0 @@
-/**
- * GFI Gate Module
- *
- * Handles Fatigue Index (GFI) based tool blocking with TIER 0-3 classification.
- *
- * **Responsibilities:**
- * - Calculate dynamic GFI thresholds based on EP tier and line changes
- * - Apply tier-based tool blocking:
- *   - TIER 0: Read-only tools (never blocked)
- *   - TIER 1: Low-risk writes (blocked when GFI >= low_risk_block threshold)
- *   - TIER 2: High-risk operations (blocked when GFI >= high_risk_block threshold)
- *   - TIER 3: Bash commands (content-dependent blocking)
- * - Prevent subagent spawn at critically high GFI (>=90)
- *
- * **Configuration:**
- * - GFI thresholds from config.gfi_gate
- * - EP tier multipliers for dynamic threshold calculation
- * - Large change adjustments
- *
- * **Block Persistence:**
- * - Uses shared `recordGateBlockAndReturn` from gate-block-helper.ts
- * - Ensures single authoritative block persistence path
- */
-import { getSession } from '../core/session-tracker.js';
-import { estimateLineChanges } from '../core/risk-calculator.js';
-import { analyzeBashCommand, calculateDynamicThreshold } from './bash-risk.js';
-import { BASH_TOOLS_SET, HIGH_RISK_TOOLS, LOW_RISK_WRITE_TOOLS, AGENT_TOOLS } from '../constants/tools.js';
-import { AGENT_SPAWN_GFI_THRESHOLD } from '../config/index.js';
-import { recordGateBlockAndReturn } from './gate-block-helper.js';
-import { getEvolutionEngine } from '../core/evolution-engine.js';
-/**
- * Internal helper to call the shared block helper with gfi-gate source tag.
- */
-function block(wctx, filePath, reason, toolName, sessionId, logger) {
-    return recordGateBlockAndReturn(wctx, {
-        filePath,
-        reason,
-        toolName,
-        sessionId,
-        blockSource: 'gfi-gate',
-    }, logger || { warn: () => { }, error: () => { } });
-}
-export function checkGfiGate(event, wctx, sessionId, config, logger) {
-    if (!config || config.enabled === false || !sessionId) {
-        return undefined;
-    }
-    const session = getSession(sessionId);
-    const currentGfi = session?.currentGfi || 0;
-    const getEpTier = () => {
-        return getEvolutionEngine(wctx.workspaceDir).getTier();
-    };
-    // TIER 3: Bash commands
-    if (BASH_TOOLS_SET.has(event.toolName)) {
-        const command = String(event.params.command || event.params.args || '');
-        const bashRisk = analyzeBashCommand(command, config.bash_safe_patterns || [], config.bash_dangerous_patterns || [], logger);
-        if (bashRisk === 'dangerous') {
-            logger?.warn?.(`[PD:GFI_GATE] Dangerous bash command blocked: ${command.substring(0, 50)}...`);
-            return block(wctx, command.substring(0, 100), `危险命令被拦截。检测到危险命令模式，需要确认执行意图。`, event.toolName, sessionId, logger);
-        }
-        if (bashRisk === 'safe') {
-            return undefined;
-        }
-        // normal bash - check GFI threshold
-        const tier = getEpTier();
-        const baseThreshold = config.thresholds?.low_risk_block || 70;
-        const dynamicThreshold = calculateDynamicThreshold(baseThreshold, tier, 0, {
-            large_change_lines: config.large_change_lines || 50,
-            ep_tier_multipliers: config.ep_tier_multipliers || { '1': 0.5, '2': 0.75, '3': 1.0, '4': 1.5, '5': 2.0 },
-        });
-        if (currentGfi >= dynamicThreshold) {
-            logger?.warn?.(`[PD:GFI_GATE] Bash blocked by GFI: ${currentGfi} >= ${dynamicThreshold}`);
-            return block(wctx, command.substring(0, 100), `疲劳指数过高 (GFI: ${currentGfi}/${dynamicThreshold})。系统进入保护模式。`, event.toolName, sessionId, logger);
-        }
-        return undefined;
-    }
-    // TIER 2: High-risk tools
-    if (HIGH_RISK_TOOLS.has(event.toolName)) {
-        const tier = getEpTier();
-        const baseThreshold = config.thresholds?.high_risk_block || 40;
-        const dynamicThreshold = calculateDynamicThreshold(baseThreshold, tier, 0, {
-            large_change_lines: config.large_change_lines || 50,
-            ep_tier_multipliers: config.ep_tier_multipliers || { '1': 0.5, '2': 0.75, '3': 1.0, '4': 1.5, '5': 2.0 },
-        });
-        if (currentGfi >= dynamicThreshold) {
-            const filePath = event.params.file_path || event.params.path || event.params.file || event.params.target || 'unknown';
-            logger?.warn?.(`[PD:GFI_GATE] High-risk tool "${event.toolName}" blocked by GFI: ${currentGfi} >= ${dynamicThreshold}`);
-            return block(wctx, filePath, `高风险操作被拦截。GFI: ${currentGfi}/${dynamicThreshold}。高风险工具需要更低的阈值。`, event.toolName, sessionId, logger);
-        }
-    }
-    // TIER 1: Low-risk write tools
-    if (LOW_RISK_WRITE_TOOLS.has(event.toolName)) {
-        const tier = getEpTier();
-        const lineChanges = estimateLineChanges({ toolName: event.toolName, params: event.params });
-        const baseThreshold = config.thresholds?.low_risk_block || 70;
-        const dynamicThreshold = calculateDynamicThreshold(baseThreshold, tier, lineChanges, {
-            large_change_lines: config.large_change_lines || 50,
-            ep_tier_multipliers: config.ep_tier_multipliers || { '1': 0.5, '2': 0.75, '3': 1.0, '4': 1.5, '5': 2.0 },
-        });
-        if (currentGfi >= dynamicThreshold) {
-            const filePath = event.params.file_path || event.params.path || event.params.file || event.params.target || 'unknown';
-            logger?.warn?.(`[PD:GFI_GATE] Low-risk tool "${event.toolName}" blocked by GFI: ${currentGfi} >= ${dynamicThreshold}`);
-            return block(wctx, filePath, `疲劳指数过高 (GFI: ${currentGfi}/${dynamicThreshold})。系统进入保护模式。`, event.toolName, sessionId, logger);
-        }
-    }
-    // AGENT_TOOLS: Block subagent spawn when GFI is critically high
-    if (AGENT_TOOLS.has(event.toolName)) {
-        if (currentGfi >= AGENT_SPAWN_GFI_THRESHOLD) {
-            logger?.warn?.(`[PD:GFI_GATE] Agent tool "${event.toolName}" blocked by GFI: ${currentGfi} >= ${AGENT_SPAWN_GFI_THRESHOLD}`);
-            return block(wctx, 'subagent-spawn', `疲劳指数过高，禁止派生子智能体。GFI: ${currentGfi}/${AGENT_SPAWN_GFI_THRESHOLD}`, event.toolName, sessionId, logger);
-        }
-    }
-    return undefined;
-}

package/dist/hooks/lifecycle.d.ts

@@ -1,5 +0,0 @@
-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>;