create-principles-disciple 1.79.0 → 1.81.0

package/plugin/dist/index.js

@@ -1,7 +1,5 @@
 import * as path from 'path';
-import * as fs from 'fs';
-import * as yaml from 'js-yaml';
-import { computeEffectiveFlags, DEFAULT_FEATURE_FLAGS } from '@principles/core/runtime-v2';
+import { loadFeatureFlagFromConfig } from './core/pd-config-loader.js';
 import { classifyTask } from './core/local-worker-routing.js';
 import { completeShadowObservation, recordShadowRouting } from './core/shadow-observation-registry.js';
 import { getCommandDescription } from './i18n/commands.js';
@@ -39,72 +37,28 @@ import { migrateDirectoryStructure } from './core/migration.js';
 import { migrateStaleWorkspaceGuidance } from './core/workspace-guidance-migrator.js';
 import { SystemLogger } from './core/system-logger.js';
 import { PathResolver } from './core/path-resolver.js';
-import { resolveCommandWorkspaceDir, resolveToolHookWorkspaceDirSafe } from './utils/workspace-resolver.js';
+import { resolveCommandWorkspaceDir, resolveToolHookWorkspaceDirSafe, resolveHookWorkspaceDir } from './utils/workspace-resolver.js';
 import { computeRuntimeShadowTaskFingerprint, PD_LOCAL_PROFILES } from './utils/shadow-fingerprint.js';
 import { validateWorkspaceDir } from './core/workspace-dir-validation.js';
 import { resolveWorkspaceDirFromApi } from './core/path-resolver.js';
 import { checkSurfaceGuard, guardHook, guardService } from './core/surface-guard.js';
 // Track started workspaces — one-time init + evolution worker per workspace
 const startedWorkspaces = new Set();
-const HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION = 'verify gateway plugin activation and hook workspace binding; ' +
-    'migrate live hook workspace resolution to PD-owned canonical configuration before relying on config-based recovery';
 // Map from childSessionKey → shadowObservationId
 // Used to complete shadow observations when subagent ends
 const pendingShadowObservations = new Map();
 // ── Feature Flag Loader (plugin I/O boundary) ─────────────────────────────
 // Reads workspace feature-flags.yaml and checks a specific flag.
 // Returns the flag definition with effective enabled state.
-const DANGEROUS_KEYS = new Set(['__proto__', 'constructor', 'prototype']);
 function isRecord(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value);
 }
