@goodandready/dsh-goal 0.2.26 → 0.2.27

package/README.md

@@ -136,6 +136,11 @@ Handles `/goal` commands and subcommands:
 * **Quick Launch Button**: Floating launcher for rapid goal formulation without typing slash commands.
 * **Plugin Settings Card**: Schemastery-backed settings UI registered via `settings.plugin.item`.
 
+### 5. Two-Phase Goal Execution: Plan Mode ⇄ Act Mode (#162)
+* **Plan Mode (Read-Only Planning Phase)**: The agent explores the codebase, searches the web, and decomposes tasks into structured milestones and checklists. All file mutating tools (`write_to_file`, `replace_file_content`, mutating shell commands) are strictly blocked by `lib/tool-guard.js`.
+* **Act Mode (Implementation Phase)**: The operator reviews and approves the plan directly via the banner or details modal with «Approve & Execute», unlocking mutating capabilities and resuming the agent.
+* **REST API & Quick Launch**: Toggle modes on demand via `POST /dsh-goal/action` (`set_mode`, `approve_plan`), or select initial mode directly in the Quick Launch dialog.
+
 ---
 
 ## 📦 Installation

package/README.ru.md

@@ -53,6 +53,7 @@
 * 🤖 **Инструменты агента**: `goal_set_milestones`, `goal_update_progress` и `goal_finish` для самостоятельной работы ИИ.
 * 🔄 **Перехват и замещение инструментов ядра DSH (*Добавлено в v0.1.10*)**: Бесшовная совместимость для моделей, вызывающих стандартные инструменты DSH (`update_goal`, `get_goal`, `create_goal`). Перехватывает действия (`complete`, `pause`, `resume`, `edit`, `blocked`), устраняет падения ядра (`complete and blocked require a direct human turn`) и синхронизирует состояние напрямую с GoalEngine.
 * 🛡️ **Защитные лимиты**: настраиваемое ограничение `maxIterations` для предотвращения бесконечных циклов.
