principles-disciple 1.126.0 → 1.128.0

package/dist/hooks/after-tool-call-helpers.js

@@ -0,0 +1,475 @@
+/**
+ * After-Tool-Call Decomposition Helpers — PRI-326
+ *
+ * Extracted functions from handleAfterToolCall that implement
+ * individual pipeline stages. Each function has a focused responsibility.
+ *
+ * Pipeline order: classify → record → triage → gate → emit
+ *
+ * ERR checklist:
+ * - ERR-001: No `as` casts on untrusted runtime values.
+ * - ERR-002: Every skip/rejection includes structured reason + nextAction.
+ * - EP-01: Runtime values validated before use.
+ * - EP-03: No silent failures — every path is logged or structured.
+ */
+import { isRisky, normalizePath } from '../utils/io.js';
+import { computePainScore, trackPrincipleValue } from '../core/pain.js';
+import { getSession, trackFriction, resetFriction, getInjectedProbationIds, clearInjectedProbationIds } from '../core/session-tracker.js';
+import { denoiseError, computeHash } from '../utils/hashing.js';
+import { SystemLogger } from '../core/system-logger.js';
+import { getEvolutionLogger, createTraceId } from '../core/evolution-logger.js';
+import { recordEvolutionSuccess, recordEvolutionFailure } from '../core/evolution-engine.js';
+import { isCooldownActive as isTriggerCooldownActive, markEpisodeAsDiagnosed, clearCooldownState } from './trigger-cooldown-tracker.js';
+import { sanitizeForEvidence, sanitizeToolParamsForEvidence } from './message-sanitize.js';
+import { resolveSourceKind, buildToolFailureObservation } from './raw-observation-adapter.js';
+import { evaluateEvidenceTriage } from './triage-adapter.js';
+import { evaluateTriggerController } from '@principles/core/runtime-v2';
+import { buildTrajectoryEvidence } from './trajectory-evidence.js';
+// ── Stage 1: Classify ───────────────────────────────────────────────────────
+/**
+ * Classify the outcome of a tool call event.
+ *
+ * Pure function — no I/O, no side effects.
+ * Extracts exitCode logic, determines failure/success, classifies failure source.
+ */
+export function classifyToolCallOutcome(event) {
+    // EP-01: Validate event.result at runtime instead of `as` cast
+    const resultObj = (event.result && typeof event.result === 'object' && !Array.isArray(event.result))
+        ? event.result // safe: guarded by typeof + Array.isArray checks above
+        : null;
+    const details = (resultObj && resultObj.details && typeof resultObj.details === 'object' && !Array.isArray(resultObj.details))
+        ? resultObj.details // safe: guarded by typeof + Array.isArray checks above
+        : null;
+    const topExitCode = resultObj?.exitCode;
+    const detailExitCode = details?.exitCode;
+    // Prefer the first *numeric* exit code
+    const exitCode = typeof topExitCode === 'number' ? topExitCode
+        : typeof detailExitCode === 'number' ? detailExitCode
+            : 0;
+    const isFailure = !!event.error || exitCode !== 0;
+    // PRI-360 S1: Use centralized builder for tool failure classification
+    // All dispatch/tool_failure rules live in raw-observation-adapter.ts
+    const obs = buildToolFailureObservation({
+        toolName: event.toolName,
+        error: event.error,
+        exitCode,
+    });
+    const failureSource = isFailure ? obs.failureSource : undefined;
+    return {
+        isFailure,
+        exitCode,
+        failureSource,
+    };
+}
+/**
+ * Build a normalized observation from the tool call event and workspace context.
+ *
+ * Combines file path normalization, risk classification, and error analysis.
+ * The profile parameter is passed in (loaded once at function scope).
+ */
+export function buildToolCallObservation(event, outcome, workspaceDir, profile) {
+    const rawParams = event.params;
+    const params = (rawParams && typeof rawParams === 'object' && !Array.isArray(rawParams))
+        ? rawParams
+        : {};
+    const filePath = params.file_path || params.path || params.file;
+    const relPath = typeof filePath === 'string' ? normalizePath(filePath, workspaceDir) : 'unknown';
+    const isRisk = isRisky(relPath, profile.risk_paths);
+    let errorText;
+    if (event.error) {
+        errorText = String(event.error);
+    }
+    else if (typeof event.result === 'string') {
+        errorText = event.result;
+    }
+    else {
+        try {
+            errorText = JSON.stringify(event.result);
+        }
+        catch {
+            errorText = `[unserializable result: ${typeof event.result}]`;
+        }
+    }
+    const denoised = denoiseError(errorText);
+    const hash = computeHash(denoised);
+    const painScore = computePainScore(1, false, false, isRisk ? 20 : 0, workspaceDir);
+    return {
+        params: {
+            filePath,
+            content: params.content,
+            text: params.text,
+            newString: params.new_string,
+            query: params.query,
+            input: params.input,
+            arguments: params.arguments,
+        },
+        relPath,
+        isRisk,
+        errorType: extractErrorType(event.error || errorText),
+        errorHash: hash,
+        errorText,
+        painScore,
+        traceId: createTraceId(),
+    };
+}
+// ── Stage 3: Friction + Recording ──────────────────────────────────────────
+/**
+ * Handle friction tracking for a tool failure.
+ *
+ * Updates GFI, records to event log and trajectory.
+ * Returns the updated session state and friction info.
+ */
+export function handleFrictionTrackingForFailure(sessionId, event, outcome, observation, gfiBefore, workspaceDir, config, wctx) {
+    const deltaF = config.get('scores.tool_failure_friction') || 30;
+    const updatedState = trackFriction(sessionId, deltaF, observation.errorHash, workspaceDir, { source: outcome.failureSource });
+    recordEvolutionFailure(workspaceDir, event.toolName, {
+        filePath: observation.relPath,
+        reason: observation.isRisk ? 'risky' : 'tool',
+        sessionId,
+    });
+    // Record tool call failure event
+    wctx.eventLog.recordToolCall(sessionId, {
+        toolName: event.toolName,
+        filePath: observation.params.filePath,
+        error: event.error ? String(event.error).substring(0, 200) : undefined,
+        errorType: observation.errorType,
+        gfi: updatedState.currentGfi,
+        consecutiveErrors: updatedState.consecutiveErrors,
+        exitCode: outcome.exitCode,
+        gfiBefore,
+        gfiAfter: updatedState.currentGfi,
+    });
+    wctx.trajectory?.recordToolCall?.({
+        sessionId,
+        toolName: event.toolName,
+        outcome: 'failure',
+        durationMs: event.durationMs,
+        exitCode: outcome.exitCode,
+        errorType: observation.errorType,
+        errorMessage: event.error ? String(event.error) : undefined,
+        gfiBefore,
+        gfiAfter: updatedState.currentGfi,
+        paramsJson: sanitizeToolParamsForEvidence(event.params, workspaceDir),
+    });
+    return updatedState;
+}
+/**
+ * Handle friction relief and recording for a tool success.
+ *
+ * Relieves both tool_failure and dispatch_error GFI sources proportionally.
+ */
+export function handleFrictionTrackingForSuccess(sessionId, event, outcome, observation, gfiBefore, workspaceDir, wctx) {
+    const session = getSession(sessionId);
+    const toolFailureGfi = session?.gfiBySource?.tool_failure || 0;
+    const dispatchErrorGfi = session?.gfiBySource?.dispatch_error || 0;
+    let resetState = session || resetFriction(sessionId, workspaceDir);
+    if (toolFailureGfi > 0) {
+        resetState = resetFriction(sessionId, workspaceDir, {
+            source: 'tool_failure',
+            amount: toolFailureGfi * 0.5,
+        });
+    }
+    if (dispatchErrorGfi > 0) {
+        resetState = resetFriction(sessionId, workspaceDir, {
+            source: 'dispatch_error',
+            amount: dispatchErrorGfi * 0.5,
+        });
+    }
+    recordEvolutionSuccess(workspaceDir, event.toolName, {
+        sessionId,
+        reason: 'tool_success',
+    });
+    wctx.trajectory?.recordToolCall?.({
+        sessionId,
+        toolName: event.toolName,
+        outcome: 'success',
+        durationMs: event.durationMs,
+        exitCode: outcome.exitCode,
+        gfiBefore,
+        gfiAfter: resetState.currentGfi,
+        paramsJson: sanitizeToolParamsForEvidence(event.params, workspaceDir),
+    });
+    wctx.eventLog.recordToolCall(sessionId, {
+        toolName: event.toolName,
+        filePath: observation.params.filePath,
+        gfi: resetState.currentGfi,
+        gfiBefore,
+        gfiAfter: resetState.currentGfi,
+    });
+    return resetState;
+}
+// ── Stage 4: Hygiene Tracking ───────────────────────────────────────────────
+/**
+ * Record hygiene tracking for memory/plan persistence actions on success.
+ */
+export function recordHygieneTracking(event, observation, wctx) {
+    const normalized = typeof observation.params.filePath === 'string' ? observation.params.filePath.replace(/\\/g, '/') : '';
+    const isMemory = /(?:^|\/)memory\//.test(normalized) || normalized.endsWith('/MEMORY.md') || normalized === 'MEMORY.md';
+    const isPlan = normalized === 'PLAN.md' || normalized.endsWith('/PLAN.md');
+    if (isMemory || isPlan) {
+        wctx.hygiene.recordPersistence({
+            ts: new Date().toISOString(),
+            tool: event.toolName,
+            path: observation.params.filePath ?? 'unknown',
+            type: isMemory ? 'memory' : 'plan',
+            contentLength: observation.params.content?.length ?? observation.params.newString?.length ?? 0,
+        });
+    }
+    // Special case for memory_store tool (Success only)
+    if (event.toolName === 'memory_store') {
+        wctx.hygiene.recordPersistence({
+            ts: new Date().toISOString(),
+            tool: event.toolName,
+            path: 'DATABASE',
+            type: 'memory',
+            contentLength: observation.params.text?.length ?? 0,
+        });
+    }
+}
+// ── Stage 5: Probation Feedback ─────────────────────────────────────────────
+function shouldAttributePrincipleToTool(principle, toolName) {
+    return principle.contextTags.includes(toolName) || principle.trigger.includes(toolName);
+}
+/**
+ * Record probation feedback for injected probation IDs.
+ *
+ * On success: positive feedback for matching principles.
+ * On failure: negative feedback for matching principles.
+ */
+export function handleProbationFeedback(sessionId, toolName, workspaceDir, wctx, isSuccess) {
+    const injectedProbationIds = getInjectedProbationIds(sessionId, workspaceDir);
+    for (const id of injectedProbationIds) {
+        const principle = wctx.evolutionReducer.getPrincipleById(id);
+        const shouldAttribute = !!principle && shouldAttributePrincipleToTool(principle, toolName);
+        if (shouldAttribute) {
+            wctx.evolutionReducer.recordProbationFeedback(id, isSuccess);
+        }
+    }
+    clearInjectedProbationIds(sessionId, workspaceDir);
+}
+// ── Stage 6: Pain Admission ─────────────────────────────────────────────────
+const WRITE_TOOLS = ['write', 'edit', 'apply_patch', 'write_file', 'edit_file', 'replace'];
+/**
+ * Cooldown map for trigger controller decisions.
+ *
+ * PRI-363: This replaces the hidden map in PainDiagnosticGate.
+ * Core trigger-controller is stateless; plugin layer owns cooldown state.
+ *
+ * EP-05: Loop state freshness — each check reads fresh state from this map.
+ */
+const TRIGGER_COOLDOWN_MAP = new Map();
+/**
+ * Evaluate whether a tool failure should trigger pain diagnosis.
+ *
+ * PRI-363: Single-gate architecture — only TriggerController decides.
+ *
+ * Combines:
+ * 1. Write-tool check — only write tools on failures enter this path
+ * 2. PEAT-B1 triage — evidence triage (always enabled now)
+ * 3. PEAT-B2 trigger controller — single source of truth for task creation
+ * 4. Cooldown tracking — plugin layer owns this state
+ *
+ * Returns a structured decision with reason and stage.
+ */
+export function evaluatePainAdmissionForToolCall(event, observation, outcome, latestFailureState, sessionState, sessionId, workspaceDir, _config) {
+    // Only write-tool failures enter the pain path
+    if (!WRITE_TOOLS.includes(event.toolName) || !outcome.isFailure) {
+        return {
+            admitted: false,
+            stage: 'not_applicable',
+            reason: 'not_a_write_tool_failure',
+            detail: `tool=${event.toolName}, isFailure=${outcome.isFailure}`,
+        };
+    }
+    const failureSource = outcome.failureSource ?? 'tool_failure';
+    // Check cooldown before calling trigger controller
+    const cooldownActive = isTriggerCooldownActive(failureSource, sessionId, latestFailureState?.lastErrorHash, TRIGGER_COOLDOWN_MAP);
+    // PRI-360 S1: Build RawObservation for unified source mapping
+    const rawObs = {
+        observedAt: new Date().toISOString(),
+        workspaceId: workspaceDir,
+        sessionId,
+        toolName: event.toolName,
+        failureSource: outcome.failureSource,
+        // Infer toolNotFound from failureSource for resolveSourceKind compatibility
+        toolNotFound: outcome.failureSource === 'dispatch_error',
+        // Extract exit code from outcome for triage (nonZeroExit)
+        nonZeroExit: outcome.exitCode !== 0,
+    };
+    // PRI-360 S1: Use unified resolveSourceKind instead of resolveSourceKindFromToolFailure
+    const sourceKind = resolveSourceKind(rawObs);
+    // PEAT-B1: Evidence triage (with consecutiveErrors and isRisky for upgrade logic)
+    const triage = evaluateEvidenceTriage(sourceKind, observation.painScore, {
+        consecutiveErrors: (latestFailureState ?? sessionState)?.consecutiveErrors,
+        isRisky: observation.isRisk,
+    });
+    // PEAT-B2: Trigger controller — single source of truth for task creation
+    const triggerDecision = evaluateTriggerController({
+        triageResult: triage,
+        isOwnerManual: false, // tool failures are never owner manual
+        isCooldownActive: cooldownActive,
+        isValid: true,
+        score: observation.painScore,
+        sessionId,
+    });
+    // Log the decision
+    SystemLogger.log(workspaceDir, 'TRIGGER_DECISION', JSON.stringify({
+        outcome: triggerDecision.outcome,
+        sourceKind: triggerDecision.sourceKind,
+        reason: triggerDecision.reason,
+        nextAction: triggerDecision.nextAction,
+        triageDecision: triggerDecision.triageDecision,
+        tool: event.toolName,
+        path: observation.relPath,
+    }));
+    // If trigger controller says yes, mark cooldown and admit
+    if (triggerDecision.shouldCreateDiagnosticTask) {
+        markEpisodeAsDiagnosed(failureSource, sessionId, latestFailureState?.lastErrorHash, TRIGGER_COOLDOWN_MAP);
+        return {
+            admitted: true,
+            stage: 'trigger_admitted',
+            reason: triggerDecision.reason,
+            detail: `outcome=${triggerDecision.outcome}, sourceKind=${triggerDecision.sourceKind}, nextAction=${triggerDecision.nextAction}`,
+        };
+    }
+    // Otherwise, reject with trigger controller's reason
+    return {
+        admitted: false,
+        stage: 'trigger_rejected',
+        reason: triggerDecision.reason,
+        detail: `outcome=${triggerDecision.outcome}, sourceKind=${triggerDecision.sourceKind}, nextAction=${triggerDecision.nextAction}`,
+    };
+}
+// ── Stage 7: Emit Pain ─────────────────────────────────────────────────────
+/**
+ * Emit pain signal after admission.
+ *
+ * Records to trajectory, event log, evolution logger, principle value tracker,
+ * and emits the pain_detected event.
+ *
+ * Only called when the admission decision is 'admitted'.
+ */
+export function emitPainIfAdmitted(wctx, event, observation, outcome, admission, sessionId, agentId, workspaceDir, emitPainDetectedEvent) {
+    if (!admission.admitted)
+        return;
+    const failureSource = outcome.failureSource ?? 'tool_failure';
+    // Record to trajectory before Runtime V2 diagnosis
+    wctx.trajectory?.recordPainEvent({
+        sessionId,
+        source: failureSource,
+        score: observation.painScore,
+        reason: `Tool ${event.toolName} failed on ${observation.relPath}`,
+        severity: observation.painScore >= 70 ? 'severe' : observation.painScore >= 40 ? 'moderate' : 'mild',
+        origin: 'system_infer',
+        text: sanitizeForEvidence(observation.params.text ?? observation.params.content, workspaceDir) || undefined,
+    });
+    // Observe: track which principles would have prevented this pain (observation-only)
+    try {
+        trackPrincipleValue(workspaceDir, {
+            reason: `Tool ${event.toolName} failed on ${observation.relPath}. Error: ${event.error ?? 'Non-zero exit code'}`,
+            source: failureSource,
+            score: String(observation.painScore),
+        }, () => wctx.evolutionReducer.getActivePrinciples().map((p) => ({
+            id: p.id,
+            trigger: p.trigger,
+            valueMetrics: p.valueMetrics,
+        })), (id, metrics) => {
+            const principle = wctx.evolutionReducer.getPrincipleById(id);
+            if (principle) {
+                principle.valueMetrics = metrics;
+                try {
+                    wctx.principleTreeLedger.updatePrincipleValueMetrics(id, {
+                        principleId: id,
+                        painPreventedCount: metrics.painPreventedCount,
+                        lastPainPreventedAt: metrics.lastPainPreventedAt,
+                        calculatedAt: metrics.calculatedAt,
+                        avgPainSeverityPrevented: 0,
+                        totalOpportunities: 0,
+                        adheredCount: 0,
+                        violatedCount: 0,
+                        implementationCost: 0,
+                        benefitScore: 0,
+                    });
+                }
+                catch (e) {
+                    SystemLogger.log(workspaceDir, 'METRICS_UPDATE_SKIP', String(e));
+                }
+            }
+        });
+    }
+    catch (e) {
+        SystemLogger.log(workspaceDir, 'PRINCIPLE_TRACK_SKIP', String(e));
+    }
+    wctx.eventLog.recordPainSignal(sessionId, {
+        score: observation.painScore,
+        source: failureSource,
+        reason: `Tool ${event.toolName} failed on ${observation.relPath}`,
+        isRisky: observation.isRisk,
+    });
+    const evoLogger = getEvolutionLogger(workspaceDir, wctx.trajectory);
+    evoLogger.logPainDetected({
+        traceId: observation.traceId,
+        source: failureSource,
+        reason: `Tool ${event.toolName} failed on ${observation.relPath}`,
+        score: observation.painScore,
+        toolName: event.toolName,
+        filePath: observation.relPath,
+        sessionId,
+    });
+    // Create painId inline (matches original createPainId)
+    const painId = `pain_${Date.now()}_${observation.errorHash.slice(0, 8)}`;
+    emitPainDetectedEvent(wctx, {
+        ts: new Date().toISOString(),
+        type: 'pain_detected',
+        data: {
+            painId,
+            painType: failureSource,
+            source: event.toolName,
+            reason: `Tool ${event.toolName} failed on ${observation.relPath}; diagnosticGate=${admission.reason}`,
+            score: observation.painScore,
+            sessionId,
+            traceId: observation.traceId,
+            agentId,
+            provenance: 'automatic_hook',
+            evidence: buildTrajectoryEvidence(wctx, sessionId),
+        },
+    });
+}
+// ── Shared Helpers ──────────────────────────────────────────────────────────
+export { buildTrajectoryEvidence } from './trajectory-evidence.js';
+/**
+ * Reset trigger cooldown state (for tests).
+ */
+export function resetTriggerCooldownForTest() {
+    clearCooldownState(TRIGGER_COOLDOWN_MAP);
+}
+// ── Source Classification ────────────────────────────────────────────────────
+// classifyToolFailureSource logic is now in resolveSourceKind (PRI-360 S1)
+// This function is removed to avoid duplication.
+/**
+ * Extract error type classification from error value.
+ */
+function extractErrorType(error) {
+    if (!error)
+        return 'Unknown';
+    const msg = String(error);
+    if (msg.includes('EACCES') || msg.includes('permission denied'))
+        return 'EACCES';
+    if (msg.includes('ENOENT') || msg.includes('no such file'))
+        return 'ENOENT';
+    if (msg.includes('EISDIR'))
+        return 'EISDIR';
+    if (msg.includes('ENOSPC'))
+        return 'ENOSPC';
+    if (msg.includes('SyntaxError'))
+        return 'SyntaxError';
+    if (msg.includes('TypeError'))
+        return 'TypeError';
+    if (msg.includes('ReferenceError'))
+        return 'ReferenceError';
+    if (msg.includes('timeout') || msg.includes('ETIMEDOUT'))
+        return 'Timeout';
+    if (msg.includes('network') || msg.includes('ECONNREFUSED'))
+        return 'Network';
+    return 'Other';
+}

