principles-disciple 1.7.4 → 1.7.6

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

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

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

@@ -0,0 +1,119 @@
+/**
+ * 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 trust stage.
+━━━━━━━━━━━━━━━━━━━━━━━━━━━━━`,
+    };
+}
+/**
+ * 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,3 +1,21 @@
+/**
+ * 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 Trust Gate: Stage 1-4 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;