@goodandready/dsh-goal 0.2.28 → 0.2.30

package/lib/client.js

@@ -32,28 +32,152 @@ window.__ModuleLoader__.load({
 
     // --- 10 QUICK LAUNCH ENGINEERING TEMPLATES ---
 
-    const QUICK_LAUNCH_TEMPLATES = [
-
-      { id: 'fix', icon: '🐛', label: { en: 'Fix Bug', zh: '修复缺陷' }, prefix: { en: 'Investigate bug, pinpoint root cause, apply fix, and verify with tests: ', zh: '调查并定位缺陷根源，实施修复并通过测试验证：' } },
-
-      { id: 'refactor', icon: '⚡', label: { en: 'Refactor (YAGNI)', zh: '重构精简' }, prefix: { en: 'Refactor module applying YAGNI principle, delete redundant abstractions, and verify: ', zh: '遵循 YAGNI 原则重构模块，删除冗余抽象并验证：' } },
-
-      { id: 'tests', icon: '📝', label: { en: 'Tests & Coverage', zh: '补充测试' }, prefix: { en: 'Write comprehensive unit tests covering edge cases for: ', zh: '为以下模块编写覆盖边界情况的完整单元测试：' } },
-
-      { id: 'review', icon: '🔍', label: { en: 'Code Review', zh: '代码审计' }, prefix: { en: 'Review codebase for subtle bugs, memory leaks, and over-engineering in: ', zh: '对代码库进行深入审查，排查潜在缺陷与过度设计：' } },
-
-      { id: 'feature', icon: '🚀', label: { en: 'New Feature', zh: '新功能开发' }, prefix: { en: 'Implement new feature according to specification and add tests for: ', zh: '根据规格说明实现新功能并补充测试：' } },
-
-      { id: 'security', icon: '🛡️', label: { en: 'Security Audit', zh: '安全加固' }, prefix: { en: 'Audit security boundaries, sanitize inputs, and prevent injection in: ', zh: '审计安全边界，增加输入过滤与防注入保护：' } },
-
-      { id: 'docs', icon: '📚', label: { en: 'Docs & Contract', zh: '文档规范' }, prefix: { en: 'Update technical documentation, README, and DESIGN.md conforming to standard for: ', zh: '按标准更新技术文档、README 与 DESIGN.md：' } },
-
-      { id: 'upgrade', icon: '📦', label: { en: 'Upgrade Deps', zh: '依赖升级' }, prefix: { en: 'Upgrade dependencies, resolve breaking API changes, and verify build for: ', zh: '安全升级依赖库，解决接口兼容性并确保构建通过：' } },
-
-      { id: 'cleanup', icon: '🧹', label: { en: 'Dead Code', zh: '清理死代码' }, prefix: { en: 'Find and safely remove dead code, unused exports, and stale fixtures in: ', zh: '查找并安全移除死代码、未使用的导出与失效测试用例：' } },
-
-      { id: 'perf', icon: '⚙️', label: { en: 'Performance', zh: '性能优化' }, prefix: { en: 'Profile performance bottlenecks, eliminate unnecessary blocking calls in: ', zh: '分析性能瓶颈，消除阻塞调用并优化响应速度：' } },
+    function formatQuickLaunchPrompt(tmpl, vars, lang) {
+      if (!tmpl) return "";
+      const chosenLang = lang === "zh" ? "zh" : "en";
+      const tStr = tmpl.template ? (tmpl.template[chosenLang] || tmpl.template.en) : null;
+      if (!tStr) return tmpl.prefix ? (tmpl.prefix[chosenLang] || tmpl.prefix.en) : "";
+      return tStr.replace(/\{\{([a-zA-Z0-9_]+)\}\}/g, (_, key) => {
+        return (vars && vars[key] != null && vars[key] !== "") ? String(vars[key]) : "";
+      }).replace(/\s+/g, " ").trim();
+    }
 
+    const QUICK_LAUNCH_TEMPLATES = [
+      {
+        id: 'fix',
+        icon: "🐛",
+        label: { en: "Fix Bug", zh: "修复缺陷" },
+        prefix: { en: "Investigate bug, pinpoint root cause, apply fix, and verify with tests: ", zh: "调查并定位缺陷根源，实施修复并通过测试验证：" },
+        template: {
+          en: "Investigate bug {{issueNumber}} in {{targetModule}}, pinpoint root cause, apply targeted fix, and verify with tests: {{description}}",
+          zh: "调查缺陷 {{issueNumber}}（位于 {{targetModule}}），定位根因，实施修复并通过测试验证：{{description}}"
+        },
+        variables: [
+          { id: "issueNumber", label: { en: "Issue #", zh: "Issue 编号" }, placeholder: '#issue-123', required: true },
+          { id: "targetModule", label: { en: "Target Module", zh: "目标模块" }, placeholder: "lib/tools.js" },
+          { id: 'description', label: { en: "Description / Symptom", zh: "症状或描述" }, placeholder: "Describe symptom..." },
+        ],
+      },
+      {
+        id: 'refactor',
+        icon: "⚡",
+        label: { en: "Refactor (YAGNI)", zh: "重构精简" },
+        prefix: { en: "Refactor module applying YAGNI principle, delete redundant abstractions, and verify: ", zh: "遵循 YAGNI 原则重构模块，删除冗余抽象并验证：" },
+        template: {
+          en: "Refactor module {{targetFile}} applying YAGNI principle to < {{maxLines}} lines, delete redundant abstractions, and verify tests.",
+          zh: "遵循 YAGNI 原则重构模块 {{targetFile}} 至 < {{maxLines}} 行，删除冗余代码并验证测试。"
+        },
+        variables: [
+          { id: "targetFile", label: { en: "Target File", zh: "目标文件" }, placeholder: "lib/goal-engine.js", required: true },
+          { id: "maxLines", label: { en: "Max Lines Threshold", zh: "行数上限" }, placeholder: "500" },
+        ],
+      },
+      {
+        id: 'tests',
+        icon: "📝",
+        label: { en: "Tests & Coverage", zh: "补充测试" },
+        prefix: { en: "Write comprehensive unit tests covering edge cases for: ", zh: "为以下模块编写覆盖边界情况的完整单元测试：" },
+        template: {
+          en: "Write comprehensive unit tests in {{testFile}} covering edge cases for {{targetFile}}.",
+          zh: "在 {{testFile}} 中为 {{targetFile}} 编写覆盖边界情况的完整单元测试。"
+        },
+        variables: [
+          { id: "targetFile", label: { en: "Module to Test", zh: "被测模块" }, placeholder: "lib/engine-verification.js", required: true },
+          { id: "testFile", label: { en: "Test File Path", zh: "测试文件路径" }, placeholder: "test/acceptance-gate.test.mjs" },
+        ],
+      },
+      {
+        id: 'review',
+        icon: "🔍",
+        label: { en: "Code Review", zh: "代码审计" },
+        prefix: { en: "Review codebase for subtle bugs, memory leaks, and over-engineering in: ", zh: "对代码库进行深入审查，排查潜在缺陷与过度设计：" },
+        template: {
+          en: "Review codebase for subtle bugs, memory leaks, and over-engineering in {{targetScope}}.",
+          zh: "对 {{targetScope}} 进行深入审查，排查潜在缺陷与过度设计。"
+        },
+        variables: [
+          { id: "targetScope", label: { en: "Target Scope", zh: "审查范围" }, placeholder: "lib/ and src/client/", required: true },
+        ],
+      },
+      {
+        id: 'feature',
+        icon: "🚀",
+        label: { en: "New Feature", zh: "新功能开发" },
+        prefix: { en: "Implement new feature according to specification and add tests for: ", zh: "根据规格说明实现新功能并补充测试：" },
+        template: {
+          en: "Implement feature {{featureName}} according to specification {{specDetails}} and add comprehensive tests.",
+          zh: "根据规格 {{specDetails}} 实现新功能 {{featureName}} 并补充完整测试。"
+        },
+        variables: [
+          { id: "featureName", label: { en: "Feature Name", zh: "功能名称" }, placeholder: "Bi-directional kanban sync", required: true },
+          { id: "specDetails", label: { en: "Specification / Issue", zh: "规格或Issue" }, placeholder: '#issue-164' },
+        ],
+      },
+      {
+        id: 'security',
+        icon: "🛡️",
+        label: { en: "Security Audit", zh: "安全加固" },
+        prefix: { en: "Audit security boundaries, sanitize inputs, and prevent injection in: ", zh: "审计安全边界，增加输入过滤与防注入保护：" },
+        template: {
+          en: "Audit security boundaries, sanitize inputs, and prevent injection in {{targetRoute}}.",
+          zh: "审计 {{targetRoute}} 的安全边界，增加输入过滤与防注入保护。"
+        },
+        variables: [
+          { id: "targetRoute", label: { en: "Routes / Subsystem", zh: "路由或子系统" }, placeholder: "lib/routes.js", required: true },
+        ],
+      },
+      {
+        id: 'docs',
+        icon: "📚",
+        label: { en: "Docs & Contract", zh: "文档规范" },
+        prefix: { en: "Update technical documentation, README, and DESIGN.md conforming to standard for: ", zh: "按标准更新技术文档、README 与 DESIGN.md：" },
+        template: {
+          en: "Update technical documentation, README, and {{docTarget}} conforming to engineering standards.",
+          zh: "按标准更新技术文档、README 与 {{docTarget}}。"
+        },
+        variables: [
+          { id: "docTarget", label: { en: "Doc Scope / Module", zh: "文档范围或模块" }, placeholder: "docs/design/DESIGN.md", required: true },
+        ],
+      },
+      {
+        id: 'upgrade',
+        icon: "📦",
+        label: { en: "Upgrade Deps", zh: "依赖升级" },
+        prefix: { en: "Upgrade dependencies, resolve breaking API changes, and verify build for: ", zh: "安全升级依赖库，解决接口兼容性并确保构建通过：" },
+        template: {
+          en: "Upgrade dependency {{depName}}, resolve breaking API changes, and verify build.",
+          zh: "升级依赖库 {{depName}}，解决接口兼容性并确保构建通过。"
+        },
+        variables: [
+          { id: "depName", label: { en: "Dependency Name", zh: "依赖包名" }, placeholder: "cordis@^4.0.0", required: true },
+        ],
+      },
+      {
+        id: 'cleanup',
+        icon: "🧹",
+        label: { en: "Dead Code", zh: "清理死代码" },
+        prefix: { en: "Find and safely remove dead code, unused exports, and stale fixtures in: ", zh: "查找并安全移除死代码、未使用的导出与失效测试用例：" },
+        template: {
+          en: "Find and safely remove dead code, unused exports, and stale fixtures in {{cleanupTarget}}.",
+          zh: "查找并安全移除 {{cleanupTarget}} 中的死代码、未使用的导出与失效测试用例。"
+        },
+        variables: [
+          { id: "cleanupTarget", label: { en: "Target Scope", zh: "清理目标" }, placeholder: "src/client/ or unused fixtures", required: true },
+        ],
+      },
+      {
+        id: 'perf',
+        icon: "⚙️",
+        label: { en: "Performance", zh: "性能优化" },
+        prefix: { en: "Profile performance bottlenecks, eliminate unnecessary blocking calls in: ", zh: "分析性能瓶颈，消除阻塞调用并优化响应速度：" },
+        template: {
+          en: "Profile performance bottlenecks, eliminate unnecessary blocking calls in {{perfTarget}}.",
+          zh: "分析性能瓶颈，消除 {{perfTarget}} 中的阻塞调用并优化响应速度。"
+        },
+        variables: [
+          { id: "perfTarget", label: { en: "Subsystem / Function", zh: "优化目标" }, placeholder: "buildClient or state flush", required: true },
+        ],
+      },
     ];
 
     // --- SVG ICONS ---
@@ -1653,6 +1777,28 @@ window.__ModuleLoader__.load({
         gap: 3px;
       }
 
+      .dsh-goal-template-chip.active {
+        border-color: var(--dsw-alias-brand-primary);
+        font-weight: 600;
+        background: var(--dsw-alias-bg-layer-3);
+      }
+
+      .dsh-goal-operator-card {
+        background: var(--dsw-alias-bg-sunken);
+        border: 1px solid var(--dsw-alias-state-warning-primary);
+        border-radius: 6px;
+        padding: 10px 12px;
+        margin-top: 8px;
+      }
+
+      .dsh-goal-tpl-vars-box {
+        background: var(--dsw-alias-bg-sunken);
+        border: 1px solid var(--dsw-alias-border-l1);
+        border-radius: 6px;
+        padding: 8px 10px;
+        margin-bottom: 10px;
+      }
+
       .dsh-goal-gate-error {
         font-size: 11px;
         color: var(--dsw-alias-state-danger-primary);
@@ -2736,6 +2882,8 @@ window.__ModuleLoader__.load({
 
       const [title, setTitle] = useState('');
       const [launchMode, setLaunchMode] = useState('act');
+      const [activeQuickTpl, setActiveQuickTpl] = useState(null);
+      const [quickTplVars, setQuickTplVars] = useState({});
       const [showTemplates, setShowTemplates] = useState(false);
       const [backendTemplates, setBackendTemplates] = useState([]);
       const [selectedTpl, setSelectedTpl] = useState(null);
@@ -2925,16 +3073,27 @@ window.__ModuleLoader__.load({
 
                       type: 'button',
 
-                      className: 'dsh-goal-template-chip',
+                      className: `dsh-goal-template-chip ${activeQuickTpl?.id === tmpl.id ? 'active' : ''}`,
+                      style: activeQuickTpl?.id === tmpl.id ? { borderColor: 'var(--dsw-alias-brand-primary)', fontWeight: 600 } : {},
 
                       title: prefix,
 
                       onClick: () => {
-
-                        setTitle(prefix);
-
+                        const isSelected = activeQuickTpl?.id === tmpl.id;
+                        if (isSelected) {
+                          setActiveQuickTpl(null);
+                          setQuickTplVars({});
+                        } else {
+                          setActiveQuickTpl(tmpl);
+                          const initial = {};
+                          (tmpl.variables || []).forEach((v) => { initial[v.id] = ""; });
+                          setQuickTplVars(initial);
+                          const generated = typeof formatQuickLaunchPrompt === "function"
+                            ? formatQuickLaunchPrompt(tmpl, initial, lang)
+                            : prefix;
+                          setTitle(generated || prefix);
+                        }
                         if (inputRef.current) inputRef.current.focus();
-
                       },
 
                     },
@@ -2947,6 +3106,75 @@ window.__ModuleLoader__.load({
 
               ),
 
+              activeQuickTpl?.variables && activeQuickTpl.variables.length > 0
+                ? React.createElement(
+                    'div',
+                    {
+                      className: 'dsh-goal-tpl-vars-box',
+                      style: {
+                        background: 'var(--dsw-alias-bg-sunken)',
+                        border: '1px solid var(--dsw-alias-border-l1)',
+                        borderRadius: 6,
+                        padding: '8px 10px',
+                        marginBottom: 10,
+                      },
+                    },
+                    React.createElement(
+                      'div',
+                      {
+                        style: {
+                          fontSize: 11,
+                          fontWeight: 600,
+                          color: 'var(--dsw-alias-label-secondary)',
+                          marginBottom: 6,
+                          display: 'flex',
+                          alignItems: 'center',
+                          justifyContent: 'space-between',
+                        },
+                      },
+                      React.createElement('span', null, `${activeQuickTpl.icon} ${activeQuickTpl.label[lang] || activeQuickTpl.label.en} ${t('quickTplVariablesTitle') || 'Parameters:'}`),
+                      React.createElement(
+                        'button',
+                        {
+                          type: 'button',
+                          className: 'dsh-goal-btn icon-only',
+                          style: { fontSize: 10, padding: '2px 4px', height: 'auto' },
+                          onClick: () => { setActiveQuickTpl(null); setQuickTplVars({}); },
+                        },
+                        '✕'
+                      )
+                    ),
+                    activeQuickTpl.variables.map((v) => {
+                      const vLabel = v.label ? (v.label[lang] || v.label.en) : v.id;
+                      return React.createElement(
+                        'div',
+                        { key: v.id, style: { marginBottom: 6 } },
+                        React.createElement(
+                          'label',
+                          { style: { fontSize: 11, display: 'block', color: 'var(--dsw-alias-label-primary)', marginBottom: 2 } },
+                          vLabel,
+                          v.required ? React.createElement('span', { style: { color: 'var(--dsw-alias-state-danger-primary)', marginLeft: 3 } }, '*') : null
+                        ),
+                        React.createElement('input', {
+                          type: 'text',
+                          className: 'dsh-goal-card-input',
+                          style: { width: '100%', boxSizing: 'border-box', fontSize: 12, padding: '4px 8px' },
+                          placeholder: v.placeholder || '',
+                          value: quickTplVars[v.id] || '',
+                          onChange: (e) => {
+                            const updated = { ...quickTplVars, [v.id]: e.target.value };
+                            setQuickTplVars(updated);
+                            const generated = typeof formatQuickLaunchPrompt === 'function'
+                              ? formatQuickLaunchPrompt(activeQuickTpl, updated, lang)
+                              : activeQuickTpl.prefix[lang] || activeQuickTpl.prefix.en;
+                            setTitle(generated);
+                          },
+                        })
+                      );
+                    })
+                  )
+                : null,
+
               React.createElement('input', {
 
                 ref: inputRef,
@@ -3177,6 +3405,7 @@ window.__ModuleLoader__.load({
       const [isModalOpen, setIsModalOpen] = useState(false);
 
       const [isQuickLaunchOpen, setIsQuickLaunchOpen] = useState(false);
+      const [operatorAnswerInput, setOperatorAnswerInput] = useState('');
 
       const [isDockCollapsed, setIsDockCollapsed] = useState(() => {
         try {
@@ -3701,6 +3930,7 @@ window.__ModuleLoader__.load({
       const isCompleted = state.state === 'COMPLETED';
 
       const isPlanMode = state.mode === 'plan' || state.state === 'PLANNING';
+      const isWaitingOperator = Boolean(state.waitingForOperator && state.operatorQuery);
 
       const formatElapsed = (totalSeconds) => {
         const s = Math.max(0, Math.floor(Number(totalSeconds) || 0));
@@ -3756,8 +3986,8 @@ window.__ModuleLoader__.load({
                 ),
                 React.createElement(
                   'span',
-                  { 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')
+                  { className: `dsh-goal-badge ${isCompleted ? 'dsh-goal-badge-ok' : isWaitingOperator ? 'dsh-goal-badge-warn' : isPlanMode ? 'dsh-goal-badge-plan' : isPaused ? 'dsh-goal-badge-warn' : ''}` },
+                  isCompleted ? (t('goalCompleted') || 'Done') : isWaitingOperator ? ('❓ ' + (t('operatorInputRequired') || 'Input Needed')) : 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}`),
@@ -3965,6 +4195,112 @@ window.__ModuleLoader__.load({
 
             ),
 
+            isWaitingOperator
+              ? React.createElement(
+                  'div',
+                  {
+                    className: 'dsh-goal-operator-card',
+                    style: {
+                      background: 'var(--dsw-alias-bg-sunken)',
+                      border: '1px solid var(--dsw-alias-state-warning-primary)',
+                      borderRadius: 6,
+                      padding: '10px 12px',
+                      marginTop: 8,
+                    },
+                  },
+                  React.createElement(
+                    'div',
+                    {
+                      style: {
+                        display: 'flex',
+                        alignItems: 'center',
+                        gap: 6,
+                        fontSize: 12,
+                        fontWeight: 600,
+                        color: 'var(--dsw-alias-state-warning-primary)',
+                        marginBottom: 4,
+                      },
+                    },
+                    React.createElement('span', null, '❓'),
+                    React.createElement('span', null, t('operatorInputRequired') || 'Operator Input Required')
+                  ),
+                  React.createElement(
+                    'div',
+                    {
+                      style: {
+                        fontSize: 13,
+                        fontWeight: 500,
+                        color: 'var(--dsw-alias-label-primary)',
+                        marginBottom: 8,
+                        wordBreak: 'break-word',
+                      },
+                    },
+                    state.operatorQuery.question
+                  ),
+                  Array.isArray(state.operatorQuery.options) && state.operatorQuery.options.length > 0
+                    ? React.createElement(
+                        'div',
+                        {
+                          className: 'dsh-goal-operator-options',
+                          style: { display: 'flex', flexWrap: 'wrap', gap: 6, marginBottom: 8 },
+                        },
+                        state.operatorQuery.options.map((opt, idx) =>
+                          React.createElement(
+                            'button',
+                            {
+                              key: idx,
+                              type: 'button',
+                              className: 'dsh-goal-btn',
+                              style: {
+                                fontSize: 12,
+                                padding: '4px 10px',
+                                borderColor: 'var(--dsw-alias-brand-primary)',
+                                color: 'var(--dsw-alias-brand-primary)',
+                              },
+                              onClick: () => handleAction('answer_operator', { answer: opt, optionIndex: idx }),
+                            },
+                            opt
+                          )
+                        )
+                      )
+                    : null,
+                  React.createElement(
+                    'div',
+                    { style: { display: 'flex', gap: 6, alignItems: 'center' } },
+                    React.createElement('input', {
+                      type: 'text',
+                      className: 'dsh-goal-card-input',
+                      style: { flex: 1, fontSize: 12, padding: '4px 8px' },
+                      placeholder: t('answerPlaceholder') || 'Type your answer or select an option above...',
+                      value: operatorAnswerInput,
+                      onChange: (e) => setOperatorAnswerInput(e.target.value),
+                      onKeyDown: (e) => {
+                        if (e.key === 'Enter' && operatorAnswerInput.trim()) {
+                          e.preventDefault();
+                          handleAction('answer_operator', { answer: operatorAnswerInput.trim() });
+                          setOperatorAnswerInput('');
+                        }
+                      },
+                    }),
+                    React.createElement(
+                      'button',
+                      {
+                        type: 'button',
+                        className: 'dsh-goal-btn dsh-goal-btn-primary',
+                        style: { fontSize: 12, padding: '4px 12px', whiteSpace: 'nowrap' },
+                        disabled: !operatorAnswerInput.trim(),
+                        onClick: () => {
+                          if (operatorAnswerInput.trim()) {
+                            handleAction('answer_operator', { answer: operatorAnswerInput.trim() });
+                            setOperatorAnswerInput('');
+                          }
+                        },
+                      },
+                      t('submitAnswer') || 'Submit'
+                    )
+                  )
+                )
+              : null
           ),
 
         ),
@@ -5081,6 +5417,12 @@ window.__ModuleLoader__.load({
         mergeBranch: 'Merge Branch',
         discardBranch: 'Discard Branch',
         retrospectiveTitle: 'Goal Retrospective',
+        operatorInputRequired: 'Operator Input Required',
+        operatorQuestion: 'Question from agent:',
+        submitAnswer: 'Submit',
+        answerPlaceholder: 'Type your answer or select an option above...',
+        quickTplVariablesTitle: 'Parameters:',
+        requiredField: 'Required',
         verificationGate: 'Acceptance gate',
         verificationPassed: 'Verified',
         verificationFailed: 'Gate failed',

package/lib/engine-operator-query.js

@@ -0,0 +1,161 @@
+import { GoalState } from './goal-engine-constants.js';
+import { recordActivity } from './engine-intervention.js';
+
+/**
+ * Ask the human operator a question when encountering ambiguity or critical decisions (#166).
+ * Sets the goal into a waiting/paused state and records the query.
+ *
+ * @param {object} goal
+ * @param {object} query
+ * @param {string} query.question - Question text
+ * @param {string[]} [query.options] - Predefined choices for the operator
+ * @param {boolean} [query.isBlocking=true] - Whether to pause execution until answered
+ * @returns {object} result
+ */
+export function askOperatorQuery(goal, query = {}) {
+  if (!goal) {
+    return { ok: false, error: 'No active goal' };
+  }
+
+  const rawQ = query.question ? String(query.question).trim() : '';
+  if (!rawQ) {
+    return { ok: false, error: 'Question text is required' };
+  }
+
+  const cleanOptions = Array.isArray(query.options)
+    ? query.options.map((o) => String(o).trim()).filter(Boolean)
+    : [];
+
+  const isBlocking = query.isBlocking !== false;
+
+  const queryId = `opq-${Date.now()}-${Math.random().toString(36).slice(2, 6)}`;
+  goal.operatorQuery = {
+    id: queryId,
+    question: rawQ,
+    options: cleanOptions,
+    isBlocking,
+    askedAt: Date.now(),
+    answeredAt: null,
+    answer: null,
+    optionIndex: null,
+    consumed: false,
+  };
+
+  goal.waitingForOperator = true;
+
+  if (isBlocking) {
+    if (!goal.previousStateBeforeOperator) {
+      goal.previousStateBeforeOperator = goal.state || GoalState.RUNNING;
+    }
+    goal.state = GoalState.PAUSED;
+    if (!goal.pausedAt) {
+      goal.pausedAt = Date.now();
+    }
+  }
+
+  recordActivity(goal, {
+    type: 'operator_query',
+    tool: 'goal_ask_operator',
+    status: 'pending',
+    details: `Asked operator: "${rawQ.slice(0, 80)}"`,
+  });
+
+  if (!Array.isArray(goal.logs)) goal.logs = [];
+  goal.logs.push({
+    timestamp: Date.now(),
+    type: 'warning',
+    message: `Goal awaiting operator input: "${rawQ}"`,
+  });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+
+  return { ok: true, queryId, question: rawQ, options: cleanOptions, isBlocking };
+}
+
+/**
+ * Record operator response to a pending query and resume goal execution (#166).
+ *
+ * @param {object} goal
+ * @param {object} payload
+ * @param {string} [payload.answer] - Freeform text answer
+ * @param {number} [payload.optionIndex] - Index of selected choice in options array
+ * @returns {object} result
+ */
+export function answerOperatorQuery(goal, payload = {}) {
+  if (!goal || !goal.operatorQuery || !goal.waitingForOperator) {
+    return { ok: false, error: 'No pending operator query for this goal' };
+  }
+
+  let finalAnswer = typeof payload.answer === 'string' ? payload.answer.trim() : '';
+  const optIdx = typeof payload.optionIndex === 'number' ? payload.optionIndex : null;
+
+  if (optIdx !== null && Array.isArray(goal.operatorQuery.options) && goal.operatorQuery.options[optIdx]) {
+    finalAnswer = goal.operatorQuery.options[optIdx];
+  }
+
+  if (!finalAnswer) {
+    return { ok: false, error: 'Answer or valid option selection is required' };
+  }
+
+  goal.operatorQuery.answeredAt = Date.now();
+  goal.operatorQuery.answer = finalAnswer;
+  goal.operatorQuery.optionIndex = optIdx;
+  goal.operatorQuery.consumed = false;
+  goal.waitingForOperator = false;
+
+  // Unpause if goal was paused for operator
+  if (goal.pausedAt) {
+    const pauseMs = Math.max(0, Date.now() - goal.pausedAt);
+    goal.totalPausedDurationMs = (goal.totalPausedDurationMs || 0) + pauseMs;
+    goal.pausedAt = null;
+  }
+
+  goal.state = goal.previousStateBeforeOperator || GoalState.RUNNING;
+  delete goal.previousStateBeforeOperator;
+
+  recordActivity(goal, {
+    type: 'operator_answer',
+    tool: 'goal_ask_operator',
+    status: 'success',
+    details: `Operator replied: "${finalAnswer.slice(0, 80)}"`,
+  });
+
+  if (!Array.isArray(goal.logs)) goal.logs = [];
+  goal.logs.push({
+    timestamp: Date.now(),
+    type: 'info',
+    message: `Operator answered: "${finalAnswer}"`,
+  });
+  if (goal.logs.length > 100) goal.logs = goal.logs.slice(-100);
+
+  return { ok: true, answer: finalAnswer };
+}
+
+/**
+ * Format prompt injection with operator's answer for the next turn.
+ * Marks the answer as consumed after formatting.
+ *
+ * @param {object} goal
+ * @param {string} [lang='en']
+ * @returns {string} formatted prompt snippet or empty string
+ */
+export function formatOperatorAnswerPrompt(goal, lang = 'en') {
+  if (!goal || !goal.operatorQuery || !goal.operatorQuery.answer || goal.operatorQuery.consumed) {
+    return '';
+  }
+
+  const { question, answer } = goal.operatorQuery;
+  // Mark consumed so it is only injected on the resume turn
+  goal.operatorQuery.consumed = true;
+
+  if (lang === 'zh') {
+    return `\n\n[操作员答复 / OPERATOR RESPONSE]\n` +
+      `你之前提出的问题: "${question}"\n` +
+      `操作员给出的明确指令: "${answer}"\n` +
+      `请严格根据操作员的答复继续推进任务，切勿再对此问题做无谓猜测！\n`;
+  }
+
+  return `\n\n[OPERATOR RESPONSE TO YOUR QUERY]\n` +
+    `Your Question: "${question}"\n` +
+    `Operator Answer: "${answer}"\n` +
+    `Strictly follow the operator's response and proceed with executing the goal without second-guessing!\n`;
+}

package/lib/engine-prompt.js

@@ -9,6 +9,16 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
   const hasMilestones = snapshot.milestones && snapshot.milestones.length > 0;
   const etaText = snapshot.formattedETA ? ` (ETA: ${snapshot.formattedETA})` : '';
 
+  let operatorAnswerText = '';
+  if (snapshot.operatorQuery?.answer && !snapshot.operatorQuery.consumed) {
+    snapshot.operatorQuery.consumed = true;
+    if (lang === 'zh') {
+      operatorAnswerText = `\n\n[操作员答复 / OPERATOR RESPONSE]\n你之前提出的问题: "${snapshot.operatorQuery.question}"\n操作员给出的明确指令: "${snapshot.operatorQuery.answer}"\n请严格根据操作员的答复继续推进任务，切勿再对此问题做无谓猜测！\n`;
+    } else {
+      operatorAnswerText = `\n\n[OPERATOR RESPONSE TO YOUR QUERY]\nYour Question: "${snapshot.operatorQuery.question}"\nOperator Answer: "${snapshot.operatorQuery.answer}"\nStrictly follow the operator's response and proceed with executing the goal without second-guessing!\n`;
+    }
+  }
+
   let directiveText = '';
   if (snapshot.userDirective && !snapshot.userDirectiveConsumed) {
     if (lang === 'zh') {
@@ -67,6 +77,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
       : '  (工作计划尚未建立 — 请立即调用 goal_set_milestones 设定初始里程碑！)';
 
     return (
+      operatorAnswerText +
       directiveText +
       nudgeText +
       budgetWarningText +
@@ -87,6 +98,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     : '  (Work plan is not yet established — call goal_set_milestones immediately with initial steps!)';
 
   return (
+    operatorAnswerText +
     directiveText +
     nudgeText +
     budgetWarningText +

package/lib/engine-templates.js

@@ -1,3 +1,16 @@
+/**
+ * Format template string by replacing {{key}} with provided variable value (#165)
+ * @param {string} templateStr
+ * @param {object} vars
+ * @returns {string}
+ */
+export function formatTemplateVariables(templateStr, vars = {}) {
+  if (!templateStr || typeof templateStr !== "string") return "";
+  return templateStr.replace(/\{\{([a-zA-Z0-9_]+)\}\}/g, (_, key) => {
+    return vars && vars[key] != null && vars[key] !== "" ? String(vars[key]) : "";
+  }).trim();
+}
+
 import { MilestoneStatus } from './goal-engine-constants.js';
 
 /**
@@ -93,8 +106,8 @@ export function instantiateTemplate(templateId, inputValues = {}) {
   const tpl = GOAL_TEMPLATES.find((t) => t.id === templateId);
   if (!tpl) return null;
 
-  let title = tpl.title;
-  let description = tpl.description;
+  let title = tpl.promptTemplate ? formatTemplateVariables(tpl.promptTemplate, inputValues) : tpl.title;
+  let description = tpl.descriptionTemplate ? formatTemplateVariables(tpl.descriptionTemplate, inputValues) : tpl.description;
   if (inputValues.targetFile) {
     title = `Refactor ${inputValues.targetFile}`;
     description = `Decompose ${inputValues.targetFile} to < ${inputValues.lineThreshold || 500} lines`;

package/lib/engine-verification.js

@@ -1,39 +1,209 @@
 import { spawnSync } from 'node:child_process';
 import { getSafeCwd } from './goal-engine-constants.js';
 
+export const SAFE_ENV_WHITELIST = [
+  'PATH',
+  'HOME',
+  'USER',
+  'LOGNAME',
+  'LANG',
+  'LC_ALL',
+  'LC_CTYPE',
+  'SHELL',
+  'TERM',
+  'TMPDIR',
+  'TMP',
+  'TEMP',
+  'NODE_ENV',
+];
+
+const FORBIDDEN_SECRET_REGEX = /(TOKEN|KEY|SECRET|AUTH|PASS|PASSWORD|CREDENTIAL|PRIVATE|BEARER|API)/i;
+
+export const DISALLOWED_BINARIES = new Set([
+  'curl', 'wget', 'nc', 'ncat', 'netcat', 'telnet',
+  'ssh', 'scp', 'sftp', 'ftp', 'rsync',
+  'rm', 'dd', 'mkfs', 'shutdown', 'reboot', 'killall', 'kill',
+]);
+
+export const SHELL_OPERATORS = new Set([';', '&&', '||', '|', '&', '>', '>>', '<', '`']);
+
+/**
+ * Sanitize environment for child verification processes, strictly stripping tokens and secrets
+ * @param {object} [userEnv={}]
+ * @returns {object}
+ */
+export function sanitizeVerificationEnv(userEnv = {}) {
+  const clean = {};
+  for (const key of SAFE_ENV_WHITELIST) {
+    if (process.env[key] !== undefined && !FORBIDDEN_SECRET_REGEX.test(key)) {
+      clean[key] = process.env[key];
+    }
+  }
+  if (userEnv && typeof userEnv === 'object') {
+    for (const [k, v] of Object.entries(userEnv)) {
+      if (k && !FORBIDDEN_SECRET_REGEX.test(k) && v !== undefined && v !== null) {
+        clean[k] = String(v);
+      }
+    }
+  }
+  if (!clean.NODE_ENV) {
+    clean.NODE_ENV = 'test';
+  }
+  return clean;
+}
+
+/**
+ * Parse a command string or array into an argv list
+ * @param {string|string[]} commandStr
+ * @returns {string[]}
+ */
+export function parseCommandArgv(commandStr) {
+  if (Array.isArray(commandStr)) {
+    return commandStr.map(String).filter((s) => s.trim().length > 0);
+  }
+  if (!commandStr || typeof commandStr !== 'string') return [];
+  const trimmed = commandStr.trim();
+  if (!trimmed) return [];
+
+  const regex = /"([^"\\]*(?:\\.[^"\\]*)*)"|'([^'\\]*(?:\\.[^'\\]*)*)'|(\S+)/g;
+  const args = [];
+  let match;
+  while ((match = regex.exec(trimmed)) !== null) {
+    if (match[1] !== undefined) {
+      args.push(match[1].replace(/\\"/g, '"'));
+    } else if (match[2] !== undefined) {
+      args.push(match[2].replace(/\\'/g, "'"));
+    } else if (match[3] !== undefined) {
+      args.push(match[3]);
+    }
+  }
+  return args;
+}
+
+/**
+ * Validate a verification command for dangerous operators, shell chaining, or exfiltration binaries
+ * @param {string|string[]} command
+ * @returns {{ valid: boolean, error?: string, argv?: string[], binary?: string }}
+ */
+export function validateVerificationCommand(command) {
+  if (!command) return { valid: false, error: 'Empty or invalid verification command' };
+  const argv = parseCommandArgv(command);
+  if (argv.length === 0) return { valid: false, error: 'Empty or invalid verification command' };
+
+  const rawBinary = argv[0].toLowerCase().replace(/^.*[/\\]/, '');
+  if (DISALLOWED_BINARIES.has(rawBinary)) {
+    return { valid: false, error: `Execution blocked: disallowed command binary "${rawBinary}"` };
+  }
+
+  for (let i = 0; i < argv.length; i++) {
+    const arg = argv[i];
+    if (SHELL_OPERATORS.has(arg)) {
+      return { valid: false, error: `Execution blocked: shell operator "${arg}" is not allowed` };
+    }
+    if (arg.startsWith('$(') || (arg.startsWith('`') && arg.endsWith('`'))) {
+      return { valid: false, error: 'Execution blocked: subshell substitution is not allowed' };
+    }
+    if (i > 0 && DISALLOWED_BINARIES.has(arg.toLowerCase().replace(/^.*[/\\]/, ''))) {
+      return { valid: false, error: `Execution blocked: disallowed binary "${arg}" in arguments` };
+    }
+  }
+
+  return { valid: true, argv, binary: rawBinary };
+}
+
 /**
  * Execute a verification command in a confined working directory with timeout and output capture
- * @param {string} command Shell command to execute
+ * Uses sanitized environment (no secrets/tokens) and shell: false (no shell injection)
+ * @param {string|string[]} command Command to execute
  * @param {string} [targetCwd] Working directory
  * @param {object} [options]
  * @param {number} [options.timeoutMs=30000] Timeout in milliseconds
  * @param {number} [options.maxBuffer=1048576] Max stdout/stderr buffer in bytes (1MB)
- * @param {object} [options.env={}] Additional environment variables
+ * @param {object} [options.env={}] Additional environment variables (sanitized)
+ * @param {Function} [options.checkApproval] Custom approval check function
+ * @param {object} [options.approvalGate] ApprovalGate service instance
  * @returns {{ ok: boolean, exitCode: number, stdout: string, stderr: string, error?: string }}
  */
 export function runMilestoneVerification(command, targetCwd, options = {}) {
-  if (!command || typeof command !== 'string' || !command.trim()) {
+  const validation = validateVerificationCommand(command);
+  if (!validation.valid) {
     return {
       ok: false,
       exitCode: 1,
       stdout: '',
       stderr: '',
-      error: 'Empty or invalid verification command',
+      error: validation.error || 'Empty or invalid verification command',
     };
   }
 
   const safeCwd = getSafeCwd(targetCwd) || process.cwd();
   const timeoutMs = typeof options.timeoutMs === 'number' ? options.timeoutMs : 30000;
   const maxBuffer = typeof options.maxBuffer === 'number' ? options.maxBuffer : 1024 * 1024;
+  const { argv, binary } = validation;
+
+  // 1. Approval seam check
+  if (typeof options.checkApproval === 'function') {
+    const decision = options.checkApproval({
+      command,
+      argv,
+      binary,
+      cwd: safeCwd,
+    });
+    if (decision && (decision.kind === 'deny' || decision.deny)) {
+      return {
+        ok: false,
+        exitCode: 1,
+        stdout: '',
+        stderr: '',
+        error: `Verification command denied by policy: ${decision.reason || 'denied'}`,
+      };
+    }
+    if (decision && (decision.kind === 'ask' || decision.ask)) {
+      return {
+        ok: false,
+        exitCode: 1,
+        stdout: '',
+        stderr: '',
+        error: `Verification command requires operator approval: ${decision.reason || 'approval required'}`,
+      };
+    }
+  }
+
+  if (options.approvalGate && typeof options.approvalGate.checkCommand === 'function') {
+    try {
+      const decision = options.approvalGate.checkCommand(command, safeCwd);
+      if (decision && (decision.verdict === 'deny' || decision.verdict === 'ask')) {
+        return {
+          ok: false,
+          exitCode: 1,
+          stdout: '',
+          stderr: '',
+          error: `Verification command blocked by approval gate: ${decision.reason || decision.verdict}`,
+        };
+      }
+    } catch (err) {
+      return {
+        ok: false,
+        exitCode: 1,
+        stdout: '',
+        stderr: '',
+        error: `Approval check error: ${err?.message || err}`,
+      };
+    }
+  }
+
+  // 2. Environment sanitization (strictly scrub secrets and tokens)
+  const cleanEnv = sanitizeVerificationEnv(options.env);
 
+  // 3. Execution without shell (shell: false)
   try {
-    const res = spawnSync(command.trim(), {
-      shell: true,
+    const res = spawnSync(argv[0], argv.slice(1), {
+      shell: false,
       cwd: safeCwd,
       timeout: timeoutMs,
       maxBuffer,
       encoding: 'utf8',
-      env: { ...process.env, ...options.env },
+      env: cleanEnv,
     });
 
     if (res.error) {

package/lib/goal-engine-constants.js

@@ -192,6 +192,8 @@ export function buildSnapshot(goal, sid, engine) {
       enableMilestoneDependencies: engine.enableMilestoneDependencies ?? true,
       soundScheme: engine.soundScheme ?? 'default',
       enableVoiceAnnouncements: engine.enableVoiceAnnouncements ?? false,
+      operatorQuery: null,
+      waitingForOperator: false,
     };
   }
 
@@ -251,6 +253,8 @@ export function buildSnapshot(goal, sid, engine) {
     enableMilestoneDependencies: engine.enableMilestoneDependencies ?? true,
     soundScheme: engine.soundScheme ?? 'default',
     enableVoiceAnnouncements: engine.enableVoiceAnnouncements ?? false,
+    operatorQuery: goal.operatorQuery || null,
+    waitingForOperator: Boolean(goal.waitingForOperator),
   };
 }
 

package/lib/goal-engine.js

@@ -1,4 +1,5 @@
 import { verifyMilestoneAcceptance } from './engine-verification.js';
+import { askOperatorQuery, answerOperatorQuery } from './engine-operator-query.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';
@@ -11,8 +12,7 @@ import { generateRetrospectiveData } from './engine-retrospective.js';
 import { generatePreplanDraft } from './engine-templates.js';
 import { pruneInactiveSessions, addNudgeToGoal, consumeGoalNudge, extendGoalBudget, setGoalMode, pauseGoal, resumeGoal, cancelGoal } from './engine-sessions.js';
 
-export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist };
-export { getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
+export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist, getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
 
 /**
  * Isolated Goal Management Engine for DeepSeek Harness
@@ -22,23 +22,19 @@ export class GoalEngine {
     this.logger = options.logger || console;
     const rawDefIters = options.defaultMaxIterations ?? 25;
     this.defaultMaxIterations = typeof rawDefIters === "number" ? rawDefIters : (typeof rawDefIters?.value === "number" ? rawDefIters.value : 25);
-    this.autoDrive = options.autoDrive ?? true;
-    this.enableSound = options.enableSound ?? true;
-    this.showQuickLaunchButton = options.showQuickLaunchButton ?? true;
-    this.consecutiveToolFailureLimit = options.consecutiveToolFailureLimit ?? 3;
-    this.maxTokenBudget = options.maxTokenBudget ?? 0;
-    this.budgetWarningThreshold = options.budgetWarningThreshold ?? 80;
-    this.autoCheckpointOnMilestone = options.autoCheckpointOnMilestone ?? false;
-    this.enableLiveActivityFeed = options.enableLiveActivityFeed ?? true;
-    this.enablePreplanning = options.enablePreplanning ?? true;
-    this.autoBranchOnGoalStart = options.autoBranchOnGoalStart ?? true;
-    this.enablePostGoalRetrospective = options.enablePostGoalRetrospective ?? true;
-    this.autoScaleBudgetNearCompletion = options.autoScaleBudgetNearCompletion ?? false;
-    this.enableTemplatesDrawer = options.enableTemplatesDrawer ?? true;
-    this.enableMilestoneDependencies = options.enableMilestoneDependencies ?? true;
-    this.soundScheme = options.soundScheme ?? 'default';
-    this.enableVoiceAnnouncements = options.enableVoiceAnnouncements ?? false;
-    this.maxSessions = options.maxSessions ?? 100;
+    Object.assign(this, {
+      autoDrive: options.autoDrive ?? true, enableSound: options.enableSound ?? true,
+      showQuickLaunchButton: options.showQuickLaunchButton ?? true,
+      consecutiveToolFailureLimit: options.consecutiveToolFailureLimit ?? 3,
+      maxTokenBudget: options.maxTokenBudget ?? 0, budgetWarningThreshold: options.budgetWarningThreshold ?? 80,
+      autoCheckpointOnMilestone: options.autoCheckpointOnMilestone ?? false,
+      enableLiveActivityFeed: options.enableLiveActivityFeed ?? true, enablePreplanning: options.enablePreplanning ?? true,
+      autoBranchOnGoalStart: options.autoBranchOnGoalStart ?? true, enablePostGoalRetrospective: options.enablePostGoalRetrospective ?? true,
+      autoScaleBudgetNearCompletion: options.autoScaleBudgetNearCompletion ?? false, enableTemplatesDrawer: options.enableTemplatesDrawer ?? true,
+      enableMilestoneDependencies: options.enableMilestoneDependencies ?? true, soundScheme: options.soundScheme ?? 'default',
+      enableVoiceAnnouncements: options.enableVoiceAnnouncements ?? false, approvalGate: options.approvalGate || null,
+      checkApproval: options.checkApproval || null, maxSessions: options.maxSessions ?? 100,
+    });
     this.goals = new Map();
     this.listeners = new Set();
     this.stallCounters = new Map();
@@ -52,10 +48,7 @@ export class GoalEngine {
   set storagePath(val) { this.store.setStoragePath(val); }
   get saveTimer() { return this.store.saveTimer; }
   get currentGoal() { return this.goals.get('default') || null; }
-  set currentGoal(val) {
-    if (val) this.goals.set('default', val);
-    else this.goals.delete('default');
-  }
+  set currentGoal(val) { if (val) this.goals.set('default', val); else this.goals.delete('default'); }
 
   loadStateFromDisk() { this.store.loadStateFromDisk(); }
   scheduleSave(immediate = false) { this.store.scheduleSave(immediate); }
@@ -109,22 +102,12 @@ export class GoalEngine {
         }
       }
     }
-    if (typeof config.autoDrive === 'boolean') this.autoDrive = config.autoDrive;
-    if (typeof config.enableSound === 'boolean') this.enableSound = config.enableSound;
-    if (typeof config.showQuickLaunchButton === 'boolean') this.showQuickLaunchButton = config.showQuickLaunchButton;
+    const boolKeys = ['autoDrive', 'enableSound', 'showQuickLaunchButton', 'autoCheckpointOnMilestone', 'enableLiveActivityFeed', 'enablePreplanning', 'autoBranchOnGoalStart', 'enablePostGoalRetrospective', 'autoScaleBudgetNearCompletion', 'enableTemplatesDrawer', 'enableMilestoneDependencies', 'enableVoiceAnnouncements'];
+    for (const k of boolKeys) if (typeof config[k] === 'boolean') this[k] = config[k];
     if (typeof config.consecutiveToolFailureLimit === 'number') this.consecutiveToolFailureLimit = Math.max(0, config.consecutiveToolFailureLimit);
     if (typeof config.maxTokenBudget === 'number') this.maxTokenBudget = Math.max(0, config.maxTokenBudget);
     if (typeof config.budgetWarningThreshold === 'number') this.budgetWarningThreshold = Math.max(1, Math.min(100, config.budgetWarningThreshold));
-    if (typeof config.autoCheckpointOnMilestone === 'boolean') this.autoCheckpointOnMilestone = config.autoCheckpointOnMilestone;
-    if (typeof config.enableLiveActivityFeed === 'boolean') this.enableLiveActivityFeed = config.enableLiveActivityFeed;
-    if (typeof config.enablePreplanning === 'boolean') this.enablePreplanning = config.enablePreplanning;
-    if (typeof config.autoBranchOnGoalStart === 'boolean') this.autoBranchOnGoalStart = config.autoBranchOnGoalStart;
-    if (typeof config.enablePostGoalRetrospective === 'boolean') this.enablePostGoalRetrospective = config.enablePostGoalRetrospective;
-    if (typeof config.autoScaleBudgetNearCompletion === 'boolean') this.autoScaleBudgetNearCompletion = config.autoScaleBudgetNearCompletion;
-    if (typeof config.enableTemplatesDrawer === 'boolean') this.enableTemplatesDrawer = config.enableTemplatesDrawer;
-    if (typeof config.enableMilestoneDependencies === 'boolean') this.enableMilestoneDependencies = config.enableMilestoneDependencies;
     if (typeof config.soundScheme === 'string') this.soundScheme = config.soundScheme;
-    if (typeof config.enableVoiceAnnouncements === 'boolean') this.enableVoiceAnnouncements = config.enableVoiceAnnouncements;
     this.emit();
   }
 
@@ -138,14 +121,8 @@ export class GoalEngine {
     this.toolFailureCounters.set(sid, next);
     return next;
   }
-
-  resetToolFailureCount(sessionId = 'default') {
-    this.toolFailureCounters.set(sessionId || 'default', 0);
-  }
-
-  getToolFailureCount(sessionId = 'default') {
-    return this.toolFailureCounters.get(sessionId || 'default') || 0;
-  }
+  resetToolFailureCount(sessionId = 'default') { this.toolFailureCounters.set(sessionId || 'default', 0); }
+  getToolFailureCount(sessionId = 'default') { return this.toolFailureCounters.get(sessionId || 'default') || 0; }
 
   nudge(text, sessionId = 'default') {
     const sid = sessionId || 'default';
@@ -227,6 +204,8 @@ export class GoalEngine {
       preplan: null,
       retrospective: null,
       issueRef: parseIssueRef(cleanTitle),
+      operatorQuery: null,
+      waitingForOperator: false,
       tokensUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
       logs: [{
         timestamp: now,
@@ -359,7 +338,7 @@ export class GoalEngine {
     if (!target) return false;
 
     if (status === MilestoneStatus.COMPLETED && target.verificationCommand) {
-      const vRes = verifyMilestoneAcceptance(target, goal.cwd || process.cwd(), goal, recordActivity);
+      const vRes = verifyMilestoneAcceptance(target, goal.cwd || process.cwd(), goal, recordActivity, { approvalGate: this.approvalGate, checkApproval: this.checkApproval });
       if (!vRes.ok) {
         this.emit(sid);
         return false;
@@ -582,6 +561,24 @@ export class GoalEngine {
     return this.goals.get(sessionId || 'default') || null;
   }
 
+  askOperator(query = {}, sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal) return { ok: false, error: 'Goal not found' };
+    const res = askOperatorQuery(goal, query);
+    this.emit(sid, true);
+    return res;
+  }
+
+  answerOperator(payload = {}, sessionId = 'default') {
+    const sid = sessionId || 'default';
+    const goal = this.goals.get(sid);
+    if (!goal) return { ok: false, error: 'Goal not found' };
+    const res = answerOperatorQuery(goal, payload);
+    this.emit(sid, true);
+    return res;
+  }
+
   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

@@ -121,6 +121,7 @@ export function apply(ctx, config = {}) {
   const milestoneManager = new MilestoneManager(addonStore, {
     gitSnapshotManager,
     enforceDependencies: currentSettings.enableMilestoneDependencies,
+    approvalGate: safeService(ctx, "approvalGate"),
     logger,
   });
   const tokenBudgetGuard = new TokenBudgetGuard({
@@ -167,6 +168,7 @@ export function apply(ctx, config = {}) {
       autoScaleBudgetNearCompletion: currentSettings.autoScaleBudgetNearCompletion,
       enableTemplatesDrawer: currentSettings.enableTemplatesDrawer,
       enableMilestoneDependencies: currentSettings.enableMilestoneDependencies,
+      approvalGate: safeService(ctx, "approvalGate"),
       logger,
     });
     registerPlanModeGuard(ctx, { engine: fallbackEngine, logger });

package/lib/milestone-manager.js

@@ -1,14 +1,16 @@
 import { syncMilestoneWithIssue } from './engine-issue-sync.js';
-import { runMilestoneVerification } from './engine-verification.js';
+import { runMilestoneVerification, validateVerificationCommand } from './engine-verification.js';
 
 /**
  * Milestone and checklist coordinator for active core goals
  */
 export class MilestoneManager {
-  constructor(addonStore, { gitSnapshotManager = null, enforceDependencies = true, logger = console } = {}) {
+  constructor(addonStore, { gitSnapshotManager = null, enforceDependencies = true, approvalGate = null, checkApproval = null, logger = console } = {}) {
     this.store = addonStore;
     this.gitSnapshotManager = gitSnapshotManager;
     this.enforceDependencies = enforceDependencies;
+    this.approvalGate = approvalGate;
+    this.checkApproval = checkApproval;
     this.logger = logger;
   }
 
@@ -80,7 +82,10 @@ export class MilestoneManager {
 
     // Acceptance Gate (Critic Verification) - Issue #163
     if (m.verificationCommand) {
-      const vResult = runMilestoneVerification(m.verificationCommand, workspaceRoot);
+      const vResult = runMilestoneVerification(m.verificationCommand, workspaceRoot, {
+        approvalGate: this.approvalGate,
+        checkApproval: this.checkApproval,
+      });
       if (!vResult.ok) {
         m.verificationError = vResult.error;
         m.verificationOutput = (vResult.stderr || vResult.stdout || '').trim();

package/lib/routes.js

@@ -750,6 +750,30 @@ export function registerRoutes(ctx, {
                   break;
                 }
 
+                case 'answer_operator': {
+                  const answer = typeof data.answer === 'string' ? data.answer.trim() : '';
+                  const optionIndex = typeof data.optionIndex === 'number' ? data.optionIndex : (typeof data.option_index === 'number' ? data.option_index : null);
+                  if (engine && typeof engine.answerOperator === 'function') {
+                    const ansRes = engine.answerOperator({ answer, optionIndex }, sid);
+                    if (!ansRes.ok) {
+                      res.statusCode = 400;
+                      return res.end(JSON.stringify({ error: ansRes.error || 'Failed to submit operator answer' }));
+                    }
+                    result = { ok: true, answer: ansRes.answer, state: engine.getSnapshot(sid) };
+                    const snap = engine.getSnapshot(sid);
+                    const detectedLang = snap?.lang || 'en';
+                    const prompt = detectedLang === 'zh'
+                      ? `✅ 操作员已答复你的提问: "${ansRes.answer}"。请继续执行任务。`
+                      : `✅ Operator answered your query: "${ansRes.answer}". Proceed with task execution.`;
+                    if (typeof resumeActiveAgent === 'function') {
+                      resumeActiveAgent(prompt, sid);
+                    }
+                  } else {
+                    result = { ok: true, answer };
+                  }
+                  break;
+                }
+
                 case 'approve_plan': {
                   if (engine) {
                     const snap = engine.getSnapshot(sid);

package/lib/tools.js

@@ -1,3 +1,4 @@
+import { validateVerificationCommand } from './engine-verification.js';
 import { MilestoneManager } from './milestone-manager.js';
 import { AddonStore } from './addon-store.js';
 import { getSafeCwd } from './goal-engine-constants.js';
@@ -67,16 +68,30 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
       }
 
       if (action === 'set') {
+        if (Array.isArray(args.milestones)) {
+          for (const m of args.milestones) {
+            const vCmd = m && (m.verificationCommand || m.verification_command);
+            if (vCmd) {
+              const val = validateVerificationCommand(vCmd);
+              if (!val.valid) throw new Error(`Invalid verificationCommand: ${val.error}`);
+            }
+          }
+        }
         const list = mm.setMilestones(goalId, args.milestones);
         return { ok: true, goalId, count: list.length, milestones: list };
       }
 
       if (action === 'add') {
+        const vCmd = args.verificationCommand || args.verification_command;
+        if (vCmd) {
+          const val = validateVerificationCommand(vCmd);
+          if (!val.valid) throw new Error(`Invalid verificationCommand: ${val.error}`);
+        }
         const item = mm.addMilestone(goalId, {
           title: args.title,
           checklist: args.checklist,
           dependsOn: args.dependsOn || args.depends_on,
-          verificationCommand: args.verificationCommand || args.verification_command,
+          verificationCommand: vCmd,
         });
         return { ok: true, goalId, milestone: item };
       }
@@ -196,6 +211,11 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
           if (typeof item === 'string') {
             return { id: `m-${idx + 1}`, title: item };
           }
+          const vCmd = item && (item.verificationCommand || item.verification_command);
+          if (vCmd) {
+            const val = validateVerificationCommand(vCmd);
+            if (!val.valid) throw new Error(`Invalid verificationCommand: ${val.error}`);
+          }
           return item;
         });
       } else {
@@ -230,6 +250,11 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
       const status = args.status || 'in_progress';
       const notes = typeof args.notes === 'string' ? args.notes : '';
       if (!milestoneId) throw new Error('milestone_id is required');
+      const vCmd = args.verificationCommand || args.verification_command;
+      if (vCmd) {
+        const val = validateVerificationCommand(vCmd);
+        if (!val.valid) throw new Error(`Invalid verificationCommand: ${val.error}`);
+      }
       if (status === 'completed') {
         const rawCwd = toolCtx?.session?.cwd || toolCtx?.cwd || process.cwd();
         const safeCwd = getSafeCwd(rawCwd);
@@ -286,5 +311,70 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
       output: JSON_OUTPUT,
       execute: handleGoalFinish,
     });
+
+    // Tool 6: goal_ask_operator (#166)
+    const handleGoalAskOperator = async (args = {}, toolCtx = {}) => {
+      const goalId = args.goalId || args.goal_id || resolveGoalId(toolCtx);
+      const question = args.question || args.prompt;
+      if (!question || typeof question !== 'string' || !question.trim()) {
+        throw new Error('Field "question" is required and must be a non-empty string');
+      }
+
+      const options = Array.isArray(args.options) ? args.options : [];
+      const isBlocking = args.isBlocking !== false && args.is_blocking !== false;
+
+      const engine = ctx.goalEngine || (ctx.get && ctx.get('goalEngine'));
+      if (engine && typeof engine.askOperator === 'function') {
+        const res = engine.askOperator({ question, options, isBlocking }, goalId);
+        if (!res.ok) {
+          throw new Error(`Failed to present question to operator: ${res.error}`);
+        }
+        return {
+          ok: true,
+          goalId,
+          queryId: res.queryId,
+          question: res.question,
+          options: res.options,
+          isBlocking: res.isBlocking,
+          message: isBlocking
+            ? 'Question submitted to human operator. Goal is paused awaiting operator input.'
+            : 'Question submitted to human operator in non-blocking mode.',
+        };
+      }
+
+      return {
+        ok: true,
+        goalId,
+        question,
+        options,
+        message: 'Question logged.',
+      };
+    };
+
+    safeRegister({
+      name: 'goal_ask_operator',
+      description: 'Ask the human operator a clarification question or present architectural choices when encountering blockers (#166). Pauses autonomous execution without consuming iterations until the operator responds.',
+      parameters: {
+        type: 'object',
+        properties: {
+          question: {
+            type: 'string',
+            description: 'The clarification question, design decision, or blocker to ask the human operator',
+          },
+          options: {
+            type: 'array',
+            items: { type: 'string' },
+            description: 'Optional list of predefined choices or alternative options for the operator to select with one click',
+          },
+          is_blocking: {
+            type: 'boolean',
+            description: 'Whether to pause goal execution awaiting operator response (default: true)',
+          },
+        },
+        required: ['question'],
+      },
+      output: JSON_OUTPUT,
+      execute: handleGoalAskOperator,
+    });
   });
 }

package/package.json

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