package/dist/hooks/after-tool-call-types.d.ts

@@ -0,0 +1,86 @@
+/**
+ * After-Tool-Call Decomposition Types — PRI-326
+ *
+ * Shared types for the decomposed handleAfterToolCall pipeline.
+ * These types make the pipeline stages explicit without introducing
+ * the larger RawObservation/PainEpisode/PainEvidence architecture.
+ *
+ * ERR checklist:
+ * - ERR-001: No `as` casts in this file; these are type definitions only.
+ * - ERR-002: Every decision/result carries structured reason + nextAction.
+ * - EP-01: These types document boundaries, not runtime validation targets.
+ */
+import type { SessionState } from '../core/session-tracker.js';
+/**
+ * Result of classifying what happened in a tool call event.
+ *
+ * Pure extraction — no I/O, no side effects.
+ */
+export interface ToolCallOutcome {
+    /** Whether the tool call is considered a failure */
+    readonly isFailure: boolean;
+    /** Resolved exit code (numeric, 0 if success/absent) */
+    readonly exitCode: number;
+    /** For failures: classified as 'tool_failure' or 'dispatch_error' */
+    readonly failureSource: 'tool_failure' | 'dispatch_error' | undefined;
+}
+/**
+ * Normalized observation built from the tool call event and context.
+ *
+ * Used by friction tracking, event recording, and pain admission.
+ * Constructed after classification, before any I/O.
+ */
+export interface ToolCallObservation {
+    /** Tool parameters (typed subset) */
+    readonly params: {
+        readonly filePath?: string;
+        readonly content?: string;
+        readonly text?: string;
+        readonly newString?: string;
+        readonly query?: string;
+        readonly input?: string;
+        readonly arguments?: string;
+    };
+    /** File path relative to workspace */
+    readonly relPath: string;
+    /** Whether the file path is in the risk set */
+    readonly isRisk: boolean;
+    /** Error type classification string */
+    readonly errorType: string;
+    /** Denoised, hashed error identifier */
+    readonly errorHash: string;
+    /** Error text for logging */
+    readonly errorText: string;
+    /** Pain score (only meaningful for write-tool failures on risky paths) */
+    readonly painScore: number;
+    /** Trace ID for this observation chain */
+    readonly traceId: string;
+}
+/**
+ * Result of evaluating whether a tool failure should trigger pain diagnosis.
+ *
+ * Encapsulates the single-gate trigger controller decision.
+ */
+export interface PainAdmissionDecision {
+    /** Whether the tool failure should proceed to pain emission */
+    readonly admitted: boolean;
+    /** The admission stage that made the decision */
+    readonly stage: 'not_applicable' | 'trigger_admitted' | 'trigger_rejected';
+    /** Human-readable reason for the decision */
+    readonly reason: string;
+    /** Detail about the decision */
+    readonly detail: string;
+}
+/**
+ * Result of friction tracking for a tool call.
+ */
+export interface FrictionUpdateResult {
+    /** GFI before this update */
+    readonly gfiBefore: number;
+    /** GFI after this update */
+    readonly gfiAfter: number;
+    /** Updated session state (if failure) */
+    readonly sessionState: SessionState | undefined;
+    /** The error hash used for tracking */
+    readonly errorHash: string;
+}

package/dist/hooks/after-tool-call-types.js

@@ -0,0 +1,13 @@
+/**
+ * After-Tool-Call Decomposition Types — PRI-326
+ *
+ * Shared types for the decomposed handleAfterToolCall pipeline.
+ * These types make the pipeline stages explicit without introducing
+ * the larger RawObservation/PainEpisode/PainEvidence architecture.
+ *
+ * ERR checklist:
+ * - ERR-001: No `as` casts in this file; these are type definitions only.
+ * - ERR-002: Every decision/result carries structured reason + nextAction.
+ * - EP-01: These types document boundaries, not runtime validation targets.
+ */
+export {};

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