principles-disciple 1.5.4

package/dist/hooks/llm.js

@@ -0,0 +1,153 @@
+import * as fs from 'fs';
+import * as path from 'path';
+import { trackLlmOutput, recordThinkingCheckpoint } from '../core/session-tracker.js';
+import { writePainFlag } from '../core/pain.js';
+import { DetectionService } from '../core/detection-service.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+export function handleLlmOutput(event, ctx) {
+    if (!ctx.workspaceDir || !ctx.sessionId)
+        return;
+    const wctx = WorkspaceContext.fromHookContext(ctx);
+    const config = wctx.config;
+    const eventLog = wctx.eventLog;
+    // Track this turn in the core session memory
+    const state = trackLlmOutput(ctx.sessionId, event.usage, config, ctx.workspaceDir);
+    // We need actual assistant text to analyze
+    if (!event.assistantTexts || event.assistantTexts.length === 0)
+        return;
+    const text = event.assistantTexts.join('\n');
+    // ── Track B: Semantic Pain Detection (V1.3.0 Funnel) ──
+    const detectionService = DetectionService.get(wctx.stateDir);
+    const detection = detectionService.detect(text);
+    if (detection.detected) {
+        eventLog.recordRuleMatch(ctx.sessionId, {
+            ruleId: detection.ruleId || detection.source,
+            layer: detection.source === 'l1_exact' ? 'L1' : (detection.source === 'l2_cache' ? 'L2' : 'L3'),
+            severity: detection.severity || 0,
+            textPreview: text.substring(0, 100)
+        });
+    }
+    let painScore = detection.detected ? (detection.severity || 0) : 0;
+    let source = detection.detected
+        ? (detection.ruleId ? `llm_${detection.ruleId.toLowerCase()}` : `llm_${detection.source}`)
+        : '';
+    let matchedReason = detection.detected
+        ? `Agent triggered pain detection (Source: ${detection.source}${detection.ruleId ? `, Rule: ${detection.ruleId}` : ''})`
+        : '';
+    // 3. Paralysis Check (from session state tracker)
+    const stuckThreshold = config.get('thresholds.stuck_loops_trigger') || 3;
+    const inputThreshold = config.get('thresholds.cognitive_paralysis_input') || 4000;
+    const paralysisScore = config.get('scores.paralysis') || 40;
+    if (state.stuckLoops >= stuckThreshold && state.totalInputTokens > inputThreshold && painScore < paralysisScore) {
+        painScore = paralysisScore;
+        source = 'llm_paralysis';
+        matchedReason = `Agent is stuck in low-output loops (${state.stuckLoops} consecutive turns with tiny output but huge context), indicating cognitive paralysis.`;
+    }
+    // If a pain threshold is crossed, write the autonomous pain flag
+    const painTriggerThreshold = config.get('thresholds.pain_trigger') || 30;
+    if (painScore >= painTriggerThreshold) {
+        // Inject the actual text snippet that triggered this for the diagnostician to read later
+        const snippet = text.length > 200 ? text.substring(0, 100) + '...' + text.substring(text.length - 100) : text;
+        writePainFlag(ctx.workspaceDir, {
+            source,
+            score: String(painScore),
+            time: new Date().toISOString(),
+            reason: matchedReason,
+            is_risky: 'false',
+            trigger_text_preview: snippet
+        });
+        eventLog.recordPainSignal(ctx.sessionId, {
+            score: painScore,
+            source: source,
+            reason: matchedReason,
+            isRisky: false
+        });
+    }
+    // ═══ Thinking OS: Mental Model Usage Tracking ═══
+    trackThinkingModelUsage(text, wctx, ctx.sessionId);
+}
+const THINKING_MODEL_SIGNALS = {
+    'T-01': [
+        /let me (first )?(understand|map|outline|survey|review the (structure|architecture|dependencies))/i,
+        /让我先(梳理|了解|画出|理解|查看)(一下)?(结构|架构|依赖|全貌)/,
+    ],
+    'T-02': [
+        /(type|test|contract|schema|interface) (constraint|requirement|check|validation)/i,
+        /we (must|need to) (respect|follow|adhere to) the/i,
+        /(必须|需要).*?(遵守|符合|满足).*?(类型|测试|契约|接口|规范)/,
+    ],
+    'T-03': [
+        /based on (the |this )?(evidence|logs?|output|error|stack trace|test result)/i,
+        /let me (check|verify|confirm|read|look at) (the |)(actual|source|code|file|log)/i,
+        /根据(日志|证据|输出|报错|堆栈|测试结果)/,
+    ],
+    'T-04': [
+        /this (is|would be) (irreversible|destructive|permanent|not easily undone)/i,
+        /(reversible|can be undone|safely roll back)/i,
+        /(不可逆|破坏性|永久的|无法回滚|可以回滚|安全地撤销)/,
+    ],
+    'T-05': [
+        /we (must|should) (not|never|avoid|prevent|ensure we don't)/i,
+        /(critical|important) (not to|that we don't|to avoid)/i,
+        /(绝不能|必须避免|不可以|禁止|确保不会)/,
+    ],
+    'T-06': [
+        /(simpl(er|est|ify)|minimal|straightforward|lean) (approach|solution|fix|implementation)/i,
+        /(simple is better|keep it simple|no need to over)/i,
+        /(最简(单|洁)|精简|没有必要(过度|额外))/,
+    ],
+    'T-07': [
+        /(minimal|smallest|narrowest|least) (change|diff|modification|impact)/i,
+        /only (change|modify|touch|edit) (the |what)/i,
+        /(最小(改动|变更|修改)|只(改|动|修))/,
+    ],
+    'T-08': [
+        /this (error|failure|issue) (tells us|indicates|signals|suggests|means)/i,
+        /let me (stop|pause|step back|reconsider|rethink)/i,
+        /这个(错误|失败|问题)(告诉我们|表明|说明|意味)/,
+        /让我(停下|暂停|退一步|重新(考虑|思考|审视))/,
+    ],
+    'T-09': [
+        /(break|split|decompose|divide) (this |the task |it )?(into|down)/i,
+        /(step 1|first,? (we|i|let's)|phase 1)/i,
+        /(拆分|分解|分步|分阶段|第一步)/,
+    ],
+};
+function trackThinkingModelUsage(text, wctx, sessionId) {
+    const logPath = wctx.resolve('THINKING_OS_USAGE');
+    const logDir = path.dirname(logPath);
+    if (!fs.existsSync(logDir))
+        fs.mkdirSync(logDir, { recursive: true });
+    let usageLog = {};
+    if (fs.existsSync(logPath)) {
+        try {
+            usageLog = JSON.parse(fs.readFileSync(logPath, 'utf8'));
+        }
+        catch (e) {
+            console.error(`[PD:LLM] Failed to parse thinking OS usage log: ${String(e)}`);
+        }
+    }
+    let anyMatch = false;
+    for (const [modelId, patterns] of Object.entries(THINKING_MODEL_SIGNALS)) {
+        for (const pattern of patterns) {
+            if (pattern.test(text)) {
+                usageLog[modelId] = (usageLog[modelId] || 0) + 1;
+                anyMatch = true;
+                break;
+            }
+        }
+    }
+    usageLog['_total_turns'] = (usageLog['_total_turns'] || 0) + 1;
+    if (anyMatch) {
+        // Record thinking checkpoint for gate enforcement
+        if (sessionId) {
+            recordThinkingCheckpoint(sessionId, wctx.workspaceDir);
+        }
+        try {
+            fs.writeFileSync(logPath, JSON.stringify(usageLog, null, 2), 'utf8');
+        }
+        catch (e) {
+            console.error(`[PD:LLM] Failed to write thinking OS usage log: ${String(e)}`);
+        }
+    }
+}

package/dist/hooks/pain.d.ts

@@ -0,0 +1,5 @@
+import type { PluginHookAfterToolCallEvent, PluginHookToolContext, OpenClawPluginApi } from '../openclaw-sdk.js';
+export declare function handleAfterToolCall(event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext & {
+    workspaceDir?: string;
+    pluginConfig?: Record<string, unknown>;
+}, api?: OpenClawPluginApi): void;

package/dist/hooks/pain.js

@@ -0,0 +1,173 @@
+import * as fs from 'fs';
+import { isRisky, normalizePath } from '../utils/io.js';
+import { normalizeProfile } from '../core/profile.js';
+import { computePainScore, writePainFlag } from '../core/pain.js';
+import { trackFriction, resetFriction } from '../core/session-tracker.js';
+import { denoiseError, computeHash } from '../utils/hashing.js';
+import { SystemLogger } from '../core/system-logger.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+const WRITE_TOOLS = ['write', 'edit', 'apply_patch', 'write_file', 'edit_file', 'replace'];
+export function handleAfterToolCall(event, ctx, api) {
+    const effectiveWorkspaceDir = ctx.workspaceDir || api?.workspaceDir || api?.resolvePath?.('.');
+    if (!effectiveWorkspaceDir) {
+        return;
+    }
+    const wctx = WorkspaceContext.fromHookContext({ ...ctx, workspaceDir: effectiveWorkspaceDir });
+    const config = wctx.config;
+    const eventLog = wctx.eventLog;
+    const trust = wctx.trust;
+    const sessionId = ctx.sessionId || 'unknown';
+    const params = event.params;
+    // ── Track A: Empirical Friction (GFI) ──
+    // 0. Special Case: Manual Pain Intervention
+    if (event.toolName === 'pain' || event.toolName === 'skill:pain') {
+        const reason = params.input || params.arguments || 'Manual intervention';
+        trackFriction(sessionId, 100, 'manual_pain', effectiveWorkspaceDir);
+        SystemLogger.log(effectiveWorkspaceDir, 'MANUAL_PAIN', `User manually triggered pain: ${reason}`);
+        eventLog.recordPainSignal(sessionId, {
+            score: 100,
+            source: 'manual',
+            reason: `User intervention: ${reason}`,
+            isRisky: true
+        });
+        return;
+    }
+    // 1. Determine if this was a failure
+    const exitCode = (event.result && typeof event.result === 'object') ? event.result.exitCode : 0;
+    const isFailure = !!event.error || (exitCode !== 0 && exitCode !== undefined);
+    if (isFailure) {
+        const errorText = event.error || (typeof event.result === 'string' ? event.result : JSON.stringify(event.result));
+        const denoised = denoiseError(errorText);
+        const hash = computeHash(denoised);
+        const deltaF = config.get('scores.tool_failure_friction') || 30;
+        const updatedState = trackFriction(sessionId, deltaF, hash, effectiveWorkspaceDir);
+        // ── Trust Engine: Record failure ──
+        const errorType = extractErrorType(event.error || errorText);
+        const filePath = params.file_path || params.path || params.file;
+        const relPath = typeof filePath === 'string' ? normalizePath(filePath, effectiveWorkspaceDir) : 'unknown';
+        // Load profile for risk_paths check
+        const profilePath = wctx.resolve('PROFILE');
+        let profile = normalizeProfile({});
+        if (fs.existsSync(profilePath)) {
+            try {
+                profile = normalizeProfile(JSON.parse(fs.readFileSync(profilePath, 'utf8')));
+            }
+            catch (_e) { }
+        }
+        const isRisk = isRisky(relPath, profile.risk_paths);
+        trust.recordFailure(isRisk ? 'risky' : 'tool', {
+            sessionId,
+            api,
+            toolName: event.toolName // 👈 NEW: Pass toolName for classification
+        });
+        // Record tool call failure event
+        eventLog.recordToolCall(sessionId, {
+            toolName: event.toolName,
+            filePath: typeof filePath === 'string' ? filePath : undefined,
+            error: event.error ? String(event.error).substring(0, 200) : undefined,
+            errorType,
+            gfi: updatedState.currentGfi,
+            consecutiveErrors: updatedState.consecutiveErrors,
+            exitCode,
+        });
+    }
+    else {
+        // ── SUCCESS BRANCH ──
+        resetFriction(sessionId, effectiveWorkspaceDir);
+        // 👈 Record success to reset failure streak and earn minor trust (if constructive)
+        trust.recordSuccess('tool_success', {
+            sessionId,
+            api,
+            toolName: event.toolName // 👈 NEW: Pass toolName for classification
+        });
+        if (WRITE_TOOLS.includes(event.toolName)) {
+            const filePath = params.file_path || params.path || params.file;
+            eventLog.recordToolCall(sessionId, {
+                toolName: event.toolName,
+                filePath: typeof filePath === 'string' ? filePath : undefined,
+                gfi: 0,
+            });
+            // ── Hygiene Tracking: Record persistence actions ──
+            if (typeof filePath === 'string') {
+                const normalized = 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) {
+                    const content = params.content || params.new_string || '';
+                    wctx.hygiene.recordPersistence({
+                        ts: new Date().toISOString(),
+                        tool: event.toolName,
+                        path: filePath,
+                        type: isMemory ? 'memory' : 'plan',
+                        contentLength: content.length,
+                    });
+                }
+            }
+        }
+        // Special case for memory_store tool (Success only)
+        if (event.toolName === 'memory_store') {
+            const text = params.text || '';
+            wctx.hygiene.recordPersistence({
+                ts: new Date().toISOString(),
+                tool: event.toolName,
+                path: 'DATABASE',
+                type: 'memory',
+                contentLength: text.length,
+            });
+        }
+    }
+    // ── Legacy/Risky Write Pain Logic (Unified WRITE_TOOLS) ──
+    if (!WRITE_TOOLS.includes(event.toolName) || !isFailure) {
+        return;
+    }
+    const filePath = params.file_path || params.path || params.file;
+    const relPath = typeof filePath === 'string' ? normalizePath(filePath, effectiveWorkspaceDir) : 'unknown';
+    const profilePath = wctx.resolve('PROFILE');
+    let profile = normalizeProfile({});
+    if (fs.existsSync(profilePath)) {
+        try {
+            profile = normalizeProfile(JSON.parse(fs.readFileSync(profilePath, 'utf8')));
+        }
+        catch (_e) { }
+    }
+    const isRisk = isRisky(relPath, profile.risk_paths);
+    const painScore = computePainScore(1, false, false, isRisk ? 20 : 0, effectiveWorkspaceDir);
+    const painData = {
+        score: String(painScore),
+        source: 'tool_failure',
+        time: new Date().toISOString(),
+        reason: `Tool ${event.toolName} failed on ${relPath}. Error: ${event.error ?? 'Non-zero exit code'}`,
+        is_risky: String(isRisk),
+    };
+    writePainFlag(effectiveWorkspaceDir, painData);
+    eventLog.recordPainSignal(sessionId, {
+        score: painScore,
+        source: 'tool_failure',
+        reason: `Tool ${event.toolName} failed on ${relPath}`,
+        isRisky: isRisk,
+    });
+}
+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/prompt.d.ts

@@ -0,0 +1,38 @@
+import type { PluginHookBeforePromptBuildEvent, PluginHookAgentContext, PluginHookBeforePromptBuildResult, PluginLogger } from '../openclaw-sdk.js';
+/**
+ * 代理默认配置
+ */
+interface AgentsDefaultsConfig {
+    model?: unknown;
+    subagents?: {
+        model?: unknown;
+    };
+}
+/**
+ * OpenClaw API 接口定义（Prompt Hook 所需部分）
+ */
+interface PromptHookApi {
+    config?: {
+        agents?: {
+            defaults?: AgentsDefaultsConfig;
+        };
+    };
+    logger: PluginLogger;
+}
+/**
+ * 从 OpenClaw 配置中解析模型选择
+ * 支持 string 或 { primary, fallbacks } 格式
+ * @internal 导出仅供测试使用
+ */
+export declare function resolveModelFromConfig(modelConfig: unknown, logger?: PluginLogger): string | null;
+/**
+ * 获取诊断子智能体应使用的模型
+ * 优先级：subagents.model > 主模型
+ * 如果都没有配置，抛出错误
+ * @internal 导出仅供测试使用
+ */
+export declare function getDiagnosticianModel(api: PromptHookApi | null, logger?: PluginLogger): string;
+export declare function handleBeforePromptBuild(event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext & {
+    api?: PromptHookApi;
+}): Promise<PluginHookBeforePromptBuildResult | void>;
+export {};

package/dist/hooks/prompt.js

@@ -0,0 +1,285 @@
+import * as fs from 'fs';
+import { getSession, resetFriction } from '../core/session-tracker.js';
+import { WorkspaceContext } from '../core/workspace-context.js';
+/**
+ * 验证模型字符串格式是否为 "provider/model"
+ */
+function isValidModelFormat(model) {
+    // 格式: "provider/model" 或 "provider/model-variant"
+    // provider: 字母数字和连字符，不能以连字符开头/结尾
+    // model: 字母数字、连字符、点号、下划线
+    const MODEL_PATTERN = /^[a-zA-Z0-9][a-zA-Z0-9-]*[a-zA-Z0-9]\/[a-zA-Z0-9._-]+$/;
+    return MODEL_PATTERN.test(model);
+}
+/**
+ * 从 OpenClaw 配置中解析模型选择
+ * 支持 string 或 { primary, fallbacks } 格式
+ * @internal 导出仅供测试使用
+ */
+export function resolveModelFromConfig(modelConfig, logger) {
+    if (!modelConfig)
+        return null;
+    // 格式 1: "provider/model" 字符串
+    if (typeof modelConfig === 'string') {
+        const trimmed = modelConfig.trim();
+        if (!trimmed)
+            return null;
+        if (!isValidModelFormat(trimmed)) {
+            logger?.warn(`[PD:Prompt] Invalid model format: "${trimmed}". Expected "provider/model" format.`);
+            return null;
+        }
+        return trimmed;
+    }
+    // 格式 2: { primary: "provider/model", fallbacks: [...] } 对象
+    if (typeof modelConfig === 'object' && modelConfig !== null && !Array.isArray(modelConfig)) {
+        const cfg = modelConfig;
+        if (cfg.primary && typeof cfg.primary === 'string') {
+            const trimmed = cfg.primary.trim();
+            if (!trimmed)
+                return null;
+            if (!isValidModelFormat(trimmed)) {
+                logger?.warn(`[PD:Prompt] Invalid primary model format: "${trimmed}". Expected "provider/model" format.`);
+                return null;
+            }
+            return trimmed;
+        }
+    }
+    // 格式 3: 数组格式（不支持，发出警告）
+    if (Array.isArray(modelConfig)) {
+        console.warn(`[PD:Prompt] Array model config not supported. Expected "provider/model" string or { primary: "..." } object.`);
+        logger?.warn(`[PD:Prompt] Array model config not supported. Expected "provider/model" string or { primary: "..." } object.`);
+        return null;
+    }
+    return null;
+}
+/**
+ * 获取诊断子智能体应使用的模型
+ * 优先级：subagents.model > 主模型
+ * 如果都没有配置，抛出错误
+ * @internal 导出仅供测试使用
+ */
+export function getDiagnosticianModel(api, logger) {
+    // 兼容两种调用方式：
+    // 1. 新方式：getDiagnosticianModel(api) - api 包含 logger
+    // 2. 旧方式：getDiagnosticianModel(api, logger) - 分离参数
+    const effectiveLogger = api?.logger || logger;
+    if (!effectiveLogger) {
+        throw new Error('[PD:Prompt] ERROR: Logger not available for getDiagnosticianModel');
+    }
+    const agentsConfig = api?.config?.agents?.defaults;
+    // 优先使用子智能体专用模型
+    const subagentModel = resolveModelFromConfig(agentsConfig?.subagents?.model, effectiveLogger);
+    if (subagentModel) {
+        effectiveLogger.info(`[PD:Prompt] Using subagents.model for diagnostician: ${subagentModel}`);
+        return subagentModel;
+    }
+    // 备选：使用主智能体模型
+    const primaryModel = resolveModelFromConfig(agentsConfig?.model, effectiveLogger);
+    if (primaryModel) {
+        effectiveLogger.info(`[PD:Prompt] Using primary model for diagnostician (subagents.model not set): ${primaryModel}`);
+        return primaryModel;
+    }
+    // 没有配置任何模型，报错
+    const errorMsg = `[PD:Prompt] ERROR: No model configured for diagnostician subagent. ` +
+        `Please set 'agents.defaults.subagents.model' or 'agents.defaults.model' in OpenClaw config.`;
+    effectiveLogger.error(errorMsg);
+    throw new Error(errorMsg);
+}
+export async function handleBeforePromptBuild(event, ctx) {
+    const workspaceDir = ctx.workspaceDir;
+    if (!workspaceDir)
+        return;
+    const wctx = WorkspaceContext.fromHookContext(ctx);
+    const { trigger, sessionId, api } = ctx;
+    const logger = api?.logger; // 统一获取 logger
+    // Minimal mode: heartbeat and subagents skip project context/system caps to reduce tokens
+    // SessionId format: "agent:main:subagent:{type}-{id}" for subagents, "agent:main:..." for main
+    const isMinimalMode = trigger === "heartbeat" || sessionId?.includes(":subagent:") === true;
+    const focusPath = wctx.resolve('CURRENT_FOCUS');
+    const painFlagPath = wctx.resolve('PAIN_FLAG');
+    const capsPath = wctx.resolve('SYSTEM_CAPABILITIES');
+    const config = wctx.config;
+    const session = sessionId ? getSession(sessionId) : undefined;
+    let prependSystemContext = '';
+    let prependContext = '';
+    let appendSystemContext = '';
+    // ═══ LAYER 0 (道之源): Core Principles - Highest Priority ═══
+    const principlesPath = wctx.resolve('PRINCIPLES');
+    if (fs.existsSync(principlesPath)) {
+        try {
+            const principles = fs.readFileSync(principlesPath, 'utf8');
+            if (principles.trim()) {
+                prependSystemContext = `<core_principles>\n${principles.trim()}\n</core_principles>`;
+            }
+        }
+        catch (e) {
+            logger?.error(`[PD:Prompt] Failed to read PRINCIPLES: ${String(e)}`);
+        }
+    }
+    // 0. Manual Pain Clearance
+    if (trigger === 'user' && sessionId && session && session.currentGfi >= 100) {
+        resetFriction(sessionId, workspaceDir);
+    }
+    // ═══ LAYER 3 (道): Thinking OS + Reflection Checkpoint ═══
+    // Both are static, cacheable content - put in prependSystemContext for provider caching
+    const thinkingOsPath = wctx.resolve('THINKING_OS');
+    if (fs.existsSync(thinkingOsPath)) {
+        try {
+            const thinkingOs = fs.readFileSync(thinkingOsPath, 'utf8');
+            if (thinkingOs.trim()) {
+                prependSystemContext += `\n<thinking_os>\n${thinkingOs.trim()}\n</thinking_os>`;
+            }
+        }
+        catch (e) {
+            logger?.error(`[PD:Prompt] Failed to read THINKING_OS: ${String(e)}`);
+        }
+    }
+    // 1. Critical Reflection Logic (High Priority - Prompt Injection)
+    const reflectionLogPath = wctx.resolve('REFLECTION_LOG');
+    if (fs.existsSync(reflectionLogPath)) {
+        try {
+            const reflectionLog = fs.readFileSync(reflectionLogPath, 'utf8');
+            if (reflectionLog.trim()) {
+                prependContext += `\n<reflection_log>\n${reflectionLog.trim()}\n</reflection_log>\n`;
+            }
+        }
+        catch (e) {
+            logger?.error(`[PD:Prompt] Failed to read REFLECTION_LOG: ${String(e)}`);
+        }
+    }
+    // 2. Strategic focus (skip in minimal mode)
+    if (!isMinimalMode) {
+        if (fs.existsSync(focusPath)) {
+            try {
+                const currentFocus = fs.readFileSync(focusPath, 'utf8');
+                if (currentFocus.trim()) {
+                    prependContext += `\n<project_context>\n--- Strategic Focus ---\n${currentFocus.trim()}\n--- End of Strategic Focus ---\n</project_context>\n`;
+                }
+            }
+            catch (e) {
+                logger?.error(`[PD:Prompt] Failed to read CURRENT_FOCUS: ${String(e)}`);
+            }
+        }
+    }
+    // 3. Background Evolution Directives
+    let evolutionDirective = ''; // 用于存储进化指令，避免 return 导致上下文丢失
+    const queuePath = wctx.resolve('EVOLUTION_QUEUE');
+    if (fs.existsSync(queuePath)) {
+        try {
+            const queue = JSON.parse(fs.readFileSync(queuePath, 'utf8'));
+            const inProgressTask = queue.find((t) => t.status === 'in_progress');
+            if (inProgressTask) {
+                // High-intensity directive to force the agent to work on the evolution task
+                let diagnosticianModel = null;
+                try {
+                    if (api) {
+                        diagnosticianModel = getDiagnosticianModel(api);
+                    }
+                }
+                catch (err) {
+                    // 模型配置缺失，记录错误但不 return，继续注入其他上下文
+                    logger?.error(`[PD:Prompt] Failed to resolve diagnostician model: ${String(err)}`);
+                }
+                if (diagnosticianModel) {
+                    // 转义任务内容，防止注入攻击
+                    // 需要转义：反引号、$、反斜杠、双引号、换行符
+                    const escapedTask = inProgressTask.task
+                        .replace(/\\/g, '\\\\') // 先转义反斜杠
+                        .replace(/`/g, '\\`') // 转义反引号（模板字符串）
+                        .replace(/\$/g, '\\$') // 转义 $（模板字符串插值）
+                        .replace(/"/g, '\\"') // 转义双引号
+                        .replace(/\n/g, '\\n'); // 转义换行符
+                    logger?.info(`[PD:Prompt] Injecting SYSTEM OVERRIDE for evolution task: ${inProgressTask.id}`);
+                    evolutionDirective = `\n[🚨 SYSTEM OVERRIDE 🚨]\n` +
+                        `A critical evolution task is assigned to you. YOU MUST PRIORITIZE THIS TASK.\n` +
+                        `TASK: "${escapedTask}"\n\n` +
+                        `ACTION REQUIRED:\n` +
+                        `Reply ONLY with "[EVOLUTION_ACK]". Then immediately invoke the \`sessions_spawn\` tool:\n` +
+                        `\`\`\`\n` +
+                        `sessions_spawn target="diagnostician" message="${escapedTask}" model="${diagnosticianModel}"\n` +
+                        `\`\`\`\n` +
+                        `NO OTHER ACTIONS PERMITTED.`;
+                }
+            }
+        }
+        catch (e) {
+            logger?.error(`[PD:Prompt] Failed to parse EVOLUTION_QUEUE: ${String(e)}`);
+        }
+    }
+    // 4. Perceptive awareness: System Capabilities (skip in minimal mode)
+    if (!isMinimalMode) {
+        if (fs.existsSync(capsPath)) {
+            try {
+                const caps = fs.readFileSync(capsPath, 'utf8');
+                prependContext += `\n<system_capabilities>\n${caps}\n</system_capabilities>\n`;
+            }
+            catch (e) {
+                logger?.error(`[PD:Prompt] Failed to read SYSTEM_CAPABILITIES: ${String(e)}`);
+            }
+        }
+    }
+    // 5. Heartbeat-specific active checklist
+    if (trigger === 'heartbeat') {
+        const heartbeatPath = wctx.resolve('HEARTBEAT');
+        if (fs.existsSync(heartbeatPath)) {
+            try {
+                const heartbeatChecklist = fs.readFileSync(heartbeatPath, 'utf8');
+                prependContext += `\n<heartbeat_checklist>\n${heartbeatChecklist}\n\nDIRECTIVE: Perform a system-wide self-audit now. If everything is stable, strictly reply with "HEARTBEAT_OK" to minimize token usage.\n</heartbeat_checklist>\n`;
+            }
+            catch (e) {
+                logger?.error(`[PD:Prompt] Failed to read HEARTBEAT: ${String(e)}`);
+            }
+        }
+    }
+    // 6. Security Layer: Trust & Permission Awareness (Dynamic Content)
+    // 这些是动态内容，放入 <pd:internal_context> 以便 prependSystemContext 保持纯静态
+    const trustScore = wctx.trust.getScore();
+    const stage = wctx.trust.getStage();
+    const hygiene = wctx.hygiene.getStats();
+    // 1. 数值安全校验：防止异常值
+    // safeScore 范围: 0-100，safeStage 范围: 1-4（四个信任阶段）
+    const safeScore = Math.max(0, Math.min(100, Number(trustScore) || 0));
+    const safeStage = Math.max(1, Math.min(4, Number(stage) || 1));
+    // 2. 构建动态内部上下文（重命名 internalContext → dynamicContext）
+    let dynamicContext = '';
+    dynamicContext += `[CURRENT TRUST SCORE: ${safeScore}/100 (Stage ${safeStage})]\n`;
+    dynamicContext += `[COGNITIVE HYGIENE: ${hygiene.persistenceCount} persists today]\n`;
+    // 3. 视觉层次改进：Stage 1 使用更醒目的格式
+    if (safeStage === 1) {
+        dynamicContext += `\n[!CRITICAL!] Your trust score is critical. You are in read-only mode. Use diagnostician sub-agents to recover trust.\n`;
+    }
+    if (hygiene.persistenceCount === 0 && trigger === 'user') {
+        dynamicContext += `⚠️ ADVISORY: You haven't persisted any state today. To prevent "Goldfish Memory", consider updating PLAN.md or writing notes to memory/ if this session is becoming complex.\n`;
+    }
+    // 4. 使用命名空间前缀 (pd:internal_context)
+    if (dynamicContext.trim()) {
+        prependContext = `\n<pd:internal_context>\n${dynamicContext.trim()}\n</pd:internal_context>\n` + prependContext;
+    }
+    // 注入进化指令（如果有），放在 prependContext 最前面（高优先级）
+    if (evolutionDirective) {
+        prependContext = evolutionDirective + prependContext;
+    }
+    // ═══ SIZE GUARD: Prevent token explosion ═══
+    const totalSize = prependSystemContext.length + prependContext.length + appendSystemContext.length;
+    const MAX_SIZE = 10000;
+    if (totalSize > MAX_SIZE) {
+        const originalSize = totalSize;
+        // Truncate <project_context> to first 50 lines
+        const projectContextMatch = prependContext.match(/(<project_context>[\s\S]*?<\/project_context>)/);
+        if (projectContextMatch) {
+            const originalBlock = projectContextMatch[1];
+            const lines = originalBlock.split('\n');
+            if (lines.length > 50) {
+                const truncatedBlock = lines.slice(0, 50).join('\n') + '\n...[truncated]';
+                prependContext = prependContext.replace(originalBlock, truncatedBlock);
+            }
+        }
+        const newSize = prependSystemContext.length + prependContext.length + appendSystemContext.length;
+        logger?.warn(`[PD:Prompt] Injection size exceeded: ${originalSize} chars (limit: ${MAX_SIZE}), truncated to ${newSize} chars (${newSize - originalSize} saved)`);
+    }
+    return {
+        prependSystemContext,
+        prependContext,
+        appendSystemContext
+    };
+}

package/dist/hooks/subagent.d.ts

@@ -0,0 +1,2 @@
+import { PluginHookSubagentEndedEvent, PluginHookAgentContext } from '../openclaw-sdk.js';
+export declare function handleSubagentEnded(event: PluginHookSubagentEndedEvent, ctx: PluginHookAgentContext): Promise<void>;