principles-disciple 1.83.1 → 1.85.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.85.0",
   "activation": {
     "onCapabilities": [
       "hook"

package/package.json

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

package/src/core/event-log.ts

@@ -32,6 +32,7 @@ import type {
 import { createEmptyDailyStats } from '../types/event-types.js';
 import { atomicWriteFileSync } from '../utils/io.js';
 import type { PluginLogger } from '../openclaw-sdk.js';
+import { redactTelemetryString } from '@principles/core/runtime-v2';
 
 const EVENT_LOG_RETENTION_DAYS = 7;
 
@@ -209,6 +210,88 @@ export class EventLog {
     this.record('runtime_v2_prompt_activations_injected', 'injected', data.sessionId, data);
   }
 
+  /**
+   * Redact telemetry-sensitive string values in event data before persistence.
+   * Applies redactTelemetryString to known high-risk fields (filePath, command,
+   * reason, args, new_string, old_string, text, paramsSummary values) and to all
+   * string values in tool_call/rulehost_* data as a safety net.
+   *
+   * ERR-002: never throws; returns data unchanged on error.
+   * ERR-045/046: covers composite command strings, Authorization headers, env vars.
+   */
+  private redactEventData(
+    type: EventType,
+    data: Record<string, unknown>
+  ): Record<string, unknown> {
+    try {
+      // Known high-risk event types — telemetry that carries tool commands / paths
+      const telemetryTypes: Set<EventType> = new Set([
+        'tool_call',
+        'rulehost_evaluated',
+        'rulehost_blocked',
+        'rulehost_requireApproval',
+        'rulehost_auto_correct_proposed',
+        'rulehost_auto_correct_applied',
+        'rule_enforced',
+        'hook_execution',
+        'gate_block',
+        'gate_bypass',
+      ]);
+
+      if (!telemetryTypes.has(type)) return data;
+
+      const redacted: Record<string, unknown> = {};
+      for (const [key, value] of Object.entries(data)) {
+        if (typeof value === 'string') {
+          redacted[key] = redactTelemetryString(value);
+        } else if (Array.isArray(value)) {
+          // Recurse into arrays (e.g. correctedFields with original/applied)
+          redacted[key] = value.map((item: unknown) => {
+            if (typeof item === 'string') {
+              return redactTelemetryString(item);
+            }
+            if (typeof item === 'object' && item !== null) {
+              const nested: Record<string, unknown> = {};
+              for (const [nk, nv] of Object.entries(item as Record<string, unknown>)) {
+                nested[nk] = typeof nv === 'string' ? redactTelemetryString(nv) : nv;
+              }
+              return nested;
+            }
+            return item;
+          });
+        } else if (typeof value === 'object' && value !== null) {
+          // Recurse one level for nested objects (e.g. paramsSummary)
+          const nested: Record<string, unknown> = {};
+          for (const [nk, nv] of Object.entries(value as Record<string, unknown>)) {
+            if (typeof nv === 'string') {
+              nested[nk] = redactTelemetryString(nv);
+            } else {
+              nested[nk] = nv;
+            }
+          }
+          redacted[key] = nested;
+        } else {
+          redacted[key] = value;
+        }
+      }
+      return redacted;
+    } catch (e) {
+      // ERR-002: fail safe — never write raw payload on redaction failure.
+      // Return a masked payload with context so downstream knows what happened.
+      const errStr = e instanceof Error ? e.message.slice(0, 200) : String(e).slice(0, 200);
+      const masked: Record<string, unknown> = {
+        redactionFailure: true,
+        redactionStatus: 'failed',
+        'redaction.status': 'failed',
+        redactionReason: errStr || 'unknown error',
+        redactionDataDropped: true,
+        originalType: type,
+        originalSessionId: data.sessionId ?? null,
+      };
+      return masked;
+    }
+  }
+
   private record(
     type: EventType, 
     category: EventCategory, 
@@ -218,13 +301,15 @@ export class EventLog {
     const now = new Date();
     const date = this.formatDate(now);
     
+    const redactedData = this.redactEventData(type, data as Record<string, unknown>);
+    
     const entry: EventLogEntry = {
       ts: now.toISOString(),
       date,
       type,
       category,
       sessionId,
-      data: data as Record<string, unknown>,
+      data: redactedData,
     };
     
     this.eventBuffer.push(entry);

package/src/hooks/gate.ts

@@ -339,6 +339,9 @@ export function handleBeforeToolCall(
 
 function _extractParamsSummary(params: Record<string, unknown>): Record<string, unknown> {
   const summary: Record<string, unknown> = {};
+  // NOTE: Do NOT redact here — this feeds into RuleHost.evaluate() which
+  // may match against paramsSummary.command. Redaction happens at
+  // EventLog.record() before persistence.
   if (params.file_path) summary.file_path = params.file_path;
   if (params.path) summary.path = params.path;
   if (params.command) summary.command = params.command;

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/core/event-log.test.ts

@@ -315,4 +315,170 @@ describe('EventLog', () => {
       expect(stats.evolution.rulehostAutoCorrectApplied).toBe(0);
     });
   });
+
+  describe('telemetry redaction', () => {
+    it('redacts lin_api_ token from rulehost_evaluated filePath', () => {
+      const sensitivePath = 'curl -s -H "Authorization: lin_api_TEST_REDACT_ME_1234567890ABCDEF" https://api.linear.app';
+      eventLog.recordRuleHostEvaluated({
+        toolName: 'bash',
+        filePath: sensitivePath,
+        matched: true,
+        decision: 'allow',
+        ruleId: 'r1',
+      });
+      eventLog.flush();
+
+      const eventsFile = path.join(tempDir, 'logs', 'events_' + new Date().toISOString().slice(0, 10) + '.jsonl');
+      const content = fs.readFileSync(eventsFile, 'utf-8');
+      expect(content).not.toContain('lin_api_TEST_REDACT_ME');
+      expect(content).toContain('[REDACTED]');
+    });
+
+    it('redacts Authorization header from tool_call data', () => {
+      eventLog.recordToolCall('s1', {
+        toolName: 'bash',
+        command: 'curl -H "Authorization: Bearer sk-TEST_REDACT_ME_1234567890" https://api.example.com',
+        error: undefined,
+        gfi: 0,
+      });
+      eventLog.flush();
+
+      const eventsFile = path.join(tempDir, 'logs', 'events_' + new Date().toISOString().slice(0, 10) + '.jsonl');
+      const content = fs.readFileSync(eventsFile, 'utf-8');
+      expect(content).not.toContain('sk-TEST_REDACT_ME_1234567890');
+      expect(content).not.toContain('Bearer sk-TEST_REDACT_ME');
+      expect(content).toContain('[REDACTED]');
+    });
+
+    it('redacts ghp_ token from tool_call data', () => {
+      eventLog.recordToolCall('s1', {
+        toolName: 'bash',
+        command: 'ghp_TEST_REDACT_ME_1234567890ABCDEFGHIJKLMN',
+        error: undefined,
+        gfi: 0,
+      });
+      eventLog.flush();
+
+      const eventsFile = path.join(tempDir, 'logs', 'events_' + new Date().toISOString().slice(0, 10) + '.jsonl');
+      const content = fs.readFileSync(eventsFile, 'utf-8');
+      expect(content).not.toContain('ghp_TEST_REDACT_ME');
+      expect(content).toContain('[REDACTED]');
+    });
+
+    it('redacts Bearer token in tool_call data', () => {
+      eventLog.recordToolCall('s1', {
+        toolName: 'bash',
+        command: 'curl -H "Authorization: Bearer TEST_REDACT_ME_TOKEN_1234567890"',
+        error: undefined,
+        gfi: 0,
+      });
+      eventLog.flush();
+
+      const eventsFile = path.join(tempDir, 'logs', 'events_' + new Date().toISOString().slice(0, 10) + '.jsonl');
+      const content = fs.readFileSync(eventsFile, 'utf-8');
+      expect(content).not.toContain('TEST_REDACT_ME_TOKEN');
+      expect(content).toContain('[REDACTED]');
+    });
+
+    it('redacts env assignment in tool_call data', () => {
+      eventLog.recordToolCall('s1', {
+        toolName: 'bash',
+        command: 'LINEAR_API_KEY=lin_api_TEST_REDACT_ME_1234567890ABCDEF curl -s https://api.linear.app',
+        error: undefined,
+        gfi: 0,
+      });
+      eventLog.flush();
+
+      const eventsFile = path.join(tempDir, 'logs', 'events_' + new Date().toISOString().slice(0, 10) + '.jsonl');
+      const content = fs.readFileSync(eventsFile, 'utf-8');
+      expect(content).not.toContain('lin_api_TEST_REDACT_ME');
+      expect(content).toContain('[REDACTED]');
+    });
+
+    it('preserves normal file path in rulehost_evaluated', () => {
+      const normalPath = 'src/app.ts';
+      eventLog.recordRuleHostEvaluated({
+        toolName: 'write',
+        filePath: normalPath,
+        matched: true,
+        decision: 'allow',
+        ruleId: 'r1',
+      });
+      eventLog.flush();
+
+      const eventsFile = path.join(tempDir, 'logs', 'events_' + new Date().toISOString().slice(0, 10) + '.jsonl');
+      const content = fs.readFileSync(eventsFile, 'utf-8');
+      expect(content).toContain(normalPath);
+    });
+
+    it('non-telemetry types are not affected', () => {
+      eventLog.recordPainSignal('s1', {
+        source: 'tool_failure',
+        score: 75,
+        reason: 'normal pain signal',
+      });
+      eventLog.flush();
+
+      const eventsFile = path.join(tempDir, 'logs', 'events_' + new Date().toISOString().slice(0, 10) + '.jsonl');
+      const content = fs.readFileSync(eventsFile, 'utf-8');
+      expect(content).toContain('normal pain signal');
+    });
+
+    it('redaction failure returns masked payload, not raw secrets', () => {
+      // Contract check: the catch block in redactEventData must NOT return raw data.
+      // This is a static regression test for the ERR-002 fail-safe fix.
+      const eventLogSource = fs.readFileSync(
+        path.resolve(__dirname, '../../src/core/event-log.ts'),
+        'utf-8'
+      );
+      // Find the catch block lines (after '} catch')
+      const afterCatch = eventLogSource.match(/\}[\s\n]*catch[\s\n]*\([^)]*\)[\s\n]*\{([\s\S]*?)\}[\s\n]*(?:private|public|\n)/);
+      // If found, verify it doesn't contain 'return data'
+      if (afterCatch) {
+        expect(afterCatch[1]).not.toMatch(/return\s+data/);
+      }
+      // The catch block must produce a masked result with redactionStatus
+      expect(eventLogSource).toContain('redactionStatus');
+      expect(eventLogSource).toContain('redactionDataDropped');
+      expect(eventLogSource).toContain('redactionReason');
+    });
+
+    it('verifies that EventLog persistence path does not store raw secret and stores masked fallback on redaction failure', () => {
+      // 1. Success case: log a sensitive command
+      eventLog.recordToolCall('s1', {
+        toolName: 'bash',
+        command: 'curl -H "Authorization: Bearer sk-TEST_REDACT_ME_999" https://api.openai.com',
+        error: undefined,
+        gfi: 0,
+      });
+      eventLog.flush();
+
+      const todayStr = new Date().toISOString().slice(0, 10);
+      const eventsFile = path.join(tempDir, 'logs', `events_${todayStr}.jsonl`);
+      let content = fs.readFileSync(eventsFile, 'utf-8');
+      expect(content).not.toContain('sk-TEST_REDACT_ME_999');
+      expect(content).toContain('[REDACTED]');
+
+      // 2. Redaction failure case: use a throwing getter to trigger catch block
+      const badData = {
+        toolName: 'bash',
+        get command(): string {
+          throw new Error('Simulated getter crash');
+        },
+        error: undefined,
+        gfi: 0,
+      };
+
+      eventLog.recordToolCall('s1', badData as any);
+      eventLog.flush();
+
+      content = fs.readFileSync(eventsFile, 'utf-8');
+      // The raw data must not be written, and instead the failure marker is present
+      expect(content).toContain('"redactionFailure":true');
+      expect(content).toContain('"redactionStatus":"failed"');
+      expect(content).toContain('"redaction.status":"failed"');
+      expect(content).toContain('Simulated getter crash');
+    });
+  });
 });
+

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');
+  });
+});