+/**
+ * PRI-305/PRI-307: Load feature flag from .pd/config.yaml instead of .pd/feature-flags.yaml.
+ * Delegates to the shared plugin config loader for consistency.
+ */
 function loadFeatureFlagFromWorkspace(workspaceDir, flagId, logger) {
-    const configPath = path.join(workspaceDir, '.pd', 'feature-flags.yaml');
-    if (!fs.existsSync(configPath)) {
-        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        const flag = flags.flags[flagId];
-        return { enabled: flag?.enabled ?? false, source: 'defaults' };
-    }
-    let raw;
-    try {
-        raw = fs.readFileSync(configPath, 'utf8');
-    }
-    catch (e) {
-        const msg = e instanceof Error ? e.message : String(e);
-        logger?.warn?.(`[PD:FeatureFlags] Feature flags unreadable: ${msg} — using defaults`);
-        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        const flag = flags.flags[flagId];
-        return { enabled: flag?.enabled ?? false, source: 'defaults' };
-    }
-    let parsed;
-    try {
-        parsed = yaml.load(raw, { schema: yaml.JSON_SCHEMA });
-    }
-    catch (e) {
-        const parseMsg = e instanceof Error ? e.message : String(e);
-        logger?.warn?.(`[PD:FeatureFlags] Feature flags YAML parse error: ${parseMsg} — using defaults`);
-        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        const flag = flags.flags[flagId];
-        return { enabled: flag?.enabled ?? false, source: 'defaults' };
-    }
-    if (!isRecord(parsed)) {
-        logger?.warn?.(`[PD:FeatureFlags] Feature flags not a mapping — using defaults`);
-        const flags = computeEffectiveFlags({}, DEFAULT_FEATURE_FLAGS, configPath);
-        const flag = flags.flags[flagId];
-        return { enabled: flag?.enabled ?? false, source: 'defaults' };
-    }
-    // parsed is now narrowed to Record<string, unknown> by isRecord guard
-    const parsedRecord = Object.create(null);
-    for (const key of Object.keys(parsed)) {
-        if (DANGEROUS_KEYS.has(key))
-            continue;
-        if (Object.hasOwn(parsed, key)) {
-            parsedRecord[key] = parsed[key];
-        }
-    }
-    const flags = computeEffectiveFlags(parsedRecord, DEFAULT_FEATURE_FLAGS, configPath);
-    const flag = flags.flags[flagId];
-    return { enabled: flag?.enabled ?? false, source: flags.source };
+    return loadFeatureFlagFromConfig(workspaceDir, flagId, logger);
 }
 export function shouldStartEvolutionWorker(workspaceDir, logger) {
     const flag = loadFeatureFlagFromWorkspace(workspaceDir, 'evolution_worker', logger);
@@ -113,7 +67,7 @@ export function shouldStartEvolutionWorker(workspaceDir, logger) {
     }
     const disabledInfo = JSON.stringify({
         reason: 'mvp_quiet_per_adr0014',
-        nextAction: 'set evolution_worker.enabled=true in .pd/feature-flags.yaml to enable',
+        nextAction: 'set features.evolution_worker.enabled=true in .pd/config.yaml to enable',
         featureFlag: 'evolution_worker',
         boundedContext: 'legacy_evolution_worker',
         flagSource: flag.source,
@@ -127,7 +81,7 @@ export function shouldStartCorrectionObserver(workspaceDir, logger) {
     }
     const disabledInfo = JSON.stringify({
         reason: 'correction_observer_disabled',
-        nextAction: 'set correction_observer.enabled=true in .pd/feature-flags.yaml to enable',
+        nextAction: 'set features.correction_observer.enabled=true in .pd/config.yaml to enable',
         featureFlag: 'correction_observer',
         boundedContext: 'correction_observer_service',
         flagSource: flag.source,
@@ -170,15 +124,18 @@ const plugin = {
         const language = api.pluginConfig?.language || 'en';
         // ── Hook: Prompt Building ──
         api.on('before_prompt_build', guardHook('hook:before_prompt_build', api.logger, async (event, ctx) => {
-            const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_prompt_build');
-            if (!workspaceDir) {
+            const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_prompt_build');
+            if (!wsResult.ok) {
                 api.logger.error(`[PD:before_prompt_build] workspaceDir resolution failed. ` +
-                    `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'} ` +
-                    `sessionKey=${ctx.sessionKey ?? '(missing)'}. ` +
+                    `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
                     `Hook skipped — no mutation will occur. ` +
-                    `NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`);
+                    `NextAction: ${wsResult.nextAction}`);
                 return;
             }
+            const workspaceDir = wsResult.workspaceDir;
+            if (wsResult.consistencyWarning) {
+                api.logger.warn(`[PD:before_prompt_build] ${wsResult.consistencyWarning}`);
+            }
             try {
                 if (!startedWorkspaces.has(workspaceDir)) {
                     startedWorkspaces.add(workspaceDir);
@@ -240,15 +197,18 @@ const plugin = {
         }));
         // ── Hook: Security Gate ──
         api.on('before_tool_call', guardHook('hook:before_tool_call', api.logger, (event, ctx) => {
-            const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_tool_call');
-            if (!workspaceDir) {
+            const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_tool_call');
+            if (!wsResult.ok) {
                 api.logger.error(`[PD:before_tool_call] workspaceDir resolution failed. ` +
-                    `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'} ` +
-                    `sessionKey=${ctx.sessionKey ?? '(missing)'}. ` +
+                    `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
                     `Hook skipped — security gate bypassed. ` +
-                    `NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`);
+                    `NextAction: ${wsResult.nextAction}`);
                 return;
             }
+            const workspaceDir = wsResult.workspaceDir;
+            if (wsResult.consistencyWarning) {
+                api.logger.warn(`[PD:before_tool_call] ${wsResult.consistencyWarning}`);
+            }
             try {
                 const pluginConfig = api.pluginConfig ?? {};
                 const { logger } = api;
@@ -268,15 +228,18 @@ const plugin = {
         }));
         // ── Hook: Pain & Trust ──
         api.on('after_tool_call', guardHook('hook:after_tool_call', api.logger, (event, ctx) => {
-            const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'after_tool_call');
-            if (!workspaceDir) {
+            const wsResult = resolveHookWorkspaceDir(ctx, api, 'after_tool_call');
+            if (!wsResult.ok) {
                 api.logger.error(`[PD:after_tool_call] workspaceDir resolution failed. ` +
-                    `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'} ` +
-                    `sessionKey=${ctx.sessionKey ?? '(missing)'}. ` +
+                    `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
                     `Hook skipped — pain detection bypassed. ` +
-                    `NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`);
+                    `NextAction: ${wsResult.nextAction}`);
                 return;
             }
+            const workspaceDir = wsResult.workspaceDir;
+            if (wsResult.consistencyWarning) {
+                api.logger.warn(`[PD:after_tool_call] ${wsResult.consistencyWarning}`);
+            }
             try {
                 const pluginConfig = api.pluginConfig ?? {};
                 // Pass api separately to handleAfterToolCall to maintain type safety
@@ -295,15 +258,19 @@ const plugin = {
         }));
         // ── Hook: LLM Analysis ──
         api.on('llm_output', guardHook('hook:llm_output', api.logger, (event, ctx) => {
-            const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'llm_output');
-            if (!workspaceDir) {
+            const wsResult = resolveHookWorkspaceDir(ctx, api, 'llm_output');
+            if (!wsResult.ok) {
                 api.logger.error(`[PD:llm_output] workspaceDir resolution failed. ` +
-                    `agentId=${ctx.agentId ?? '(missing)'} ` +
+                    `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} ` +
                     `sessionId=${ctx.sessionId ?? '(missing)'}. ` +
                     `Hook skipped — LLM analysis bypassed. ` +
-                    `NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`);
+                    `NextAction: ${wsResult.nextAction}`);
                 return;
             }
+            const workspaceDir = wsResult.workspaceDir;
+            if (wsResult.consistencyWarning) {
+                api.logger.warn(`[PD:llm_output] ${wsResult.consistencyWarning}`);
+            }
             try {
                 handleLlmOutput(event, { ...ctx, workspaceDir });
                 WorkspaceContext.fromHookContext({ workspaceDir }).eventLog.recordHookExecution({
@@ -423,41 +390,50 @@ const plugin = {
         }));
         // ── Hook: Lifecycle ──
         api.on('before_reset', guardHook('hook:before_reset', api.logger, (event, ctx) => {
-            const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_reset');
-            if (!workspaceDir) {
+            const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_reset');
+            if (!wsResult.ok) {
                 api.logger.error(`[PD:before_reset] workspaceDir resolution failed. ` +
-                    `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
-                    `Hook skipped. NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`);
+                    `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
+                    `Hook skipped. NextAction: ${wsResult.nextAction}`);
                 return;
             }
-            return handleBeforeReset(event, { ...ctx, workspaceDir });
+            if (wsResult.consistencyWarning) {
+                api.logger.warn(`[PD:before_reset] ${wsResult.consistencyWarning}`);
+            }
+            return handleBeforeReset(event, { ...ctx, workspaceDir: wsResult.workspaceDir });
         }));
         api.on('before_compaction', guardHook('hook:before_compaction', api.logger, (event, ctx) => {
-            const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'before_compaction');
-            if (!workspaceDir) {
+            const wsResult = resolveHookWorkspaceDir(ctx, api, 'before_compaction');
+            if (!wsResult.ok) {
                 api.logger.error(`[PD:before_compaction] workspaceDir resolution failed. ` +
-                    `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
-                    `Hook skipped. NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`);
+                    `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
+                    `Hook skipped. NextAction: ${wsResult.nextAction}`);
                 return;
             }
-            return handleBeforeCompaction(event, { ...ctx, workspaceDir });
+            if (wsResult.consistencyWarning) {
+                api.logger.warn(`[PD:before_compaction] ${wsResult.consistencyWarning}`);
+            }
+            return handleBeforeCompaction(event, { ...ctx, workspaceDir: wsResult.workspaceDir });
         }));
         api.on('after_compaction', guardHook('hook:after_compaction', api.logger, (event, ctx) => {
-            const workspaceDir = resolveToolHookWorkspaceDirSafe(ctx, api, 'after_compaction');
-            if (!workspaceDir) {
+            const wsResult = resolveHookWorkspaceDir(ctx, api, 'after_compaction');
+            if (!wsResult.ok) {
                 api.logger.error(`[PD:after_compaction] workspaceDir resolution failed. ` +
-                    `agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
-                    `Hook skipped. NextAction: ${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}`);
+                    `reason=${wsResult.reason} agentId=${ctx.agentId ?? '(missing)'} sessionId=${ctx.sessionId ?? '(missing)'}. ` +
+                    `Hook skipped. NextAction: ${wsResult.nextAction}`);
                 return;
             }
-            return handleAfterCompaction(event, { ...ctx, workspaceDir });
+            if (wsResult.consistencyWarning) {
+                api.logger.warn(`[PD:after_compaction] ${wsResult.consistencyWarning}`);
+            }
+            return handleAfterCompaction(event, { ...ctx, workspaceDir: wsResult.workspaceDir });
         }));
-        // ── Service: Background Evolution Worker ──
+        // ── Service Registration (surface-guarded) ──
+        // PRI-294: EvolutionWorker service registration removed — it starts via
+        // before_prompt_build hook gate, not via api.registerService. The surface
+        // guard already prevents registration when disabled (enabledByDefault=false).
+        // Dead pre-assignment of EvolutionWorkerService.api removed.
         try {
-            EvolutionWorkerService.api = api;
-            const guardedEvolutionWorker = guardService('service:evolution-worker', EvolutionWorkerService, api.logger);
-            if (guardedEvolutionWorker)
-                api.registerService(guardedEvolutionWorker);
             const guardedCorrectionObserver = guardService('service:correction-observer', CorrectionObserverService, api.logger);
             if (guardedCorrectionObserver)
                 api.registerService(guardedCorrectionObserver);

package/plugin/dist/service/correction-observer-service.d.ts

@@ -6,6 +6,14 @@ export interface CorrectionObserverServiceShape {
     start: (ctx: OpenClawPluginServiceContext) => void;
     stop?: (ctx: OpenClawPluginServiceContext) => void;
 }
+/**
+ * PRI-307: Resolve CorrectionObserver from .pd/config.yaml.
+ *
+ * States:
+ * - disabled: feature flag off → return null, no noisy logs
+ * - needs_setup: enabled but missing API key or profile → return null with structured reason
+ * - ready/not_ready: enabled and configured → return observer instance
+ */
 export declare function resolveCorrectionObserver(wctx: WorkspaceContext, logger?: Pick<PluginLogger, 'info' | 'warn' | 'error' | 'debug'>): CorrectionObserver | null;
 export declare function runCorrectionObserverCycle(wctx: WorkspaceContext, logger: PluginLogger): Promise<void>;
 export declare const CorrectionObserverService: CorrectionObserverServiceShape;

package/plugin/dist/service/correction-observer-service.js

@@ -1,9 +1,10 @@
 import { WorkspaceContext } from '../core/workspace-context.js';
 import { TrajectoryRegistry } from '../core/trajectory.js';
 import { CorrectionCueLearner } from '../core/correction-cue-learner.js';
-import { WorkflowFunnelLoader, PiAiRuntimeAdapter, CorrectionObserver, AgentScheduler, } from '@principles/core/runtime-v2';
+import { PiAiRuntimeAdapter, CorrectionObserver, AgentScheduler, } from '@principles/core/runtime-v2';
 import { KeywordOptimizationService } from './keyword-optimization-service.js';
 import { SystemLogger } from '../core/system-logger.js';
+import { resolveObserverConfig } from '../core/pd-config-loader.js';
 let correctionObserverTimeoutId = null;
 let correctionObserverStopped = false;
 const startedWorkspaces = new Set();
@@ -11,40 +12,45 @@ const CORRECTION_OBSERVER_INTERVAL_MS = 15 * 60 * 1000;
 const CORRECTION_OBSERVER_INITIAL_DELAY_MS = 10_000;
 const CORRECTION_OBSERVER_MAX_RECENT_SESSIONS = 20;
 const CORRECTION_OBSERVER_MAX_PAYLOAD_SESSIONS = 5;
+/**
+ * PRI-307: Resolve CorrectionObserver from .pd/config.yaml.
+ *
+ * States:
+ * - disabled: feature flag off → return null, no noisy logs
+ * - needs_setup: enabled but missing API key or profile → return null with structured reason
+ * - ready/not_ready: enabled and configured → return observer instance
+ */
 export function resolveCorrectionObserver(wctx, logger) {
     try {
-        const loader = new WorkflowFunnelLoader(wctx.stateDir);
-        const funnel = loader.getFunnel('pd-correction-observer');
-        const policy = funnel?.policy;
-        if (!policy || policy.runtimeKind !== 'pi-ai') {
-            logger?.debug?.('[PD:CorrectionObserver] workflows.yaml pd-correction-observer policy not found. Falling back to environment variables.');
-            const provider = process.env.PD_CORRECTION_PROVIDER || 'anthropic';
-            const model = process.env.PD_CORRECTION_MODEL || 'anthropic/claude-3-5-sonnet';
-            const apiKeyEnv = process.env.PD_CORRECTION_API_KEY_ENV || 'ANTHROPIC_API_KEY';
-            const baseUrl = process.env.PD_CORRECTION_BASE_URL;
-            if (!process.env[apiKeyEnv]) {
-                logger?.debug?.(`[PD:CorrectionObserver] API key env ${apiKeyEnv} is not set. Periodic optimization disabled.`);
-                return null;
+        const observerConfig = resolveObserverConfig(wctx.workspaceDir, 'correction_observer', 'correctionObserver', logger);
+        if (!observerConfig.enabled) {
+            if (observerConfig.readiness === 'config_malformed') {
+                logger?.warn?.(`[PD:CorrectionObserver] Config malformed: ${observerConfig.reason}. ${observerConfig.nextAction}`);
             }
+            else {
+                logger?.debug?.(`[PD:CorrectionObserver] ${observerConfig.reason}`);
+            }
+            return null;
+        }
+        if (observerConfig.readiness === 'needs_setup') {
+            logger?.info?.(`[PD:CorrectionObserver] ${observerConfig.reason}. ${observerConfig.nextAction}`);
+            return null;
+        }
+        // ready or not_ready — create the observer
+        if (observerConfig.runtimeProfileType === 'pi-ai') {
             const adapter = new PiAiRuntimeAdapter({
-                provider,
-                model,
-                apiKeyEnv,
-                baseUrl,
+                provider: observerConfig.provider ?? 'anthropic',
+                model: observerConfig.model ?? 'anthropic/claude-3-5-sonnet',
+                apiKeyEnv: observerConfig.apiKeyEnv ?? 'ANTHROPIC_API_KEY',
+                timeoutMs: observerConfig.timeoutMs ?? undefined,
+                baseUrl: observerConfig.baseUrl ?? undefined,
                 workspace: wctx.workspaceDir,
             });
-            return new CorrectionObserver({ runtimeAdapter: adapter });
+            return new CorrectionObserver({ runtimeAdapter: adapter }, { timeoutMs: observerConfig.timeoutMs ?? undefined });
         }
-        const adapter = new PiAiRuntimeAdapter({
-            provider: String(policy.provider),
-            model: String(policy.model),
-            apiKeyEnv: String(policy.apiKeyEnv),
-            maxRetries: policy.maxRetries,
-            timeoutMs: policy.timeoutMs ?? 30_000,
-            baseUrl: policy.baseUrl,
-            workspace: wctx.workspaceDir,
-        });
-        return new CorrectionObserver({ runtimeAdapter: adapter }, { timeoutMs: policy.timeoutMs });
+        // OpenClaw profile — not yet supported for observer runtime
+        logger?.info?.(`[PD:CorrectionObserver] OpenClaw runtime profile not yet supported for correction observer. Skipping.`);
+        return null;
     }
     catch (err) {
         logger?.warn?.(`[PD:CorrectionObserver] Failed to resolve CorrectionObserver: ${String(err)}`);
@@ -55,7 +61,8 @@ export async function runCorrectionObserverCycle(wctx, logger) {
     try {
         const observer = resolveCorrectionObserver(wctx, logger);
         if (!observer) {
-            logger?.info?.('[PD:CorrectionObserver] Observer not resolved (no API key or config). Skipping cycle.');
+            // PRI-307: No noisy "no API key" cycling. Only log at debug level.
+            logger?.debug?.(`[PD:CorrectionObserver] Observer not resolved. Skipping cycle.`);
             return;
         }
         logger?.info?.('[PD:CorrectionObserver] Observer resolved. Initiating periodic optimization...');
@@ -135,6 +142,18 @@ export const CorrectionObserverService = {
                 logger.info(`[PD:CorrectionObserver] Already started for workspace: ${workspaceDir}. Skipping duplicate start.`);
             return;
         }
+        // PRI-307: Check observer config before starting
+        const observerConfig = resolveObserverConfig(workspaceDir, 'correction_observer', 'correctionObserver', logger);
+        if (!observerConfig.enabled) {
+            // Disabled → no start, no noisy cycling. Single structured log.
+            logger?.info?.(`[PD:CorrectionObserver] ${observerConfig.reason}. ${observerConfig.nextAction}`);
+            return;
+        }
+        if (observerConfig.readiness === 'needs_setup') {
+            // Enabled but missing setup → structured needs_setup, no noisy cycling
+            logger?.info?.(`[PD:CorrectionObserver] ${observerConfig.reason}. ${observerConfig.nextAction}`);
+            return;
+        }
         startedWorkspaces.add(workspaceDir);
         correctionObserverStopped = false;
         const wctx = WorkspaceContext.fromHookContext({ workspaceDir, ...ctx.config });

package/plugin/dist/utils/workspace-resolver.d.ts

@@ -2,6 +2,11 @@
  * Workspace Directory Resolution Utilities
  *
  * Shared helpers for resolving workspace directories across commands and hooks.
+ *
+ * Hook resolution priority (PRI-259): PD canonical config → OpenClaw fallback.
+ * PD canonical sources: PD_WORKSPACE_DIR env → OPENCLAW_WORKSPACE env →
+ * principles-disciple.json → ~/.openclaw/workspace default.
+ * OpenClaw fallback: ctx.workspaceDir → api.runtime.agent.resolveAgentWorkspaceDir().
  */
 import type { OpenClawPluginApi, PluginCommandContext } from '../openclaw-sdk.js';
 import { type WorkspaceResolutionContext } from '../core/workspace-dir-validation.js';
@@ -29,11 +34,38 @@ export declare function resolveCommandWorkspaceDir(api: OpenClawPluginApi, ctx:
  * @param source - Source label for error messages (e.g. 'evolution-status', 'pain')
  */
 export declare function resolvePluginCommandWorkspaceDir(ctx: PluginCommandContext, source: string): string;
+export type CanonicalWorkspaceSource = 'pd_env' | 'openclaw_env' | 'pd_config' | 'pd_default';
+export interface CanonicalWorkspaceResult {
+    workspaceDir: string;
+    source: CanonicalWorkspaceSource;
+}
+export declare function resolveCanonicalWorkspaceDir(): CanonicalWorkspaceResult | null;
+export type HookWorkspaceSource = CanonicalWorkspaceSource | 'openclaw_context' | 'openclaw_api';
+export interface HookWorkspaceResolutionSuccess {
+    ok: true;
+    workspaceDir: string;
+    source: HookWorkspaceSource;
+    consistencyWarning?: string;
+}
+export interface HookWorkspaceResolutionFailure {
+    ok: false;
+    reason: string;
+    nextAction: string;
+    message: string;
+}
+export type HookWorkspaceResolutionResult = HookWorkspaceResolutionSuccess | HookWorkspaceResolutionFailure;
+export interface HookWorkspaceResolutionOptions {
+    canonicalResolver?: () => CanonicalWorkspaceResult | null;
+    explicitPdResolver?: () => CanonicalWorkspaceResult | null;
+}
+export declare function resolveHookWorkspaceDir(ctx: WorkspaceResolutionContext, api: OpenClawPluginApi, source: string, options?: HookWorkspaceResolutionOptions): HookWorkspaceResolutionResult;
 /**
  * Resolve workspace directory for tool hook execution (safe version).
  * Returns undefined instead of throwing if resolution fails.
+ *
+ * PRI-259: Uses PD canonical config as primary source, OpenClaw as fallback.
  */
-export declare function resolveToolHookWorkspaceDirSafe(ctx: WorkspaceResolutionContext, api: OpenClawPluginApi, source: string): string | undefined;
+export declare function resolveToolHookWorkspaceDirSafe(ctx: WorkspaceResolutionContext, api: OpenClawPluginApi, source: string, options?: HookWorkspaceResolutionOptions): string | undefined;
 export declare class WorkspaceResolutionError extends Error {
     readonly reason: string;
     readonly nextAction: string;

package/plugin/dist/utils/workspace-resolver.js

@@ -2,11 +2,17 @@
  * Workspace Directory Resolution Utilities
  *
  * Shared helpers for resolving workspace directories across commands and hooks.
+ *
+ * Hook resolution priority (PRI-259): PD canonical config → OpenClaw fallback.
+ * PD canonical sources: PD_WORKSPACE_DIR env → OPENCLAW_WORKSPACE env →
+ * principles-disciple.json → ~/.openclaw/workspace default.
+ * OpenClaw fallback: ctx.workspaceDir → api.runtime.agent.resolveAgentWorkspaceDir().
  */
 import { validateWorkspaceDir } from '../core/workspace-dir-validation.js';
-import { resolveWorkspaceDir } from '../core/workspace-dir-service.js';
 import { resolveWorkspaceDirFromApi } from '../core/path-resolver.js';
 import * as path from 'path';
+import * as os from 'os';
+import * as fs from 'fs';
 /**
  * Resolve workspace directory for command execution.
  *
@@ -69,12 +75,185 @@ export function resolvePluginCommandWorkspaceDir(ctx, source) {
     throw new Error(`[PD:Command:${source}] CRITICAL: workspaceDir is not set in ctx.workspaceDir or ctx.config.workspaceDir. ` +
         `Commands cannot execute without a valid workspace. Set OPENCLAW_WORKSPACE_DIR env var or ensure the workspace is properly initialized.`);
 }
+const PD_CONFIG_FILENAME = 'principles-disciple.json';
+function loadWorkspaceFromPdConfigFile() {
+    const candidates = [
+        path.join(os.homedir(), '.openclaw', PD_CONFIG_FILENAME),
+        path.join(os.homedir(), '.principles', PD_CONFIG_FILENAME),
+        path.join(process.cwd(), PD_CONFIG_FILENAME),
+    ];
+    for (const configPath of candidates) {
+        if (!fs.existsSync(configPath))
+            continue;
+        try {
+            const raw = fs.readFileSync(configPath, 'utf8');
+            const parsed = JSON.parse(raw);
+            if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+                if (Object.hasOwn(parsed, 'workspace')) {
+                    const workspaceValue = parsed['workspace'];
+                    if (typeof workspaceValue === 'string' && workspaceValue.trim()) {
+                        return workspaceValue.trim();
+                    }
+                }
+            }
+        }
+        catch {
+            continue;
+        }
+    }
+    return null;
+}
+export function resolveCanonicalWorkspaceDir() {
+    const pdEnv = process.env.PD_WORKSPACE_DIR;
+    if (pdEnv && pdEnv.trim()) {
+        const dir = path.resolve(pdEnv.trim());
+        if (!validateWorkspaceDir(dir)) {
+            return { workspaceDir: dir, source: 'pd_env' };
+        }
+    }
+    const ocEnv = process.env.OPENCLAW_WORKSPACE;
+    if (ocEnv && ocEnv.trim()) {
+        const dir = path.resolve(ocEnv.trim());
+        if (!validateWorkspaceDir(dir)) {
+            return { workspaceDir: dir, source: 'openclaw_env' };
+        }
+    }
+    const configWorkspace = loadWorkspaceFromPdConfigFile();
+    if (configWorkspace) {
+        const dir = path.resolve(configWorkspace);
+        if (!validateWorkspaceDir(dir)) {
+            return { workspaceDir: dir, source: 'pd_config' };
+        }
+    }
+    const defaultDir = path.join(os.homedir(), '.openclaw', 'workspace');
+    if (!validateWorkspaceDir(defaultDir)) {
+        return { workspaceDir: defaultDir, source: 'pd_default' };
+    }
+    return null;
+}
+/**
+ * Resolve only PD explicit sources (env vars + config file), excluding pd_default.
+ * Used by hook resolution to ensure ctx.workspaceDir takes priority over the
+ * hardcoded default fallback.
+ */
+function resolveExplicitPdSources() {
+    const pdEnv = process.env.PD_WORKSPACE_DIR;
+    if (pdEnv && pdEnv.trim()) {
+        const dir = path.resolve(pdEnv.trim());
+        if (!validateWorkspaceDir(dir)) {
+            return { workspaceDir: dir, source: 'pd_env' };
+        }
+    }
+    const ocEnv = process.env.OPENCLAW_WORKSPACE;
+    if (ocEnv && ocEnv.trim()) {
+        const dir = path.resolve(ocEnv.trim());
+        if (!validateWorkspaceDir(dir)) {
+            return { workspaceDir: dir, source: 'openclaw_env' };
+        }
+    }
+    const configWorkspace = loadWorkspaceFromPdConfigFile();
+    if (configWorkspace) {
+        const dir = path.resolve(configWorkspace);
+        if (!validateWorkspaceDir(dir)) {
+            return { workspaceDir: dir, source: 'pd_config' };
+        }
+    }
+    return null;
+}
+function tryResolveFromOpenClawApi(api, agentId) {
+    try {
+        const resolved = api.runtime?.agent?.resolveAgentWorkspaceDir?.(api.config, agentId ?? 'main');
+        if (resolved && !validateWorkspaceDir(resolved)) {
+            return resolved;
+        }
+    }
+    catch {
+        // Fall through
+    }
+    return undefined;
+}
+export function resolveHookWorkspaceDir(ctx, api, source, options) {
+    // Priority 1: PD explicit sources (env vars + config file) — these are
+    // owner-declared and intentionally override the live session context.
+    const resolveExplicit = options?.explicitPdResolver ?? resolveExplicitPdSources;
+    const explicit = resolveExplicit();
+    if (explicit) {
+        let consistencyWarning;
+        if (ctx.workspaceDir) {
+            const normalizedCtx = path.resolve(ctx.workspaceDir);
+            const normalizedExplicit = path.resolve(explicit.workspaceDir);
+            if (normalizedCtx !== normalizedExplicit) {
+                consistencyWarning =
+                    `PD explicit workspace (${explicit.source}: ${explicit.workspaceDir}) ` +
+                        `differs from OpenClaw context (${ctx.workspaceDir}). Using PD explicit.`;
+            }
+        }
+        return {
+            ok: true,
+            workspaceDir: explicit.workspaceDir,
+            source: explicit.source,
+            consistencyWarning,
+        };
+    }
+    // Priority 2: OpenClaw live context — the real session workspace.
+    // This MUST take priority over pd_default (the hardcoded fallback).
+    if (ctx.workspaceDir) {
+        const issue = validateWorkspaceDir(ctx.workspaceDir);
+        if (!issue) {
+            return {
+                ok: true,
+                workspaceDir: ctx.workspaceDir,
+                source: 'openclaw_context',
+            };
+        }
+    }
+    // Priority 3: OpenClaw API resolution
+    const apiResolved = tryResolveFromOpenClawApi(api, ctx.agentId);
+    if (apiResolved) {
+        return {
+            ok: true,
+            workspaceDir: apiResolved,
+            source: 'openclaw_api',
+        };
+    }
+    // Priority 4: pd_default (hardcoded fallback) — only when nothing else works
+    const resolveCanonical = options?.canonicalResolver ?? resolveCanonicalWorkspaceDir;
+    const canonical = resolveCanonical();
+    if (canonical && canonical.source === 'pd_default') {
+        return {
+            ok: true,
+            workspaceDir: canonical.workspaceDir,
+            source: 'pd_default',
+            consistencyWarning: 'Using hardcoded default workspace (~/.openclaw/workspace). ' +
+                'Set PD_WORKSPACE_DIR or create ~/.openclaw/principles-disciple.json for stable resolution.',
+        };
+    }
+    return {
+        ok: false,
+        reason: 'workspace_dir_unresolvable',
+        nextAction: 'Set PD_WORKSPACE_DIR environment variable, create ~/.openclaw/principles-disciple.json ' +
+            'with a "workspace" field, or ensure OpenClaw provides workspaceDir in hook context.',
+        message: `[PD:${source}] Cannot resolve workspace directory from any source. ` +
+            `PD explicit config (PD_WORKSPACE_DIR, principles-disciple.json) ` +
+            `and OpenClaw fallback (ctx.workspaceDir, api.resolveAgentWorkspaceDir, ~/.openclaw/workspace) all failed.`,
+    };
+}
 /**
  * Resolve workspace directory for tool hook execution (safe version).
  * Returns undefined instead of throwing if resolution fails.
+ *
+ * PRI-259: Uses PD canonical config as primary source, OpenClaw as fallback.
  */
-export function resolveToolHookWorkspaceDirSafe(ctx, api, source) {
-    return resolveWorkspaceDir(api, ctx, { source });
+export function resolveToolHookWorkspaceDirSafe(ctx, api, source, options) {
+    const result = resolveHookWorkspaceDir(ctx, api, source, options);
+    if (!result.ok) {
+        api.logger.warn(result.message);
+        return undefined;
+    }
+    if (result.consistencyWarning) {
+        api.logger.warn(`[PD:${source}] ${result.consistencyWarning}`);
+    }
+    return result.workspaceDir;
 }
 export class WorkspaceResolutionError extends Error {
     reason;