principles-disciple 1.8.0 → 1.8.2

package/src/hooks/gate-block-helper.ts

@@ -0,0 +1,160 @@
+/**
+ * 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 type { WorkspaceContext } from '../core/workspace-context.js';
+import type { PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
+import {
+  TRAJECTORY_GATE_BLOCK_RETRY_DELAY_MS,
+  TRAJECTORY_GATE_BLOCK_MAX_RETRIES
+} from '../config/index.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 function recordGateBlockAndReturn(
+  wctx: WorkspaceContext,
+  blockCtx: BlockContext,
+  logger: { warn?: (message: string) => void; error?: (message: string) => void; info?: (message: string) => void }
+): PluginHookBeforeToolCallResult {
+  const { filePath, reason, toolName, sessionId, blockSource } = blockCtx;
+
+  // Default logger if not provided
+  const logWarn = (msg: string) => logger.warn?.(msg);
+  const logError = (msg: string) => 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: unknown) {
+    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: unknown) {
+    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: WorkspaceContext,
+  payload: {
+    sessionId: string | null;
+    toolName: string;
+    filePath: string;
+    reason: string;
+    blockSource?: string;
+  },
+  attempt: number,
+  logWarn: (message: string) => void,
+  logError: (message: string) => void
+): void {
+  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: unknown) {
+      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/src/hooks/gate.ts

@@ -0,0 +1,210 @@
+/**
+ * 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 * as path from 'path';
+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 type { PluginHookBeforeToolCallEvent, PluginHookToolContext, PluginHookBeforeToolCallResult } from '../openclaw-sdk.js';
+import {
+  AGENT_TOOLS,
+  BASH_TOOLS_SET,
+  WRITE_TOOLS,
+} from '../constants/tools.js';
+
+export function handleBeforeToolCall(
+  event: PluginHookBeforeToolCallEvent,
+  ctx: PluginHookToolContext & { workspaceDir?: string; pluginConfig?: Record<string, unknown>; logger?: any }
+): PluginHookBeforeToolCallResult | void {
+  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: [] as string[],
+    gate: { require_plan_for_risk_paths: true },
+    progressive_gate: {
+      enabled: true,
+      plan_approvals: {
+        enabled: false,
+        max_lines_override: -1,
+        allowed_patterns: [] as string[],
+        allowed_operations: [] as string[],
+      }
+    },
+    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' as 'warn' | 'block',
+    },
+    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 as string[] | undefined) ?? [];
+  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 as 'warn' | 'block' | undefined,
+    });
+    if (verifyResult) {
+      return verifyResult; // Block or modify params
+    }
+  }
+
+  // All checks passed - allow the operation
+  return;
+}

package/src/hooks/gfi-gate.ts

@@ -0,0 +1,177 @@
+/**
+ * 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, type DynamicThresholdConfig } 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';
+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[];
+}
+
+/**
+ * Internal helper to call the shared block helper with gfi-gate source tag.
+ */
+function block(
+  wctx: WorkspaceContext,
+  filePath: string,
+  reason: string,
+  toolName: string,
+  sessionId: string | undefined,
+  logger?: { info?: (message: string) => void; warn?: (message: string) => void; error?: (message: string) => void }
+): PluginHookBeforeToolCallResult {
+  return recordGateBlockAndReturn(wctx, {
+    filePath,
+    reason,
+    toolName,
+    sessionId,
+    blockSource: 'gfi-gate',
+  }, logger || { warn: () => {}, error: () => {} });
+}
+
+export function checkGfiGate(
+  event: PluginHookBeforeToolCallEvent,
+  wctx: WorkspaceContext,
+  sessionId: string | undefined,
+  config: GfiGateConfig,
+  logger?: { info?: (message: string) => void; warn?: (message: string) => void }
+): PluginHookBeforeToolCallResult | undefined {
+  if (!config || config.enabled === false || !sessionId) {
+    return undefined;
+  }
+
+  const session = getSession(sessionId);
+  const currentGfi = session?.currentGfi || 0;
+
+  const getEpTier = (): number => {
+    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;
+}