principles-disciple 1.83.1 → 1.84.0

package/openclaw.plugin.json

@@ -2,7 +2,7 @@
   "id": "principles-disciple",
   "name": "Principles Disciple",
   "description": "Evolutionary programming agent framework with strategic guardrails and reflection loops.",
-  "version": "1.83.1",
+  "version": "1.84.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "principles-disciple",
-  "version": "1.83.1",
+  "version": "1.84.0",
   "description": "Native OpenClaw plugin for Principles Disciple",
   "type": "module",
   "main": "./dist/bundle.js",

package/src/index.ts

@@ -58,7 +58,7 @@ 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 type { WorkerProfile } from './core/model-deployment-registry.js';
 import { validateWorkspaceDir } from './core/workspace-dir-validation.js';
@@ -68,10 +68,6 @@ import { checkSurfaceGuard, guardHook, guardService } from './core/surface-guard
 // Track started workspaces — one-time init + evolution worker per workspace
 const startedWorkspaces = new Set<string>();
 
-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<string, string>();
@@ -235,17 +231,20 @@ const plugin = {
     api.on(
       'before_prompt_build',
       guardHook('hook:before_prompt_build', api.logger, async (event: PluginHookBeforePromptBuildEvent, ctx: PluginHookAgentContext): Promise<PluginHookBeforePromptBuildResult | void> => {
-        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);
@@ -313,17 +312,20 @@ const plugin = {
     api.on(
       'before_tool_call',
       guardHook('hook:before_tool_call', api.logger, (event: PluginHookBeforeToolCallEvent, ctx: PluginHookToolContext): PluginHookBeforeToolCallResult | void => {
-        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;
@@ -348,17 +350,20 @@ const plugin = {
     api.on(
       'after_tool_call',
       guardHook('hook:after_tool_call', api.logger, (event: PluginHookAfterToolCallEvent, ctx: PluginHookToolContext): void => {
-        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
@@ -381,17 +386,21 @@ const plugin = {
     api.on(
       'llm_output',
       guardHook('hook:llm_output', api.logger, (event: PluginHookLlmOutputEvent, ctx: PluginHookAgentContext): void => {
-        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 });
 
@@ -525,42 +534,51 @@ const plugin = {
 
     // ── Hook: Lifecycle ──
     api.on('before_reset', guardHook('hook:before_reset', api.logger, (event: PluginHookBeforeResetEvent, ctx: PluginHookAgentContext) => {
-      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: PluginHookBeforeCompactionEvent, ctx: PluginHookAgentContext) => {
-      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: PluginHookAfterCompactionEvent, ctx: PluginHookAgentContext) => {
-      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 Registration (surface-guarded) ──

package/src/utils/workspace-resolver.ts

@@ -2,13 +2,19 @@
  * 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 { validateWorkspaceDir, type WorkspaceResolutionContext } 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.
@@ -83,16 +89,258 @@ export function resolvePluginCommandWorkspaceDir(
   );
 }
 
+// ── PD Canonical Workspace Config Resolution (PRI-259) ──────────────────
+
+export type CanonicalWorkspaceSource = 'pd_env' | 'openclaw_env' | 'pd_config' | 'pd_default';
+
+export interface CanonicalWorkspaceResult {
+  workspaceDir: string;
+  source: CanonicalWorkspaceSource;
+}
+
+const PD_CONFIG_FILENAME = 'principles-disciple.json';
+
+function loadWorkspaceFromPdConfigFile(): string | null {
+  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: unknown = JSON.parse(raw);
+      if (parsed !== null && typeof parsed === 'object' && !Array.isArray(parsed)) {
+        if (Object.hasOwn(parsed, 'workspace')) {
+          const workspaceValue = (parsed as Record<string, unknown>)['workspace'];
+          if (typeof workspaceValue === 'string' && workspaceValue.trim()) {
+            return workspaceValue.trim();
+          }
+        }
+      }
+    } catch {
+      continue;
+    }
+  }
+  return null;
+}
+
+export function resolveCanonicalWorkspaceDir(): CanonicalWorkspaceResult | null {
+  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(): CanonicalWorkspaceResult | null {
+  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;
+}
+
+// ── Hook Workspace Resolution (PRI-259) ────────────────────────────────
+
+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;
+
+function tryResolveFromOpenClawApi(
+  api: OpenClawPluginApi,
+  agentId: string | undefined,
+): string | undefined {
+  try {
+    const resolved = api.runtime?.agent?.resolveAgentWorkspaceDir?.(api.config, agentId ?? 'main');
+    if (resolved && !validateWorkspaceDir(resolved)) {
+      return resolved;
+    }
+  } catch {
+    // Fall through
+  }
+  return undefined;
+}
+
+export interface HookWorkspaceResolutionOptions {
+  canonicalResolver?: () => CanonicalWorkspaceResult | null;
+  explicitPdResolver?: () => CanonicalWorkspaceResult | null;
+}
+
+export function resolveHookWorkspaceDir(
+  ctx: WorkspaceResolutionContext,
+  api: OpenClawPluginApi,
+  source: string,
+  options?: HookWorkspaceResolutionOptions,
+): HookWorkspaceResolutionResult {
+  // 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: string | undefined;
+
+    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: WorkspaceResolutionContext,
   api: OpenClawPluginApi,
   source: string,
+  options?: HookWorkspaceResolutionOptions,
 ): string | undefined {
-  return resolveWorkspaceDir(api, ctx, { source });
+  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 {

package/tests/hook-workspace-nextaction-contract.test.ts

@@ -7,36 +7,44 @@ const INDEX_TS = fs.readFileSync(
   'utf-8',
 );
 
+const WORKSPACE_RESOLVER_TS = fs.readFileSync(
+  path.resolve(__dirname, '../src/utils/workspace-resolver.ts'),
+  'utf-8',
+);
+
 describe('Hook workspace resolution NextAction contract', () => {
-  const FORBIDDEN_NEXT_ACTION_PATTERNS = [
-    /PD_WORKSPACE_DIR/,
-    /principles-disciple\.json/,
-  ];
-
-  it('does not claim PD_WORKSPACE_DIR env var as recovery in NextAction', () => {
-    const matches = INDEX_TS.match(/NextAction:[^`]*PD_WORKSPACE_DIR/g);
-    expect(matches).toBeNull();
+  it('no stale HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION constant remains', () => {
+    const constantMatch = INDEX_TS.match(/HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION/);
+    expect(constantMatch).toBeNull();
   });
 
-  it('does not claim principles-disciple.json as recovery in NextAction', () => {
-    const matches = INDEX_TS.match(/NextAction:[^`]*principles-disciple\.json/g);
-    expect(matches).toBeNull();
+  it('resolveHookWorkspaceDir failure result includes PD canonical config in nextAction', () => {
+    const nextActionMatch = WORKSPACE_RESOLVER_TS.match(
+      /nextAction:\s*'([^']+)'/s,
+    );
+    expect(nextActionMatch).not.toBeNull();
+    const nextAction = nextActionMatch![1];
+    expect(nextAction).toContain('PD_WORKSPACE_DIR');
+    expect(nextAction).toContain('principles-disciple.json');
   });
 
-  it('all hook failure NextActions reference canonical workspace migration', () => {
-    const nextActionLines = INDEX_TS.match(/NextAction: \${HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION}/g);
-    expect(nextActionLines).not.toBeNull();
-    expect(nextActionLines!.length).toBeGreaterThanOrEqual(7);
+  it('all hook failure paths use resolveHookWorkspaceDir with structured nextAction', () => {
+    const hookUsages = INDEX_TS.match(/resolveHookWorkspaceDir\(/g);
+    expect(hookUsages).not.toBeNull();
+    expect(hookUsages!.length).toBeGreaterThanOrEqual(6);
+
+    const wsResultOkChecks = INDEX_TS.match(/!wsResult\.ok/g);
+    expect(wsResultOkChecks).not.toBeNull();
+    expect(wsResultOkChecks!.length).toBeGreaterThanOrEqual(6);
+
+    const nextActionRefs = INDEX_TS.match(/wsResult\.nextAction/g);
+    expect(nextActionRefs).not.toBeNull();
+    expect(nextActionRefs!.length).toBeGreaterThanOrEqual(6);
   });
 
-  it('HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION constant exists and does not contain forbidden patterns', () => {
-    const constantMatch = INDEX_TS.match(
-      /const HOOK_WORKSPACE_RESOLUTION_NEXT_ACTION\s*=\s*'([^']+)'/,
-    );
-    expect(constantMatch).not.toBeNull();
-    const constantValue = constantMatch![1];
-    for (const pattern of FORBIDDEN_NEXT_ACTION_PATTERNS) {
-      expect(pattern.test(constantValue)).toBe(false);
-    }
+  it('resolveHookWorkspaceDir failure result has reason and nextAction fields', () => {
+    expect(WORKSPACE_RESOLVER_TS).toContain("reason: 'workspace_dir_unresolvable'");
+    expect(WORKSPACE_RESOLVER_TS).toContain('nextAction:');
+    expect(WORKSPACE_RESOLVER_TS).toContain('PD_WORKSPACE_DIR');
   });
 });

package/tests/utils/hook-workspace-resolver.test.ts

@@ -0,0 +1,347 @@
+import { beforeEach, describe, expect, it, vi, afterEach } from 'vitest';
+import * as os from 'os';
+import * as path from 'path';
+import * as fs from 'fs';
+
+import {
+  resolveCanonicalWorkspaceDir,
+  resolveHookWorkspaceDir,
+  resolveToolHookWorkspaceDirSafe,
+} from '../../src/utils/workspace-resolver.js';
+import type { CanonicalWorkspaceResult, HookWorkspaceResolutionResult } from '../../src/utils/workspace-resolver.js';
+
+const homeDir = os.homedir();
+const validWorkspace = path.join(os.tmpdir(), 'pd-test-workspace-hook-resolver');
+
+function ensureDir(dir: string): void {
+  if (!fs.existsSync(dir)) {
+    fs.mkdirSync(dir, { recursive: true });
+  }
+}
+
+const noCanonical: () => null = () => null;
+
+describe('resolveCanonicalWorkspaceDir', () => {
+  const originalEnv = { ...process.env };
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.PD_WORKSPACE_DIR;
+    delete process.env.OPENCLAW_WORKSPACE;
+    ensureDir(validWorkspace);
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('resolves from PD_WORKSPACE_DIR env var with highest priority', () => {
+    process.env.PD_WORKSPACE_DIR = validWorkspace;
+    process.env.OPENCLAW_WORKSPACE = '/some/other/path';
+    const result = resolveCanonicalWorkspaceDir();
+    expect(result).not.toBeNull();
+    expect(result!.source).toBe('pd_env');
+    expect(result!.workspaceDir).toBe(path.resolve(validWorkspace));
+  });
+
+  it('resolves from OPENCLAW_WORKSPACE env var when PD_WORKSPACE_DIR is not set', () => {
+    process.env.OPENCLAW_WORKSPACE = validWorkspace;
+    const result = resolveCanonicalWorkspaceDir();
+    expect(result).not.toBeNull();
+    expect(result!.source).toBe('openclaw_env');
+    expect(result!.workspaceDir).toBe(path.resolve(validWorkspace));
+  });
+
+  it('prefers PD_WORKSPACE_DIR over OPENCLAW_WORKSPACE', () => {
+    const altWorkspace = path.join(os.tmpdir(), 'pd-test-workspace-alt');
+    ensureDir(altWorkspace);
+    process.env.PD_WORKSPACE_DIR = validWorkspace;
+    process.env.OPENCLAW_WORKSPACE = altWorkspace;
+    const result = resolveCanonicalWorkspaceDir();
+    expect(result).not.toBeNull();
+    expect(result!.source).toBe('pd_env');
+    expect(result!.workspaceDir).toBe(path.resolve(validWorkspace));
+  });
+
+  it('rejects home directory from PD_WORKSPACE_DIR', () => {
+    process.env.PD_WORKSPACE_DIR = homeDir;
+    const result = resolveCanonicalWorkspaceDir();
+    if (result?.source === 'pd_env') {
+      expect.fail('Should not resolve home directory from PD_WORKSPACE_DIR');
+    }
+  });
+
+  it('rejects empty string from PD_WORKSPACE_DIR', () => {
+    process.env.PD_WORKSPACE_DIR = '';
+    const result = resolveCanonicalWorkspaceDir();
+    if (result?.source === 'pd_env') {
+      expect.fail('Should not resolve empty PD_WORKSPACE_DIR');
+    }
+  });
+
+  it('always returns a result when PD_WORKSPACE_DIR points to a valid dir', () => {
+    process.env.PD_WORKSPACE_DIR = validWorkspace;
+    const result = resolveCanonicalWorkspaceDir();
+    expect(result).not.toBeNull();
+    expect(result!.workspaceDir).toBe(path.resolve(validWorkspace));
+  });
+});
+
+describe('resolveHookWorkspaceDir — PD canonical primary', () => {
+  const originalEnv = { ...process.env };
+  const logger = {
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+  };
+
+  const api = {
+    runtime: {
+      agent: {
+        resolveAgentWorkspaceDir: vi.fn(),
+      },
+    },
+    config: {},
+    logger,
+  };
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.PD_WORKSPACE_DIR;
+    delete process.env.OPENCLAW_WORKSPACE;
+    vi.clearAllMocks();
+    ensureDir(validWorkspace);
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('uses PD_WORKSPACE_DIR as primary source regardless of OpenClaw context', () => {
+    process.env.PD_WORKSPACE_DIR = validWorkspace;
+    const result = resolveHookWorkspaceDir(
+      { workspaceDir: '/some/openclaw/path', agentId: 'main' },
+      api as any,
+      'test',
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.source).toBe('pd_env');
+      expect(result.workspaceDir).toBe(path.resolve(validWorkspace));
+    }
+  });
+
+  it('emits consistency warning when PD canonical differs from OpenClaw context', () => {
+    const altWorkspace = path.join(os.tmpdir(), 'pd-test-workspace-alt-2');
+    ensureDir(altWorkspace);
+    process.env.PD_WORKSPACE_DIR = validWorkspace;
+    const result = resolveHookWorkspaceDir(
+      { workspaceDir: altWorkspace },
+      api as any,
+      'test',
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.source).toBe('pd_env');
+      expect(result.workspaceDir).toBe(path.resolve(validWorkspace));
+      expect(result.consistencyWarning).toContain('differs from OpenClaw context');
+    }
+  });
+
+  it('does not emit consistency warning when PD canonical matches OpenClaw context', () => {
+    process.env.PD_WORKSPACE_DIR = validWorkspace;
+    const result = resolveHookWorkspaceDir(
+      { workspaceDir: validWorkspace },
+      api as any,
+      'test',
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.consistencyWarning).toBeUndefined();
+    }
+  });
+
+  it('falls back to OpenClaw context when no PD explicit config exists', () => {
+    const result = resolveHookWorkspaceDir(
+      { workspaceDir: validWorkspace },
+      api as any,
+      'test',
+      { canonicalResolver: noCanonical, explicitPdResolver: noCanonical },
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.source).toBe('openclaw_context');
+      expect(result.workspaceDir).toBe(validWorkspace);
+    }
+  });
+
+  it('falls back to OpenClaw API when context is also missing', () => {
+    api.runtime.agent.resolveAgentWorkspaceDir.mockReturnValue(validWorkspace);
+    const result = resolveHookWorkspaceDir(
+      {},
+      api as any,
+      'test',
+      { canonicalResolver: noCanonical, explicitPdResolver: noCanonical },
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.source).toBe('openclaw_api');
+      expect(result.workspaceDir).toBe(validWorkspace);
+    }
+  });
+
+  it('returns structured failure with reason and nextAction when all sources fail', () => {
+    api.runtime.agent.resolveAgentWorkspaceDir.mockReturnValue(homeDir);
+    const result = resolveHookWorkspaceDir(
+      {},
+      api as any,
+      'test_hook',
+      { canonicalResolver: noCanonical, explicitPdResolver: noCanonical },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe('workspace_dir_unresolvable');
+      expect(result.nextAction).toContain('PD_WORKSPACE_DIR');
+      expect(result.nextAction).toContain('principles-disciple.json');
+      expect(result.message).toContain('test_hook');
+    }
+  });
+
+  it('rejects home directory from OpenClaw context and falls back to API', () => {
+    api.runtime.agent.resolveAgentWorkspaceDir.mockReturnValue(validWorkspace);
+    const result = resolveHookWorkspaceDir(
+      { workspaceDir: homeDir, agentId: 'main' },
+      api as any,
+      'test',
+      { canonicalResolver: noCanonical, explicitPdResolver: noCanonical },
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.source).toBe('openclaw_api');
+      expect(result.workspaceDir).toBe(validWorkspace);
+    }
+  });
+
+  it('ctx.workspaceDir takes priority over pd_default when no explicit PD source exists', () => {
+    // canonicalResolver returns pd_default, but ctx.workspaceDir is a real workspace
+    const pdDefaultResolver = (): CanonicalWorkspaceResult => ({
+      workspaceDir: path.join(homeDir, '.openclaw', 'workspace'),
+      source: 'pd_default',
+    });
+    const result = resolveHookWorkspaceDir(
+      { workspaceDir: validWorkspace },
+      api as any,
+      'test',
+      { canonicalResolver: pdDefaultResolver, explicitPdResolver: noCanonical },
+    );
+    expect(result.ok).toBe(true);
+    if (result.ok) {
+      expect(result.source).toBe('openclaw_context');
+      expect(result.workspaceDir).toBe(validWorkspace);
+    }
+  });
+
+  it('returns failure when API throws and no other source works', () => {
+    api.runtime.agent.resolveAgentWorkspaceDir.mockImplementation(() => {
+      throw new Error('API unavailable');
+    });
+    const result = resolveHookWorkspaceDir(
+      {},
+      api as any,
+      'test_hook',
+      { canonicalResolver: noCanonical, explicitPdResolver: noCanonical },
+    );
+    expect(result.ok).toBe(false);
+    if (!result.ok) {
+      expect(result.reason).toBe('workspace_dir_unresolvable');
+      expect(result.nextAction).toContain('PD_WORKSPACE_DIR');
+    }
+  });
+});
+
+describe('resolveToolHookWorkspaceDirSafe (backward compat)', () => {
+  const originalEnv = { ...process.env };
+  const logger = {
+    error: vi.fn(),
+    warn: vi.fn(),
+    info: vi.fn(),
+    debug: vi.fn(),
+  };
+
+  const api = {
+    runtime: {
+      agent: {
+        resolveAgentWorkspaceDir: vi.fn(),
+      },
+    },
+    config: {},
+    logger,
+  };
+
+  beforeEach(() => {
+    process.env = { ...originalEnv };
+    delete process.env.PD_WORKSPACE_DIR;
+    delete process.env.OPENCLAW_WORKSPACE;
+    vi.clearAllMocks();
+    ensureDir(validWorkspace);
+  });
+
+  afterEach(() => {
+    process.env = { ...originalEnv };
+  });
+
+  it('returns string when PD_WORKSPACE_DIR resolves', () => {
+    process.env.PD_WORKSPACE_DIR = validWorkspace;
+    const result = resolveToolHookWorkspaceDirSafe({}, api as any, 'test');
+    expect(result).toBe(path.resolve(validWorkspace));
+  });
+
+  it('logs consistency warning when PD canonical differs from context', () => {
+    const altWorkspace = path.join(os.tmpdir(), 'pd-test-workspace-alt-3');
+    ensureDir(altWorkspace);
+    process.env.PD_WORKSPACE_DIR = validWorkspace;
+    const result = resolveToolHookWorkspaceDirSafe(
+      { workspaceDir: altWorkspace },
+      api as any,
+      'test',
+    );
+    expect(result).toBe(path.resolve(validWorkspace));
+    expect(logger.warn).toHaveBeenCalledWith(
+      expect.stringContaining('differs from OpenClaw context'),
+    );
+  });
+
+  it('returns pd_default when only default fallback is available', () => {
+    // When no explicit PD source, no ctx.workspaceDir, and no API resolution,
+    // resolveToolHookWorkspaceDirSafe falls back to pd_default
+    api.runtime.agent.resolveAgentWorkspaceDir.mockReturnValue(homeDir);
+    const result = resolveToolHookWorkspaceDirSafe(
+      {},
+      api as any,
+      'test',
+    );
+    // pd_default (~/.openclaw/workspace) is used as last resort
+    expect(result).toBeDefined();
+    expect(result).toContain('.openclaw');
+  });
+
+  it('returns undefined and logs when all sources including pd_default fail', () => {
+    api.runtime.agent.resolveAgentWorkspaceDir.mockImplementation(() => {
+      throw new Error('no workspace');
+    });
+    const result = resolveToolHookWorkspaceDirSafe(
+      {},
+      api as any,
+      'test_hook',
+      { canonicalResolver: noCanonical, explicitPdResolver: noCanonical },
+    );
+    expect(result).toBeUndefined();
+    expect(logger.warn).toHaveBeenCalled();
+    const warnCalls = logger.warn.mock.calls.map((c: unknown[]) => String(c[0]));
+    const fullWarn = warnCalls.join('\n');
+    expect(fullWarn).toContain('Cannot resolve workspace directory');
+    expect(fullWarn).toContain('PD_WORKSPACE_DIR');
+    expect(fullWarn).toContain('principles-disciple.json');
+  });
+});