+* 🛡️ **Двухфазный режим «Plan Mode ⇄ Act Mode» (*#162*)**: Разделение жизненного цикла цели на фазу проектирования и планирования (только чтение и формирование этапов через `goal_milestones`, блокировка записи файлов и мутирующих команд) и фазу реализации (`Act Mode`), активируемую по кнопке «Утвердить план и запустить» (Approve & Execute).
 
 ---
 

package/README.zh.md

@@ -54,6 +54,7 @@
 * 🔄 **DSH 核心目标工具无缝拦截与兼容 (*v0.1.10 新增*)**: 为使用原生 DSH 目标控制指令的模型提供完美向下兼容，透明接管 `update_goal`、`get_goal`、`create_goal`。拦截并处理 `complete`、`pause`、`resume`、`edit`、`blocked` 等操作，彻底解决原生工具抛出的 `complete and blocked require a direct human turn` 权限崩溃错误，所有状态直接同步至 GoalEngine。
 * 🛡️ **安全防护机制**：支持自定义最大迭代次数（`maxIterations`）以及智能卡顿检测（Smart Progress Guard）。
 * 🔔 **Web Audio 提示音**：任务完成或失败时，通过 Web Audio API 播放舒缓的合成音效。
+* 📋 **两阶段目标模式：Plan Mode ⇄ Act Mode (*#162*)**：分离规划设计与落地执行。只读规划阶段严格限制文件变更与危险命令，待操作者在横幅或弹窗点击“批准并执行 (Approve & Execute)”后切入执行阶段。
 
 ---
 

package/lib/client.js

@@ -730,6 +730,66 @@ window.__ModuleLoader__.load({
 
       }
 
+      .dsh-goal-badge-plan {
+
+        border-color: var(--dsw-alias-brand-primary);
+
+        color: var(--dsw-alias-brand-primary);
+
+        background: var(--dsw-alias-bg-hover);
+
+      }
+
+      .dsh-goal-badge-act {
+
+        border-color: var(--dsw-alias-state-success-primary);
+
+        color: var(--dsw-alias-state-success-primary);
+
+        background: var(--dsw-alias-bg-hover);
+
+      }
+
+      .dsh-goal-btn-approve {
+
+        background: var(--dsw-alias-state-success-primary) !important;
+
+        color: var(--dsw-alias-bg-layer-3) !important;
+
+        font-weight: 600 !important;
+
+        border: none !important;
+
+        cursor: pointer;
+
+      }
+
+      .dsh-goal-btn-approve:hover {
+
+        opacity: 0.88;
+
+      }
+
+      .dsh-goal-plan-banner {
+
+        display: flex;
+
+        align-items: center;
+
+        justify-content: space-between;
+
+        padding: 8px 12px;
+
+        margin-bottom: 12px;
+
+        border-radius: 6px;
+
+        background: var(--dsw-alias-bg-hover);
+
+        border: 1px solid var(--dsw-alias-brand-primary);
+
+      }
+
       .dsh-goal-label {
 
         font-weight: 600;
@@ -1855,6 +1915,7 @@ window.__ModuleLoader__.load({
       const milestones = state.milestones || [];
 
       const isCompleted = state.state === 'COMPLETED';
+      const isPlanMode = state.mode === 'plan' || state.state === 'PLANNING';
 
       const [copied, setCopied] = useState(false);
 
@@ -1992,6 +2053,36 @@ window.__ModuleLoader__.load({
 
             ),
 
+            isPlanMode && !isCompleted
+              ? React.createElement(
+                  'div',
+                  { className: 'dsh-goal-plan-banner' },
+                  React.createElement(
+                    'div',
+                    { style: { display: 'flex', flexDirection: 'column', gap: 2 } },
+                    React.createElement(
+                      'div',
+                      { style: { display: 'flex', alignItems: 'center', gap: 6 } },
+                      React.createElement('span', { className: 'dsh-goal-badge dsh-goal-badge-plan' }, t('planMode') || 'Plan Mode'),
+                      React.createElement('strong', { style: { fontSize: 13, color: 'var(--dsw-alias-brand-primary)' } }, t('planningPhase') || 'Planning Phase (Read-Only)')
+                    ),
+                    React.createElement('span', { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } }, t('planPhaseNotice') || 'Agent is formulating the plan. File modifications are guarded until operator approval.')
+                  ),
+                  React.createElement(
+                    'button',
+                    {
+                      type: 'button',
+                      className: 'dsh-goal-btn dsh-goal-btn-approve',
+                      style: { padding: '6px 14px', fontSize: 12 },
+                      onClick: async () => {
+                        await onAction('approve_plan');
+                      },
+                    },
+                    '✓ ' + (t('approveAndExecute') || 'Approve & Execute')
+                  )
+                )
+              : null,
+
             !isCompleted
 
               ? React.createElement(
@@ -2561,6 +2652,20 @@ window.__ModuleLoader__.load({
 
               : null,
 
+            isPlanMode && !isCompleted
+              ? React.createElement(
+                  'button',
+                  {
+                    type: 'button',
+                    className: 'dsh-goal-btn dsh-goal-btn-approve',
+                    onClick: async () => {
+                      await onAction('approve_plan');
+                    },
+                  },
+                  '✓ ' + (t('approveAndExecute') || 'Approve & Execute')
+                )
+              : null,
+
             React.createElement(
 
               'button',
@@ -2590,6 +2695,7 @@ window.__ModuleLoader__.load({
     function QuickLaunchModal({ onClose, onStart, t }) {
 
       const [title, setTitle] = useState('');
+      const [launchMode, setLaunchMode] = useState('act');
       const [showTemplates, setShowTemplates] = useState(false);
       const [backendTemplates, setBackendTemplates] = useState([]);
       const [selectedTpl, setSelectedTpl] = useState(null);
@@ -2649,7 +2755,7 @@ window.__ModuleLoader__.load({
 
         if (trimmed) {
 
-          onStart(trimmed);
+          onStart(trimmed, { mode: launchMode });
 
         }
 
@@ -2727,6 +2833,34 @@ window.__ModuleLoader__.load({
 
               ),
 
+              React.createElement(
+                'div',
+                { style: { display: 'flex', alignItems: 'center', gap: 8, marginBottom: 10 } },
+                React.createElement('span', { style: { fontSize: 12, fontWeight: 600, color: 'var(--dsw-alias-label-secondary)' } }, t('launchModeLabel') || 'Mode:'),
+                React.createElement(
+                  'button',
+                  {
+                    type: 'button',
+                    className: `dsh-goal-chip-btn ${launchMode === 'act' ? 'active' : ''}`,
+                    style: launchMode === 'act' ? { fontWeight: 600, borderColor: 'var(--dsw-alias-state-success-primary)', color: 'var(--dsw-alias-state-success-primary)' } : {},
+                    onClick: () => setLaunchMode('act'),
+                    title: t('actModeDesc') || 'Direct execution right away',
+                  },
+                  '⚡ ' + (t('actMode') || 'Act Mode')
+                ),
+                React.createElement(
+                  'button',
+                  {
+                    type: 'button',
+                    className: `dsh-goal-chip-btn ${launchMode === 'plan' ? 'active' : ''}`,
+                    style: launchMode === 'plan' ? { fontWeight: 600, borderColor: 'var(--dsw-alias-brand-primary)', color: 'var(--dsw-alias-brand-primary)' } : {},
+                    onClick: () => setLaunchMode('plan'),
+                    title: t('planModeDesc') || 'Plan first, review milestones, then execute',
+                  },
+                  '📋 ' + (t('planMode') || 'Plan Mode')
+                )
+              ),
+
               React.createElement(
 
                 'div',
@@ -3504,9 +3638,9 @@ window.__ModuleLoader__.load({
 
                 onClose: () => setIsQuickLaunchOpen(false),
 
-                onStart: async (title) => {
+                onStart: async (title, opts) => {
 
-                  await handleAction('start', { title });
+                  await handleAction('start', { title, mode: opts?.mode });
 
                   setIsQuickLaunchOpen(false);
 
@@ -3526,6 +3660,8 @@ window.__ModuleLoader__.load({
 
       const isCompleted = state.state === 'COMPLETED';
 
+      const isPlanMode = state.mode === 'plan' || state.state === 'PLANNING';
+
       const formatElapsed = (totalSeconds) => {
         const s = Math.max(0, Math.floor(Number(totalSeconds) || 0));
         if (s < 60) return `${s}s`;
@@ -3580,11 +3716,21 @@ window.__ModuleLoader__.load({
                 ),
                 React.createElement(
                   'span',
-                  { className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isPaused ? 'dsh-goal-badge-warn' : ''}` },
-                  isCompleted ? (t('goalCompleted') || 'Done') : isPaused ? (t('paused') || 'Paused') : (t('goalLabel') || 'Goal')
+                  { className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isPlanMode ? 'dsh-goal-badge-plan' : isPaused ? 'dsh-goal-badge-warn' : ''}` },
+                  isCompleted ? (t('goalCompleted') || 'Done') : isPlanMode ? (t('planMode') || 'Plan Mode') : isPaused ? (t('paused') || 'Paused') : (t('goalLabel') || 'Goal')
                 ),
                 React.createElement('span', { className: 'dsh-goal-title', title: state.title }, state.title),
                 React.createElement('span', { className: 'dsh-goal-time' }, `⏱ ${liveElapsedStr}`),
+                isPlanMode && !isCompleted ? React.createElement(
+                  'button',
+                  {
+                    className: 'dsh-goal-btn dsh-goal-btn-approve',
+                    style: { padding: '2px 6px', height: 22, fontSize: 11 },
+                    title: t('approveAndExecute') || 'Approve & Execute',
+                    onClick: () => handleAction('approve_plan'),
+                  },
+                  '✓ ' + (t('approveAndExecute') || 'Approve')
+                ) : null,
                 !isCompleted ? React.createElement(
                   'button',
                   {
@@ -3644,11 +3790,11 @@ window.__ModuleLoader__.load({
 
                 {
 
-                  className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isPaused ? 'dsh-goal-badge-warn' : ''}`,
+                  className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isPlanMode ? 'dsh-goal-badge-plan' : isPaused ? 'dsh-goal-badge-warn' : ''}`,
 
                 },
 
-                isCompleted ? (t('goalCompleted') || 'Goal completed') : isPaused ? (t('paused') || 'Paused') : (t('goalLabel') || 'Current goal'),
+                isCompleted ? (t('goalCompleted') || 'Goal completed') : isPlanMode ? (t('planMode') || 'Plan Mode') : isPaused ? (t('paused') || 'Paused') : (t('goalLabel') || 'Current goal'),
 
               ),
 
@@ -3672,6 +3818,18 @@ window.__ModuleLoader__.load({
 
               ),
 
+              isPlanMode && !isCompleted
+                ? React.createElement(
+                    'button',
+                    {
+                      className: 'dsh-goal-btn dsh-goal-btn-approve',
+                      style: { fontSize: 12, padding: '2px 8px' },
+                      title: t('approveAndExecute') || 'Approve & Execute',
+                      onClick: () => handleAction('approve_plan'),
+                    },
+                    '✓ ' + (t('approveAndExecute') || 'Approve & Execute')
+                  )
+                : null,
               !isCompleted
 
                 ? React.createElement(
@@ -4983,6 +5141,15 @@ window.__ModuleLoader__.load({
         toolFailHint: 'Auto-pause goal if N consecutive turns hit tool execution errors (0 to disable)',
 
         notifLabel: 'Native browser desktop notifications on completion',
+        planMode: 'Plan Mode',
+        actMode: 'Act Mode',
+        approveAndExecute: 'Approve & Execute',
+        switchToPlan: 'Switch to Plan Mode',
+        planningPhase: 'Planning Phase (Read-Only)',
+        planPhaseNotice: 'Agent is formulating the plan. File modifications are guarded until operator approval.',
+        launchModeLabel: 'Launch Mode:',
+        planModeDesc: 'Plan first, review milestones, then execute',
+        actModeDesc: 'Direct execution right away',
 
       },
 
@@ -5122,6 +5289,15 @@ window.__ModuleLoader__.load({
         toolFailHint: '连续 N 轮遭遇工具调用错误时自动暂停（0 表示禁用）',
 
         notifLabel: '目标完成时发送浏览器桌面原生通知',
+        planMode: '规划模式',
+        actMode: '执行模式',
+        approveAndExecute: '批准并执行',
+        switchToPlan: '切换到规划模式',
+        planningPhase: '规划阶段（只读）',
+        planPhaseNotice: '智能体正在制定方案与里程碑。在操作者批准前，禁止修改文件。',
+        launchModeLabel: '启动模式：',
+        planModeDesc: '先制定里程碑方案，人工确认后再执行',
+        actModeDesc: '立即开始编码与任务执行',
 
       },
 

package/lib/engine-sessions.js

@@ -1,4 +1,4 @@
-import { GoalState } from './goal-engine-constants.js';
+import { GoalMode, GoalState } from './goal-engine-constants.js';
 
 /**
  * Prune inactive sessions when exceeding maxSessions threshold
@@ -81,3 +81,80 @@ export function extendGoalBudget(goal, addTokens = 50000, defaultBudget = 0) {
   if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
   return newBudget;
 }
+
+/**
+ * Set mode for a goal
+ */
+export function setGoalMode(goal, mode, recordActivity) {
+  if (mode !== GoalMode.PLAN && mode !== GoalMode.ACT) {
+    throw new Error(`Invalid mode: ${mode}. Must be one of: plan, act`);
+  }
+  if (!goal) {
+    throw new Error('No active goal found');
+  }
+  const previousMode = goal.mode || GoalMode.ACT;
+  goal.mode = mode;
+  if (mode === GoalMode.ACT && goal.state === GoalState.PLANNING) {
+    goal.state = GoalState.RUNNING;
+  } else if (mode === GoalMode.PLAN && goal.state === GoalState.RUNNING) {
+    goal.state = GoalState.PLANNING;
+  }
+  const message = mode === GoalMode.ACT
+    ? 'Plan approved by operator, switched to Act Mode'
+    : 'Switched to Plan Mode (read-only planning phase)';
+  goal.logs.push({ timestamp: Date.now(), type: 'info', message });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  if (typeof recordActivity === 'function') {
+    recordActivity(goal, { type: 'control', tool: 'setMode', status: 'info', details: `${previousMode} -> ${mode}` });
+  }
+  return goal;
+}
+
+/**
+ * Pause active goal
+ */
+export function pauseGoal(goal, reason, recordActivity) {
+  if (!goal || goal.state !== GoalState.RUNNING) return false;
+  goal.state = GoalState.PAUSED;
+  goal.pausedAt = Date.now();
+  if (typeof recordActivity === 'function') {
+    recordActivity(goal, { type: 'control', tool: 'pause', status: 'warning', details: reason });
+  }
+  goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Paused: ${reason}` });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  return true;
+}
+
+/**
+ * Resume paused goal
+ */
+export function resumeGoal(goal, recordActivity) {
+  if (!goal || goal.state !== GoalState.PAUSED) return false;
+  const now = Date.now();
+  if (goal.pausedAt) {
+    goal.totalPausedDurationMs += now - goal.pausedAt;
+    goal.pausedAt = null;
+  }
+  goal.state = GoalState.RUNNING;
+  if (typeof recordActivity === 'function') {
+    recordActivity(goal, { type: 'control', tool: 'resume', status: 'info', details: 'Resumed by user' });
+  }
+  goal.logs.push({ timestamp: now, type: 'info', message: 'Goal resumed' });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  return true;
+}
+
+/**
+ * Cancel active goal
+ */
+export function cancelGoal(goal, reason, recordActivity) {
+  if (!goal) return false;
+  goal.state = GoalState.CANCELLED;
+  goal.completedAt = Date.now();
+  if (typeof recordActivity === 'function') {
+    recordActivity(goal, { type: 'control', tool: 'cancel', status: 'warning', details: reason });
+  }
+  goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Cancelled: ${reason}` });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+  return true;
+}

package/lib/goal-engine-constants.js

@@ -4,6 +4,11 @@ import path from "node:path";
  * Enums and helpers for DSH Goal Engine
  */
 
+export const GoalMode = {
+  PLAN: 'plan',
+  ACT: 'act',
+};
+
 export const GoalState = {
   IDLE: 'IDLE',
   PLANNING: 'PLANNING',
@@ -144,6 +149,7 @@ export function buildSnapshot(goal, sid, engine) {
     return {
       sessionId: sid,
       hasActiveGoal: false,
+      mode: GoalMode.ACT,
       state: GoalState.IDLE,
       title: '',
       startedAt: null,
@@ -199,6 +205,7 @@ export function buildSnapshot(goal, sid, engine) {
     sessionId: sid,
     hasActiveGoal: true,
     id: goal.id,
+    mode: goal.mode || (goal.state === GoalState.PLANNING ? GoalMode.PLAN : GoalMode.ACT),
     state: goal.state,
     title: goal.title,
     description: goal.description,

package/lib/goal-engine.js

@@ -1,4 +1,4 @@
-import { GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, calculateElapsedSeconds, calculateRemainingSeconds, buildSnapshot, getSafeCwd } from './goal-engine-constants.js';
+import { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, calculateElapsedSeconds, calculateRemainingSeconds, buildSnapshot, getSafeCwd } from './goal-engine-constants.js';
 import { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact } from './engine-reports.js';
 import { EngineStore } from './engine-store.js';
 import { buildStatePromptInjection } from './engine-prompt.js';
@@ -8,9 +8,9 @@ import { createGoalBranch, sanitizeBranchSlug, getCurrentGitBranch, mergeGoalBra
 import { parseIssueRef, parseIssueChecklist, syncMilestoneWithIssue } from './engine-issue-sync.js';
 import { generateRetrospectiveData } from './engine-retrospective.js';
 import { generatePreplanDraft } from './engine-templates.js';
-import { pruneInactiveSessions, addNudgeToGoal, consumeGoalNudge, extendGoalBudget } from './engine-sessions.js';
+import { pruneInactiveSessions, addNudgeToGoal, consumeGoalNudge, extendGoalBudget, setGoalMode, pauseGoal, resumeGoal, cancelGoal } from './engine-sessions.js';
 
-export { GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist };
+export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist };
 export { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
 
 /**
@@ -193,6 +193,9 @@ export class GoalEngine {
       ? options.gitStartCommit
       : getGitCurrentCommit(options.cwd);
 
+    const initialMode = options.mode === GoalMode.PLAN ? GoalMode.PLAN : GoalMode.ACT;
+    const initialState = initialMode === GoalMode.PLAN ? GoalState.PLANNING : GoalState.RUNNING;
+
     const goal = {
       id: `goal-${now}-${Math.random().toString(36).substring(2, 7)}`,
       sessionId: sid,
@@ -200,7 +203,8 @@ export class GoalEngine {
       description: options.description?.trim() || '',
       lang: options.lang || detectLanguage(cleanTitle),
       cwd: options.cwd ? getSafeCwd(options.cwd) : null,
-      state: GoalState.RUNNING,
+      mode: initialMode,
+      state: initialState,
       startedAt: now,
       pausedAt: null,
       totalPausedDurationMs: 0,
@@ -265,13 +269,7 @@ export class GoalEngine {
   pause(reason = 'User requested pause', sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || goal.state !== GoalState.RUNNING) return this.getSnapshot(sid);
-
-    goal.state = GoalState.PAUSED;
-    goal.pausedAt = Date.now();
-    recordActivity(goal, { type: 'control', tool: 'pause', status: 'warning', details: reason });
-    goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Paused: ${reason}` });
-    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+    if (!pauseGoal(goal, reason, recordActivity)) return this.getSnapshot(sid);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -279,18 +277,8 @@ export class GoalEngine {
   resume(sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal || goal.state !== GoalState.PAUSED) return this.getSnapshot(sid);
-
-    const now = Date.now();
-    if (goal.pausedAt) {
-      goal.totalPausedDurationMs += now - goal.pausedAt;
-      goal.pausedAt = null;
-    }
-    goal.state = GoalState.RUNNING;
+    if (!resumeGoal(goal, recordActivity)) return this.getSnapshot(sid);
     this.stallCounters.set(sid, 0);
-    recordActivity(goal, { type: 'control', tool: 'resume', status: 'info', details: 'Resumed by user' });
-    goal.logs.push({ timestamp: now, type: 'info', message: 'Goal resumed' });
-    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -298,13 +286,7 @@ export class GoalEngine {
   cancel(reason = 'Cancelled by user', sessionId = 'default') {
     const sid = sessionId || 'default';
     const goal = this.goals.get(sid);
-    if (!goal) return null;
-
-    goal.state = GoalState.CANCELLED;
-    goal.completedAt = Date.now();
-    recordActivity(goal, { type: 'control', tool: 'cancel', status: 'warning', details: reason });
-    goal.logs.push({ timestamp: Date.now(), type: 'warning', message: `Cancelled: ${reason}` });
-    if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+    if (!cancelGoal(goal, reason, recordActivity)) return null;
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
@@ -580,4 +562,26 @@ export class GoalEngine {
     const goal = this.goals.get(sid);
     if (goal) recordActivity(goal, { type: 'tool', tool, status, details });
   }
+
+  setMode(mode, sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal) throw new Error(`No active goal for session "${sid}"`);
+    setGoalMode(goal, mode, recordActivity);
+    this.emit(sid, true);
+    return this.getSnapshot(sid);
+  }
+
+  approvePlan(sessionId = 'default') {
+    return this.setMode(GoalMode.ACT, sessionId);
+  }
+
+  getActiveGoal(sessionId = 'default') {
+    return this.goals.get(sessionId || 'default') || null;
+  }
+
+  isPlanMode(sessionId = 'default') {
+    const goal = this.goals.get(sessionId || 'default');
+    return Boolean(goal && (goal.mode === GoalMode.PLAN || goal.state === GoalState.PLANNING));
+  }
 }

package/lib/index.js

@@ -19,6 +19,7 @@ import { GitSnapshotManager } from './git-snapshot-manager.js';
 import { MilestoneManager } from './milestone-manager.js';
 import { registerRoutes } from './routes.js';
 import { registerTools } from './tools.js';
+import { registerPlanModeGuard, createPlanModeGuard, isPermittedInPlanMode } from './tool-guard.js';
 import { saveGoalReportFile } from './engine-reports.js';
 import { registerPluginUpdater } from './updater.js';
 import { GoalEngine, GoalState } from './goal-engine.js';
@@ -168,6 +169,7 @@ export function apply(ctx, config = {}) {
       enableMilestoneDependencies: currentSettings.enableMilestoneDependencies,
       logger,
     });
+    registerPlanModeGuard(ctx, { engine: fallbackEngine, logger });
   }
 
   // 1. One-click auto-updater registration (Issue #99)
@@ -414,3 +416,5 @@ export function apply(ctx, config = {}) {
     engine: fallbackEngine,
   };
 }
+
+export { registerPlanModeGuard, createPlanModeGuard, isPermittedInPlanMode };

package/lib/routes.js

@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { MilestoneStatus, detectLanguage, sessionIdOf, isPathInsideOrEqual, getSafeCwd } from './goal-engine-constants.js';
+import { MilestoneStatus, GoalMode, detectLanguage, sessionIdOf, isPathInsideOrEqual, getSafeCwd } from './goal-engine-constants.js';
 import { isValidGitRef } from './engine-git-branch.js';
 import { saveGoalArtifact, rollbackToCheckpoint } from './engine-reports.js';
 import { getTemplatesCatalogue, instantiateTemplate } from './engine-templates.js';
@@ -467,24 +467,32 @@ export function registerRoutes(ctx, {
                       lang: detectedLang,
                       cwd: safeStartCwd,
                       issueBody: data.issueBody,
+                      mode: data.mode,
                     }, sid);
                   } else {
                     let parsedMilestones = [];
                     if (data.issueBody) {
                       parsedMilestones = parseIssueChecklist(data.issueBody);
                     }
+                    const initialMode = data.mode === 'plan' ? 'plan' : 'act';
                     result = {
                       title: cleanTitle,
                       sessionId: sid,
                       hasActiveGoal: true,
-                      state: 'RUNNING',
+                      mode: initialMode,
+                      state: initialMode === 'plan' ? 'PLANNING' : 'RUNNING',
                       milestones: parsedMilestones,
                     };
                   }
 
-                  const startPrompt = detectedLang === 'zh'
-                    ? `🎯 目标已确立：“${cleanTitle}”。请立即通过 goal_milestones 制定工作计划并开始执行。`
-                    : `🎯 Goal established: "${cleanTitle}". Formulate milestones via goal_milestones and proceed.`;
+                  const isPlan = result?.mode === 'plan' || (engine && typeof engine.isPlanMode === 'function' && engine.isPlanMode(sid));
+                  const startPrompt = isPlan
+                    ? (detectedLang === 'zh'
+                      ? `🎯 目标已确立（规划模式/Plan Mode）：“${cleanTitle}”。请通过 goal_milestones 制定工作计划并列出检查清单。在操作者批准前，请勿进行写文件等变更操作。`
+                      : `🎯 Goal established in Plan Mode: "${cleanTitle}". Formulate milestones and checklist via goal_milestones and goal_checklist. Do not modify files until the operator approves the plan.`)
+                    : (detectedLang === 'zh'
+                      ? `🎯 目标已确立：“${cleanTitle}”。请立即通过 goal_milestones 制定工作计划并开始执行。`
+                      : `🎯 Goal established: "${cleanTitle}". Formulate milestones via goal_milestones and proceed.`);
 
                   if (typeof resumeActiveAgent === 'function') {
                     resumeActiveAgent(startPrompt, sid);
@@ -714,6 +722,55 @@ export function registerRoutes(ctx, {
                   break;
                 }
 
+                case 'set_mode': {
+                  const targetMode = data.mode;
+                  if (targetMode !== GoalMode.PLAN && targetMode !== GoalMode.ACT) {
+                    res.statusCode = 400;
+                    return res.end(JSON.stringify({ error: `Invalid mode "${targetMode}". Must be "plan" or "act".` }));
+                  }
+                  if (engine) {
+                    const snap = engine.getSnapshot(sid);
+                    if (!snap || !snap.hasActiveGoal) {
+                      res.statusCode = 404;
+                      return res.end(JSON.stringify({ error: 'No active goal found to set mode' }));
+                    }
+                    result = engine.setMode(targetMode, sid);
+                    if (targetMode === GoalMode.ACT) {
+                      const detectedLang = snap.lang || 'en';
+                      const prompt = detectedLang === 'zh'
+                        ? '⚡ 执行模式（Act Mode）已激活。请继续推进目标任务。'
+                        : '⚡ Act Mode activated by operator. Proceed with task execution.';
+                      if (typeof resumeActiveAgent === 'function') {
+                        resumeActiveAgent(prompt, sid);
+                      }
+                    }
+                  } else {
+                    result = { mode: targetMode, state: targetMode === GoalMode.PLAN ? 'PLANNING' : 'RUNNING' };
+                  }
+                  break;
+                }
+
+                case 'approve_plan': {
+                  if (engine) {
+                    const snap = engine.getSnapshot(sid);
+                    if (!snap || !snap.hasActiveGoal) {
+                      res.statusCode = 404;
+                      return res.end(JSON.stringify({ error: 'No active goal found to approve plan' }));
+                    }
+                    result = engine.approvePlan(sid);
+                    const detectedLang = snap.lang || 'en';
+                    const prompt = detectedLang === 'zh'
+                      ? '✅ 操作者已批准计划。执行模式（Act Mode）已激活。请立即开始具体代码与任务实现。'
+                      : '✅ Plan approved by operator. Act Mode activated. Proceed with implementation.';
+                    if (typeof resumeActiveAgent === 'function') {
+                      resumeActiveAgent(prompt, sid);
+                    }
+                  } else {
+                    result = { mode: GoalMode.ACT, state: 'RUNNING', approved: true };
+                  }
+                  break;
+                }
+
                 case 'branch_action': {
                   const op = String(data.operation || data.branchOperation || 'merge').toLowerCase();
                   const targetBranch = String(data.targetBranch || 'main');

package/lib/tool-guard.js

@@ -0,0 +1,147 @@
+/**
+ * Plan Mode tool execution guard for @goodandready/dsh-goal.
+ * Blocks mutating file operations and commands during the planning phase.
+ */
+
+export const READ_ONLY_TOOLS = new Set([
+  'view_file',
+  'read_file',
+  'read_url_content',
+  'search_web',
+  'search',
+  'grep',
+  'glob',
+  'find',
+  'list_dir',
+  'dir_list',
+  'code_search',
+  'read_resource',
+  'list_resources',
+  'brain_recall',
+  'brain_list',
+  'brain_status',
+  'brain_remember',
+  'ask_question',
+  'send_message',
+  'schedule',
+  'manage_task',
+  'get_goal',
+]);
+
+export const FILE_WRITER_TOOLS = new Set([
+  'write_to_file',
+  'replace_file_content',
+  'edit_file',
+  'apply_diff',
+  'patch',
+  'create_file',
+  'delete_file',
+  'remove_file',
+]);
+
+const SAFE_COMMAND_PATTERN = /^(git\s+(status|diff|log|branch|show)|ls|dir|pwd|cat|head|tail|grep|find|wc|echo|which|where)(\s+|$)/i;
+const MUTATING_COMMAND_PATTERN = /(\b(rm|rmdir|mv|cp|mkdir|touch|chmod|chown|sed\s+-i|git\s+(commit|checkout\s+-b|push|merge|rebase|reset|restore))\b|[>|&;])/i;
+
+/**
+ * Check whether a tool is permitted in Plan Mode.
+ * @param {string} toolName
+ * @param {object} [args]
+ * @returns {boolean}
+ */
+export function isPermittedInPlanMode(toolName, args = {}) {
+  if (!toolName || typeof toolName !== 'string') return false;
+
+  // Milestone and checklist tools are explicitly permitted in plan mode
+  if (toolName === 'goal_milestones' || toolName === 'goal_checklist') {
+    return true;
+  }
+
+  // Explicit file writing tools are strictly blocked
+  if (FILE_WRITER_TOOLS.has(toolName)) {
+    return false;
+  }
+
+  // Check command execution
+  if (toolName === 'run_command' || toolName === 'execute_command' || toolName === 'bash') {
+    const rawCmd = (args.CommandLine || args.command || args.cmd || '').trim();
+    if (!rawCmd) return true;
+    if (SAFE_COMMAND_PATTERN.test(rawCmd) && !MUTATING_COMMAND_PATTERN.test(rawCmd)) {
+      return true;
+    }
+    return false;
+  }
+
+  // Allow known read-only inspection tools
+  if (READ_ONLY_TOOLS.has(toolName)) {
+    return true;
+  }
+
+  // Default fail-closed for unknown tools in plan mode
+  return false;
+}
+
+/**
+ * Create a tool guard function for Cordis ctx.tools.guard.
+ * @param {import('./goal-engine.js').GoalEngine} engine
+ * @param {object} [logger]
+ * @returns {(execution: object) => string | undefined}
+ */
+export function createPlanModeGuard(engine, logger = console) {
+  return function planModeGuard(execution) {
+    if (!engine || typeof engine.isPlanMode !== 'function') return undefined;
+
+    const sid = execution?.sessionId || execution?.session?.id || 'default';
+    if (!engine.isPlanMode(sid)) {
+      return undefined;
+    }
+
+    const toolName = execution?.name || execution?.tool || '';
+    if (isPermittedInPlanMode(toolName, execution?.arguments)) {
+      return undefined;
+    }
+
+    const rejection = `[Plan Mode Active] Tool "${toolName}" is blocked in Plan Mode. The goal is in the planning phase and file modifications are restricted until the plan is approved by the operator. Use goal_milestones to define the milestones and ask the operator to approve the plan or switch to Act Mode.`;
+    logger?.warn?.(`[dsh-goal] Blocked tool execution in Plan Mode: ${toolName}`);
+    return rejection;
+  };
+}
+
+/**
+ * Register the plan mode guard with Cordis context.
+ * @param {any} ctx
+ * @param {object} options
+ * @param {import('./goal-engine.js').GoalEngine} options.engine
+ * @param {object} [options.logger]
+ */
+export function registerPlanModeGuard(ctx, { engine, logger = console } = {}) {
+  if (!ctx || !engine) return;
+
+  const guard = createPlanModeGuard(engine, logger);
+
+  // 1. Cordis tools service guard
+  ctx.inject(['tools'], (tctx) => {
+    if (typeof tctx.tools?.guard === 'function') {
+      try {
+        const unguard = tctx.tools.guard(guard);
+        if (typeof unguard === 'function' && typeof tctx.effect === 'function') {
+          tctx.effect(() => () => {
+            try { unguard(); } catch (e) { /* ignore */ }
+          }, 'dsh-goal: plan mode tool guard');
+        }
+      } catch (err) {
+        logger?.warn?.('[dsh-goal] Failed to register tools guard:', err.message);
+      }
+    }
+  });
+
+  // 2. Pre-execute event hook if present
+  if (typeof ctx.on === 'function') {
+    ctx.on('tools/pre-execute', (execution, next) => {
+      const decision = guard(execution);
+      if (decision !== undefined) {
+        return { kind: 'deny', reason: decision };
+      }
+      return typeof next === 'function' ? next() : undefined;
+    });
+  }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@goodandready/dsh-goal",
-  "version": "0.2.26",
+  "version": "0.2.27",
   "description": "Core Goal Addon (Token Budget, Milestones, Git Snapshots & Retrospective Reports) for DeepSeek Harness",
   "type": "module",
   "main": "./lib/index.js",