@goodandready/dsh-goal 0.2.31 → 0.2.32

package/lib/client.js

@@ -1930,6 +1930,77 @@ window.__ModuleLoader__.load({
         color: var(--dsw-alias-label-secondary);
         font-size: 13px;
       }
+      /* Sub-goals and Compaction (Issue 167 and Issue 170) */
+      .dsh-goal-badge-subgoal {
+        background: var(--dsw-alias-brand-bg, var(--dsw-alias-bg-hover));
+        color: var(--dsw-alias-brand-primary, var(--dsw-alias-text-primary));
+        border: 1px solid var(--dsw-alias-brand-border, var(--dsw-alias-border));
+      }
+      .dsh-goal-breadcrumbs {
+        display: inline-flex;
+        align-items: center;
+        gap: 4px;
+        font-size: 13px;
+        color: var(--dsw-alias-label-secondary);
+      }
+      .dsh-goal-breadcrumb-item {
+        color: var(--dsw-alias-label-secondary);
+      }
+      .dsh-goal-breadcrumb-item.active {
+        color: var(--dsw-alias-text-primary);
+        font-weight: 600;
+      }
+      .dsh-goal-crumb-sep {
+        color: var(--dsw-alias-label-tertiary);
+        margin: 0 2px;
+      }
+      .dsh-goal-subgoals-box {
+        display: flex;
+        flex-direction: column;
+        gap: 10px;
+        padding: 4px 0;
+      }
+      .dsh-goal-subgoals-list {
+        display: flex;
+        flex-direction: column;
+        gap: 8px;
+      }
+      .dsh-goal-subgoal-card {
+        background: var(--dsw-alias-bg-layer-2, var(--dsw-alias-bg-hover));
+        border: 1px solid var(--dsw-alias-border);
+        border-radius: 6px;
+        padding: 10px 12px;
+        display: flex;
+        flex-direction: column;
+        gap: 4px;
+      }
+      .dsh-goal-subgoal-header {
+        display: flex;
+        align-items: center;
+        justify-content: space-between;
+        gap: 8px;
+      }
+      .dsh-goal-subgoal-title {
+        font-weight: 600;
+        font-size: 13px;
+        color: var(--dsw-alias-text-primary);
+      }
+      .dsh-goal-subgoal-summary {
+        font-size: 12px;
+        color: var(--dsw-alias-label-secondary);
+      }
+      .dsh-goal-compacted-pill {
+        display: inline-flex;
+        align-items: center;
+        gap: 3px;
+        font-size: 10px;
+        padding: 1px 5px;
+        border-radius: 3px;
+        background: var(--dsw-alias-bg-layer-2, var(--dsw-alias-bg-hover));
+        color: var(--dsw-alias-state-success-primary, var(--dsw-alias-text-secondary));
+        border: 1px solid var(--dsw-alias-border);
+        margin-left: 6px;
+      }
     `;
     function injectStylesOnce() {
 
@@ -2364,6 +2435,53 @@ window.__ModuleLoader__.load({
         );
       };
 
+      const renderSubGoalsBox = () => {
+        const subList = Array.isArray(state.subGoals) ? state.subGoals : [];
+        return React.createElement(
+          'div',
+          { className: 'dsh-goal-subgoals-box' },
+          state.isSubGoal
+            ? React.createElement(
+                'div',
+                { className: 'dsh-goal-subgoal-card', style: { borderStyle: 'dashed' } },
+                React.createElement('div', { style: { fontSize: 11, color: 'var(--dsw-alias-brand-primary)', fontWeight: 600 } }, '🌱 ' + (t('parentGoalBanner') || 'Child Sub-goal of:')),
+                React.createElement('div', { style: { fontSize: 12, color: 'var(--dsw-alias-label-secondary)' } }, state.parentGoalId || 'Parent Goal')
+              )
+            : null,
+          subList.length === 0
+            ? React.createElement('div', { className: 'dsh-goal-diff-empty' }, t('noSubGoals') || 'No sub-goals spawned yet.')
+            : React.createElement(
+                'div',
+                { className: 'dsh-goal-subgoals-list' },
+                subList.map((sub, idx) =>
+                  React.createElement(
+                    'div',
+                    { key: sub.id || sub.subGoalId || idx, className: 'dsh-goal-subgoal-card' },
+                    React.createElement(
+                      'div',
+                      { className: 'dsh-goal-subgoal-header' },
+                      React.createElement('span', { className: 'dsh-goal-subgoal-title' }, sub.title),
+                      React.createElement(
+                        'span',
+                        {
+                          className: 'dsh-goal-badge ' + (sub.state === 'COMPLETED' ? 'dsh-goal-badge-ok' : sub.state === 'RUNNING' ? 'dsh-goal-badge-plan' : ''),
+                        },
+                        sub.state || 'PENDING'
+                      )
+                    ),
+                    sub.resultSummary
+                      ? React.createElement(
+                          'div',
+                          { className: 'dsh-goal-subgoal-summary' },
+                          sub.resultSummary
+                        )
+                      : null
+                  )
+                )
+              )
+        );
+      };
+
       const totalTokens = state.tokensUsage?.totalTokens || 0;
 
       const promptTokens = state.tokensUsage?.promptTokens || 0;
@@ -2502,11 +2620,22 @@ window.__ModuleLoader__.load({
                   onClick: () => setActiveTab("diff"),
                 },
                 "🔍 " + (t("tabDiff") || "Changes / Diff") + (diffData && diffData.stats && diffData.stats.filesChanged ? ` (${diffData.stats.filesChanged})` : "")
+              ),
+              React.createElement(
+                'button',
+                {
+                  type: 'button',
+                  className: `dsh-goal-tab-btn${activeTab === "subgoals" ? " active" : ""}`,
+                  onClick: () => setActiveTab("subgoals"),
+                },
+                "🌳 " + (t("tabSubGoals") || "Sub-goals") + (state.subGoals && state.subGoals.length > 0 ? ` (${state.subGoals.length})` : "")
               )
             ),
 
             activeTab === 'diff'
               ? renderDiffBox()
+              : activeTab === 'subgoals'
+              ? renderSubGoalsBox()
               : React.createElement(
                   React.Fragment,
                   null,
@@ -2835,6 +2964,13 @@ window.__ModuleLoader__.load({
                           },
 
                           `${i + 1}. ${m.title}`,
+                          m.compactionSummary
+                            ? React.createElement(
+                                'span',
+                                { className: 'dsh-goal-compacted-pill', title: m.compactionSummary },
+                                '⚡ ' + (t('compactedBadge') || 'Compacted')
+                              )
+                            : null,
                           m.verificationCommand
                             ? React.createElement(
                                 'span',
@@ -4357,7 +4493,28 @@ window.__ModuleLoader__.load({
 
               ),
 
-              React.createElement('span', { className: 'dsh-goal-title', title: state.title }, state.title),
+              state.isSubGoal
+                ? React.createElement(
+                    'span',
+                    { className: 'dsh-goal-badge dsh-goal-badge-subgoal', title: t('subGoalBadge') || 'Sub-goal' },
+                    '🌱 ' + (t('subGoalBadge') || 'Sub-goal')
+                  )
+                : null,
+
+              state.breadcrumbs && state.breadcrumbs.length > 1
+                ? React.createElement(
+                    'span',
+                    { className: 'dsh-goal-breadcrumbs', title: state.title },
+                    state.breadcrumbs.map((crumb, idx) =>
+                      React.createElement(
+                        'span',
+                        { key: crumb.sessionId || idx, className: 'dsh-goal-breadcrumb-item' + (crumb.isCurrent ? ' active' : '') },
+                        idx > 0 && React.createElement('span', { className: 'dsh-goal-crumb-sep' }, ' / '),
+                        crumb.title
+                      )
+                    )
+                  )
+                : React.createElement('span', { className: 'dsh-goal-title', title: state.title }, state.title),
 
             ),
 
@@ -4367,6 +4524,19 @@ window.__ModuleLoader__.load({
 
               { className: 'dsh-goal-right' },
 
+              state.subGoals && state.subGoals.length > 0
+                ? React.createElement(
+                    'span',
+                    {
+                      className: 'dsh-goal-stat-pill',
+                      style: { cursor: 'pointer' },
+                      title: t('subGoalsTitle') || 'Sub-goals',
+                      onClick: () => setIsModalOpen(true),
+                    },
+                    '🌿 ' + state.subGoals.filter((s) => s.state === 'COMPLETED').length + '/' + state.subGoals.length + ' ' + (t('subGoalsPill') || 'sub-goals')
+                  )
+                : null,
+
               React.createElement(
 
                 'span',
@@ -5835,6 +6005,14 @@ window.__ModuleLoader__.load({
         allFiles: 'All Files',
         planModeDesc: 'Plan first, review milestones, then execute',
         actModeDesc: 'Direct execution right away',
+        tabSubGoals: 'Sub-goals',
+        subGoalsTitle: 'Hierarchical Sub-goals',
+        subGoalBadge: 'Sub-goal',
+        subGoalsPill: 'sub-goals',
+        noSubGoals: 'No sub-goals spawned yet. Model can spawn sub-goals via goal_spawn_subgoal tool.',
+        parentGoalBanner: 'Child Sub-goal of:',
+        compactedBadge: 'Compacted',
+        compactionTooltip: 'History compacted to reduce context footprint',
 
       },
 
@@ -5997,6 +6175,14 @@ window.__ModuleLoader__.load({
         allFiles: '所有文件',
         planModeDesc: '先制定里程碑方案，人工确认后再执行',
         actModeDesc: '立即开始编码与任务执行',
+        tabSubGoals: '子目标',
+        subGoalsTitle: '分层子目标管理',
+        subGoalBadge: '子目标',
+        subGoalsPill: '个子目标',
+        noSubGoals: '当前任务暂无衍生子目标。模型可通过 goal_spawn_subgoal 工具动态创建独立子目标。',
+        parentGoalBanner: '衍生自主目标:',
+        compactedBadge: '已压缩',
+        compactionTooltip: '阶段历史已自动精简压缩以优化上下文窗口',
 
       },
 

package/lib/engine-compaction.js

@@ -0,0 +1,126 @@
+/**
+ * Milestone Context Compaction for DSH Goal Engine (Issue #167).
+ * Compresses verbose raw logs and full checklist traces of completed milestones
+ * into high-density summaries, cutting context token footprint by > 40%.
+ */
+
+/**
+ * Compact a single milestone upon completion into a structured summary
+ * @param {object} milestone
+ * @param {object} [options]
+ * @returns {object}
+ */
+export function compactMilestone(milestone, options = {}) {
+  if (!milestone) return null;
+
+  const id = milestone.id ? String(milestone.id).toUpperCase() : 'M';
+  const title = milestone.title || 'Milestone';
+  const notes = milestone.notes ? String(milestone.notes).trim() : '';
+
+  let checklistPart = '';
+  if (Array.isArray(milestone.checklist) && milestone.checklist.length > 0) {
+    const doneCount = milestone.checklist.filter((item) => item && item.done).length;
+    checklistPart = ` [${doneCount}/${milestone.checklist.length} subtasks]`;
+  }
+
+  let gatePart = '';
+  if (milestone.verificationCommand) {
+    gatePart = milestone.verificationPassed ? ' [Gate: verified]' : ' [Gate: passed]';
+  }
+
+  const outcomePart = notes ? ` (Outcome: ${notes})` : '';
+  const summaryLine = `[${id} COMPLETED] ${title}${outcomePart}${checklistPart}${gatePart}`;
+
+  milestone.compactionSummary = summaryLine;
+  milestone.compactedAt = milestone.completedAt || Date.now();
+
+  return {
+    id: milestone.id,
+    title,
+    notes,
+    summary: summaryLine,
+    completedAt: milestone.compactedAt,
+  };
+}
+
+/**
+ * Build compacted milestones history block for active prompt injection
+ * @param {Array<object>} milestones
+ * @param {string} [lang='en']
+ * @returns {string}
+ */
+export function buildCompactedMilestonesHistory(milestones = [], lang = 'en') {
+  if (!Array.isArray(milestones) || milestones.length === 0) return '';
+
+  const completed = milestones.filter((m) => m && m.status === 'completed');
+  if (completed.length === 0) return '';
+
+  const header = lang === 'zh'
+    ? '[已完成里程碑历史简报 / COMPACTED MILESTONES HISTORY]'
+    : '[COMPACTED MILESTONES HISTORY]';
+
+  const lines = completed.map((m) => {
+    if (m.compactionSummary) return `- ${m.compactionSummary}`;
+    const id = m.id ? String(m.id).toUpperCase() : 'M';
+    const outcome = m.notes ? ` (Outcome: ${m.notes})` : '';
+    return `- [${id} COMPLETED] ${m.title}${outcome}`;
+  });
+
+  return `${header}\n${lines.join('\n')}`;
+}
+
+/**
+ * Format milestone into raw uncompacted text (for baseline comparison & active milestones)
+ * @param {object} m
+ * @param {number} idx
+ * @returns {string}
+ */
+export function formatRawMilestoneTrace(m, idx = 0) {
+  if (!m) return '';
+  const statusStr = (m.status || 'pending').toUpperCase();
+  let line = `  ${idx + 1}. [${statusStr}] ${m.title || ''}${m.notes ? ` (${m.notes})` : ''}`;
+  if (m.verificationCommand) {
+    line += `\n      [verification_command: ${m.verificationCommand}]`;
+  }
+  if (Array.isArray(m.checklist) && m.checklist.length > 0) {
+    const checkLines = m.checklist
+      .map((item) => `      [${item && item.done ? 'x' : ' '}] ${item && item.text ? item.text : ''}`)
+      .join('\n');
+    line += `\n${checkLines}`;
+  }
+  return line;
+}
+
+/**
+ * Estimate context savings achieved by compaction on completed milestones
+ * @param {Array<object>} milestones
+ * @param {string} [lang='en']
+ * @returns {{ completedCount: number, uncompactedChars: number, compactedChars: number, savedChars: number, savingsRatio: number, savingsPercent: string }}
+ */
+export function estimateCompactionSavings(milestones = [], lang = 'en') {
+  if (!Array.isArray(milestones) || milestones.length === 0) {
+    return { completedCount: 0, uncompactedChars: 0, compactedChars: 0, savedChars: 0, savingsRatio: 0, savingsPercent: '0%' };
+  }
+
+  const completed = milestones.filter((m) => m && m.status === 'completed');
+  if (completed.length === 0) {
+    return { completedCount: 0, uncompactedChars: 0, compactedChars: 0, savedChars: 0, savingsRatio: 0, savingsPercent: '0%' };
+  }
+
+  const uncompacted = completed.map((m, i) => formatRawMilestoneTrace(m, i)).join('\n');
+  const compacted = completed.map((m) => m.compactionSummary || `[${m.id ? String(m.id).toUpperCase() : 'M'} COMPLETED] ${m.title}`).join('\n');
+
+  const uncompactedChars = uncompacted.length;
+  const compactedChars = compacted.length;
+  const savedChars = Math.max(0, uncompactedChars - compactedChars);
+  const savingsRatio = uncompactedChars > 0 ? (savedChars / uncompactedChars) : 0;
+
+  return {
+    completedCount: completed.length,
+    uncompactedChars,
+    compactedChars,
+    savedChars,
+    savingsRatio,
+    savingsPercent: `${Math.round(savingsRatio * 100)}%`,
+  };
+}

package/lib/engine-prompt.js

@@ -1,5 +1,6 @@
 import { detectLanguage } from "./goal-engine.js";
 import { isMilestoneBlocked } from './engine-milestones.js';
+import { buildCompactedMilestonesHistory } from './engine-compaction.js';
 
 /**
  * Prompt generation for DSH Goal Mode
@@ -55,13 +56,28 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     }
   }
 
+  let subGoalContextText = '';
+  if (snapshot.isSubGoal) {
+    if (lang === 'zh') {
+      subGoalContextText = `\n\n[子目标隔离执行上下文 / ISOLATED SUB-GOAL EXECUTION CONTEXT]\n` +
+        `你当前处于从主目标派生出的隔离子目标中 (主目标 ID: "${snapshot.parentGoalId || 'parent'}")。\n` +
+        `请严格专注于当前子目标的独立交付！所有里程碑完成后，立即调用 goal_finish 提交最终成果并将控制权移交回主目标。\n`;
+    } else {
+      subGoalContextText = `\n\n[ISOLATED SUB-GOAL EXECUTION CONTEXT]\n` +
+        `You are running inside an isolated sub-goal spawned by parent goal (Parent Goal ID: "${snapshot.parentGoalId || 'parent'}").\n` +
+        `Focus strictly on delivering this specific sub-goal objective! When all sub-milestones are completed, call tool goal_finish immediately to return deliverables and control to the parent goal.\n`;
+    }
+  }
+
   const allMilestones = snapshot.milestones || [];
   const formatMilestone = (m, i) => {
+    const origIdx = allMilestones.indexOf(m);
+    const num = origIdx >= 0 ? origIdx + 1 : i + 1;
     const depCheck = isMilestoneBlocked(m, allMilestones);
     const blockedLabel = depCheck.blocked
       ? ` (BLOCKED by ${depCheck.missingDependencies.join(', ')})`
       : '';
-    let line = `  ${i + 1}. [${m.status.toUpperCase()}] ${m.title}${blockedLabel}${m.notes ? ` (${m.notes})` : ''}`;
+    let line = `  ${num}. [${m.status.toUpperCase()}] ${m.title}${blockedLabel}${m.notes ? ` (${m.notes})` : ''}`;
     if (Array.isArray(m.checklist) && m.checklist.length > 0) {
       const checkLines = m.checklist
         .map((item) => `      [${item.done ? 'x' : ' '}] ${item.text}`)
@@ -71,12 +87,26 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     return line;
   };
 
+  const enableCompaction = snapshot.enableMilestoneCompaction !== false;
+  const completedMilestones = allMilestones.filter((m) => m && m.status === 'completed');
+  const activeMilestones = allMilestones.filter((m) => m && m.status !== 'completed');
+  const shouldCompact = enableCompaction && completedMilestones.length > 0 && activeMilestones.length > 0;
+
+  let compactedBlock = '';
+  if (shouldCompact) {
+    compactedBlock = `${buildCompactedMilestonesHistory(completedMilestones, lang)}\n\n`;
+  }
+
+  const displayMilestones = shouldCompact ? activeMilestones : allMilestones;
+
   if (lang === 'zh') {
+    const planTitle = shouldCompact ? '当前进行中与后续工作计划:' : '工作计划:';
     const milestonesText = hasMilestones
-      ? snapshot.milestones.map(formatMilestone).join('\n')
+      ? displayMilestones.map(formatMilestone).join('\n')
       : '  (工作计划尚未建立 — 请立即调用 goal_set_milestones 设定初始里程碑！)';
 
     return (
+      subGoalContextText +
       operatorAnswerText +
       directiveText +
       nudgeText +
@@ -84,7 +114,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
       `\n\n[DSH GOAL MODE ACTIVE]\n` +
       `目标: "${snapshot.title}"\n` +
       `运行时间: ${snapshot.formattedElapsed}${etaText} | 迭代轮次: ${snapshot.iterationsCount}/${snapshot.maxIterations}\n` +
-      `工作计划:\n` +
+      `${compactedBlock}${planTitle}\n` +
       `${milestonesText}\n\n` +
       `Goal Mode 执行契约 (必须严格遵循):\n` +
       `1. ${hasMilestones ? '按部就班推进当前进行中的里程碑。注意：标记为 [BLOCKED] 的里程碑在前置依赖完成前严禁推进。' : '第一步核心指令: 立即调用 goal_set_milestones 制定 3-7 个具体里程碑。在完成此工具调用前严禁执行其他操作！'}\n` +
@@ -93,11 +123,13 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     );
   }
 
+  const planTitle = shouldCompact ? 'Active & Upcoming Work Plan:' : 'Work Plan:';
   const milestonesText = hasMilestones
-    ? snapshot.milestones.map(formatMilestone).join('\n')
+    ? displayMilestones.map(formatMilestone).join('\n')
     : '  (Work plan is not yet established — call goal_set_milestones immediately with initial steps!)';
 
   return (
+    subGoalContextText +
     operatorAnswerText +
     directiveText +
     nudgeText +
@@ -105,7 +137,7 @@ export function buildStatePromptInjection(snapshot, pendingNudge) {
     `\n\n[DSH GOAL MODE ACTIVE]\n` +
     `Goal: "${snapshot.title}"\n` +
     `Elapsed Time: ${snapshot.formattedElapsed}${etaText} | Iteration: ${snapshot.iterationsCount}/${snapshot.maxIterations}\n` +
-    `Work Plan:\n` +
+    `${compactedBlock}${planTitle}\n` +
     `${milestonesText}\n\n` +
     `Goal Mode Instructions (MANDATORY TO FOLLOW):\n` +
     `1. ${hasMilestones ? 'Execute the current active milestone from the work plan. Note: Milestones marked [BLOCKED] must not be started until prerequisite milestones are COMPLETED.' : 'YOUR FIRST STEP: Immediately call tool goal_set_milestones with the list of milestones (3-7 concrete steps). You must not execute work or finish turn without calling goal_set_milestones!'}\n` +

package/lib/engine-subgoals.js

@@ -0,0 +1,207 @@
+/**
+ * Hierarchical Recursive Sub-goals Engine Module (Issue #170).
+ * Supports isolated context execution, state counters isolation,
+ * breadcrumbs hierarchy, and artifact/control synchronization with parent goals.
+ */
+
+import { GoalState } from './goal-engine-constants.js';
+
+/**
+ * Spawn a child sub-goal under a parent goal session
+ * @param {object} engine - GoalEngine instance
+ * @param {string} parentSessionId - Parent goal session ID
+ * @param {object} options - Sub-goal options { title, prompt, description, maxIterations, cwd, inheritContext, milestones }
+ * @returns {object}
+ */
+export function spawnSubGoal(engine, parentSessionId, options = {}) {
+  if (!engine) throw new Error('GoalEngine instance is required');
+
+  const pSid = parentSessionId || 'default';
+  const parentGoal = engine.goals.get(pSid);
+  if (!parentGoal) {
+    return { ok: false, error: `Parent goal for session "${pSid}" not found` };
+  }
+
+  const rawTitle = options.title || options.goal;
+  if (!rawTitle || typeof rawTitle !== 'string' || !rawTitle.trim()) {
+    return { ok: false, error: 'Sub-goal title is required and cannot be empty' };
+  }
+
+  const cleanTitle = rawTitle.trim();
+  const subGoalId = options.subGoalId || `sub-${Date.now().toString(36)}-${Math.random().toString(36).substring(2, 6)}`;
+  const childSessionId = options.sessionId || `${pSid}:subgoal:${subGoalId}`;
+
+  const inheritContext = options.inheritContext !== false && options.inherit_context !== false;
+  let childDesc = (options.prompt || options.description || '').trim();
+  if (inheritContext) {
+    const parentContextTag = `[Parent Goal: "${parentGoal.title}"]`;
+    childDesc = childDesc ? `${parentContextTag} ${childDesc}` : parentContextTag;
+  }
+
+  const maxIters = typeof options.maxIterations === 'number'
+    ? options.maxIterations
+    : (typeof options.max_iterations === 'number' ? options.max_iterations : 15);
+
+  const childSnapshot = engine.startGoal(cleanTitle, {
+    description: childDesc,
+    maxIterations: maxIters,
+    cwd: options.cwd || parentGoal.cwd,
+    lang: options.lang || parentGoal.lang,
+    parentGoalId: parentGoal.id,
+    parentSessionId: pSid,
+    autoBranch: false,
+    milestones: Array.isArray(options.milestones) ? options.milestones : [],
+  }, childSessionId);
+
+  const childGoal = engine.goals.get(childSessionId);
+  if (childGoal) {
+    childGoal.parentGoalId = parentGoal.id;
+    childGoal.parentSessionId = pSid;
+    childGoal.isSubGoal = true;
+    childGoal.subGoalId = subGoalId;
+  }
+
+  if (!Array.isArray(parentGoal.subGoals)) {
+    parentGoal.subGoals = [];
+  }
+
+  parentGoal.subGoals.push({
+    id: childGoal ? childGoal.id : childSnapshot.id,
+    subGoalId,
+    sessionId: childSessionId,
+    title: cleanTitle,
+    state: childGoal ? childGoal.state : GoalState.RUNNING,
+    createdAt: childGoal ? childGoal.startedAt : Date.now(),
+    completedAt: null,
+    resultSummary: '',
+  });
+
+  if (typeof engine.recordToolActivity === 'function') {
+    engine.recordToolActivity('spawnSubGoal', 'success', `Spawned sub-goal [${cleanTitle}]`, pSid);
+  }
+
+  engine.emit(pSid, true);
+
+  return {
+    ok: true,
+    parentGoalId: parentGoal.id,
+    parentSessionId: pSid,
+    subGoalId,
+    childSessionId,
+    childGoal: childSnapshot,
+  };
+}
+
+/**
+ * Complete a child sub-goal and synchronize state/deliverables back to parent goal
+ * @param {object} engine - GoalEngine instance
+ * @param {string} childSessionId - Child sub-goal session ID
+ * @param {string} [resultSummary=''] - Deliverables summary
+ * @returns {object}
+ */
+export function syncSubGoalToParent(engine, childSessionId, resultSummary = '') {
+  if (!engine) return false;
+  const childGoal = engine.goals.get(childSessionId);
+  if (!childGoal) return false;
+
+  const pSid = childGoal.parentSessionId;
+  const parentGoal = pSid ? engine.goals.get(pSid) : null;
+  if (!parentGoal) return false;
+
+  if (Array.isArray(parentGoal.subGoals)) {
+    const entry = parentGoal.subGoals.find(
+      (s) => s.sessionId === childSessionId || s.id === childGoal.id || (childGoal.subGoalId && s.subGoalId === childGoal.subGoalId)
+    );
+    if (entry) {
+      entry.state = GoalState.COMPLETED;
+      entry.completedAt = Date.now();
+      entry.resultSummary = resultSummary;
+    }
+  }
+
+  const note = resultSummary ? `: ${resultSummary}` : '';
+  parentGoal.logs.push({
+    timestamp: Date.now(),
+    type: 'info',
+    message: `Sub-goal [${childGoal.title}] completed${note}`,
+  });
+
+  if (typeof engine.recordToolActivity === 'function') {
+    engine.recordToolActivity('completeSubGoal', 'success', `Sub-goal [${childGoal.title}] completed`, pSid);
+  }
+
+  engine.emit(pSid, true);
+  return true;
+}
+
+export function completeSubGoal(engine, childSessionId, resultSummary = '') {
+  if (!engine) throw new Error('GoalEngine instance is required');
+  if (!childSessionId) return { ok: false, error: 'childSessionId is required' };
+
+  const childGoal = engine.goals.get(childSessionId);
+  if (!childGoal) {
+    return { ok: false, error: `Child sub-goal "${childSessionId}" not found` };
+  }
+
+  const pSid = childGoal.parentSessionId;
+  if (childGoal.state !== GoalState.COMPLETED) {
+    engine.completeGoal(resultSummary, childSessionId);
+  } else {
+    syncSubGoalToParent(engine, childSessionId, resultSummary);
+  }
+
+  return {
+    ok: true,
+    childSessionId,
+    parentSessionId: pSid || null,
+    resultSummary,
+  };
+}
+
+/**
+ * Get hierarchy breadcrumbs chain from root goal down to current session
+ * @param {object} engine - GoalEngine instance
+ * @param {string} [sessionId='default']
+ * @returns {Array<{ sessionId: string, id: string, title: string, state: string, isSubGoal: boolean, isCurrent?: boolean }>}
+ */
+export function getSubGoalBreadcrumbs(engine, sessionId = 'default') {
+  if (!engine || !engine.goals) return [];
+
+  const crumbs = [];
+  let currSid = sessionId || 'default';
+  const visited = new Set();
+
+  while (currSid && !visited.has(currSid)) {
+    visited.add(currSid);
+    const g = engine.goals.get(currSid);
+    if (!g) break;
+
+    crumbs.unshift({
+      sessionId: currSid,
+      id: g.id,
+      title: g.title,
+      state: g.state,
+      isSubGoal: Boolean(g.parentGoalId || g.isSubGoal),
+    });
+
+    currSid = g.parentSessionId;
+  }
+
+  if (crumbs.length > 0) {
+    crumbs[crumbs.length - 1].isCurrent = true;
+  }
+
+  return crumbs;
+}
+
+/**
+ * Get list of child sub-goals for a given parent session
+ * @param {object} engine - GoalEngine instance
+ * @param {string} [sessionId='default']
+ * @returns {Array<object>}
+ */
+export function getSubGoalsList(engine, sessionId = 'default') {
+  if (!engine || !engine.goals) return [];
+  const g = engine.goals.get(sessionId || 'default');
+  return Array.isArray(g?.subGoals) ? g.subGoals : [];
+}

package/lib/goal-engine-constants.js

@@ -192,6 +192,12 @@ export function buildSnapshot(goal, sid, engine) {
       enableMilestoneDependencies: engine.enableMilestoneDependencies ?? true,
       soundScheme: engine.soundScheme ?? 'default',
       enableVoiceAnnouncements: engine.enableVoiceAnnouncements ?? false,
+      enableMilestoneCompaction: engine.enableMilestoneCompaction ?? true,
+      parentGoalId: null,
+      parentSessionId: null,
+      isSubGoal: false,
+      subGoals: [],
+      breadcrumbs: [],
       operatorQuery: null,
       waitingForOperator: false,
     };
@@ -253,6 +259,12 @@ export function buildSnapshot(goal, sid, engine) {
     enableMilestoneDependencies: engine.enableMilestoneDependencies ?? true,
     soundScheme: engine.soundScheme ?? 'default',
     enableVoiceAnnouncements: engine.enableVoiceAnnouncements ?? false,
+    enableMilestoneCompaction: engine.enableMilestoneCompaction ?? true,
+    parentGoalId: goal.parentGoalId || null,
+    parentSessionId: goal.parentSessionId || null,
+    isSubGoal: Boolean(goal.parentGoalId || goal.isSubGoal),
+    subGoals: Array.isArray(goal.subGoals) ? goal.subGoals : [],
+    breadcrumbs: typeof engine.getSubGoalBreadcrumbs === "function" ? engine.getSubGoalBreadcrumbs(sid) : [],
     operatorQuery: goal.operatorQuery || null,
     waitingForOperator: Boolean(goal.waitingForOperator),
   };

package/lib/goal-engine.js

@@ -13,8 +13,10 @@ import { parseIssueRef, parseIssueChecklist, syncMilestoneWithIssue } from './en
 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';
+import { compactMilestone, estimateCompactionSavings } from './engine-compaction.js';
+import { spawnSubGoal, completeSubGoal, syncSubGoalToParent, getSubGoalBreadcrumbs, getSubGoalsList } from './engine-subgoals.js';
 
-export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist, getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact };
+export { GoalMode, GoalState, MilestoneStatus, formatElapsed, formatETA, detectLanguage, sessionIdOf, matchMilestone, parseIssueChecklist, getGitCurrentCommit, exportReportMarkdown, exportReportGitHubPR, createMilestoneCheckpoint, rollbackToCheckpoint, saveGoalArtifact, compactMilestone, estimateCompactionSavings, spawnSubGoal, completeSubGoal, getSubGoalBreadcrumbs, getSubGoalsList };
 
 /**
  * Isolated Goal Management Engine for DeepSeek Harness
@@ -34,7 +36,7 @@ export class GoalEngine {
       autoBranchOnGoalStart: options.autoBranchOnGoalStart ?? true, enablePostGoalRetrospective: options.enablePostGoalRetrospective ?? true,
       autoScaleBudgetNearCompletion: options.autoScaleBudgetNearCompletion ?? false, enableTemplatesDrawer: options.enableTemplatesDrawer ?? true,
       enableMilestoneDependencies: options.enableMilestoneDependencies ?? true, soundScheme: options.soundScheme ?? 'default', enableKanbanSync: options.enableKanbanSync ?? true, ctx: options.ctx || null, kanbanService: options.kanbanService || null, kanbanStore: options.kanbanStore || null,
-      enableVoiceAnnouncements: options.enableVoiceAnnouncements ?? false, approvalGate: options.approvalGate || null,
+      enableVoiceAnnouncements: options.enableVoiceAnnouncements ?? false, enableMilestoneCompaction: options.enableMilestoneCompaction ?? true, approvalGate: options.approvalGate || null,
       checkApproval: options.checkApproval || null, maxSessions: options.maxSessions ?? 100,
     });
     this.goals = new Map();
@@ -58,10 +60,7 @@ export class GoalEngine {
   flushSync() { this.store.flushSync(); }
   saveStateToDisk() { this.flushSync(); }
 
-  subscribe(callback) {
-    this.listeners.add(callback);
-    return () => this.listeners.delete(callback);
-  }
+  subscribe(callback) { this.listeners.add(callback); return () => this.listeners.delete(callback); }
 
   emit(sessionId = 'default', immediate = false) {
     this.scheduleSave(immediate);
@@ -76,21 +75,9 @@ export class GoalEngine {
     }
   }
 
-  recordProgress(sessionId = 'default') {
-    this.stallCounters.set(sessionId || 'default', 0);
-  }
-
-  incrementStallCount(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    const current = this.stallCounters.get(sid) || 0;
-    const next = current + 1;
-    this.stallCounters.set(sid, next);
-    return next;
-  }
-
-  getStallCount(sessionId = 'default') {
-    return this.stallCounters.get(sessionId || 'default') || 0;
-  }
+  recordProgress(sessionId = 'default') { this.stallCounters.set(sessionId || 'default', 0); }
+  incrementStallCount(sessionId = 'default') { const sid = sessionId || 'default'; const n = (this.stallCounters.get(sid) || 0) + 1; this.stallCounters.set(sid, n); return n; }
+  getStallCount(sessionId = 'default') { return this.stallCounters.get(sessionId || 'default') || 0; }
 
   updateConfig(config = {}) {
     const rawMax = config.defaultMaxIterations ?? config.maxIterations;
@@ -104,7 +91,7 @@ export class GoalEngine {
         }
       }
     }
-    const boolKeys = ['autoDrive', 'enableSound', 'showQuickLaunchButton', 'autoCheckpointOnMilestone', 'enableLiveActivityFeed', 'enablePreplanning', 'autoBranchOnGoalStart', 'enablePostGoalRetrospective', 'autoScaleBudgetNearCompletion', 'enableTemplatesDrawer', 'enableMilestoneDependencies', 'enableVoiceAnnouncements'];
+    const boolKeys = ['autoDrive', 'enableSound', 'showQuickLaunchButton', 'autoCheckpointOnMilestone', 'enableLiveActivityFeed', 'enablePreplanning', 'autoBranchOnGoalStart', 'enablePostGoalRetrospective', 'autoScaleBudgetNearCompletion', 'enableTemplatesDrawer', 'enableMilestoneDependencies', 'enableVoiceAnnouncements', 'enableMilestoneCompaction'];
     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);
@@ -208,6 +195,10 @@ export class GoalEngine {
       issueRef: parseIssueRef(cleanTitle),
       operatorQuery: null,
       waitingForOperator: false,
+      parentGoalId: options.parentGoalId || null,
+      parentSessionId: options.parentSessionId || null,
+      isSubGoal: Boolean(options.parentGoalId),
+      subGoals: [],
       tokensUsage: { promptTokens: 0, completionTokens: 0, totalTokens: 0 },
       logs: [{
         timestamp: now,
@@ -305,16 +296,14 @@ export class GoalEngine {
         m.status = MilestoneStatus.COMPLETED;
       }
     }
+    if (goal.parentSessionId) syncSubGoalToParent(this, sid, summary);
     this.stallCounters.delete(sid);
     this.toolFailureCounters.delete(sid);
     this.emit(sid, true);
     return this.getSnapshot(sid);
   }
 
-  setMilestones(milestonesList, sessionId = 'default') {
-    this.addMilestones(milestonesList, true, sessionId);
-    return this.getSnapshot(sessionId);
-  }
+  setMilestones(milestonesList, sessionId = 'default') { this.addMilestones(milestonesList, true, sessionId); return this.getSnapshot(sessionId); }
 
   addMilestones(milestonesList, shouldEmit = true, sessionId = 'default') {
     const sid = typeof shouldEmit === 'string' ? shouldEmit : (sessionId || 'default');
@@ -365,6 +354,7 @@ export class GoalEngine {
     if (this.enableKanbanSync) syncMilestoneStatusToKanban(target, { goal, ctx: this.ctx, store: this.kanbanStore, kanbanService: this.kanbanService }).catch(() => {});
 
     if (target.status === MilestoneStatus.COMPLETED && prevStatus !== MilestoneStatus.COMPLETED) {
+      if (this.enableMilestoneCompaction !== false) compactMilestone(target, { goal, cwd: goal.cwd });
       if (this.autoCheckpointOnMilestone) {
         const commitHash = createMilestoneCheckpoint(target, sid);
         if (commitHash) {
@@ -439,9 +429,7 @@ export class GoalEngine {
     return true;
   }
 
-  getElapsedSeconds(sessionId = 'default') {
-    return calculateElapsedSeconds(this.goals.get(sessionId || 'default'));
-  }
+  getElapsedSeconds(sessionId = 'default') { return calculateElapsedSeconds(this.goals.get(sessionId || 'default')); }
 
   addTokenUsage(usage, sessionId = 'default') {
     if (!usage || typeof usage !== 'object') return;
@@ -471,19 +459,9 @@ export class GoalEngine {
     this.emit(sid);
   }
 
-  getEstimatedRemainingSeconds(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    return calculateRemainingSeconds(this.goals.get(sid), this.getElapsedSeconds(sid));
-  }
-
-  getSnapshot(sessionId = 'default') {
-    const sid = sessionId || 'default';
-    return buildSnapshot(this.goals.get(sid), sid, this);
-  }
-
-  getGoalSnapshot(sessionId = 'default') {
-    return this.getSnapshot(sessionId);
-  }
+  getEstimatedRemainingSeconds(sessionId = 'default') { const sid = sessionId || 'default'; return calculateRemainingSeconds(this.goals.get(sid), this.getElapsedSeconds(sid)); }
+  getSnapshot(sessionId = 'default') { const sid = sessionId || 'default'; return buildSnapshot(this.goals.get(sid), sid, this); }
+  getGoalSnapshot(sessionId = 'default') { return this.getSnapshot(sessionId); }
 
   getStatePromptInjection(sessionId = 'default') {
     const sid = sessionId || 'default';
@@ -591,4 +569,9 @@ export class GoalEngine {
     const goal = this.goals.get(sessionId || 'default');
     return Boolean(goal && (goal.mode === GoalMode.PLAN || goal.state === GoalState.PLANNING));
   }
+  spawnSubGoal(options = {}, sessionId = 'default') { return spawnSubGoal(this, sessionId, options); }
+  completeSubGoal(sessionId, summary = '') { return completeSubGoal(this, sessionId, summary); }
+  getSubGoals(sessionId = 'default') { return getSubGoalsList(this, sessionId); }
+  getSubGoalBreadcrumbs(sessionId = 'default') { return getSubGoalBreadcrumbs(this, sessionId); }
+  getCompactionSavings(sessionId = 'default') { const g = this.goals.get(sessionId || 'default'); return estimateCompactionSavings(g?.milestones || [], g?.lang || 'en'); }
 }

package/lib/index.js

@@ -143,13 +143,6 @@ export function apply(ctx, config = {}) {
     logger.warn?.('[dsh-goal] Legacy migration check failed:', migErr.message);
   }
 
-  // Register addon tools: goal_milestones and goal_checklist
-  registerTools(ctx, {
-    milestoneManager,
-    goalsService: safeService(ctx, "goals"),
-    logger,
-  });
-
   // Support fallback engine for tests or non-core environments
   let fallbackEngine = null;
   if (!safeService(ctx, "goals")) {
@@ -168,12 +161,22 @@ export function apply(ctx, config = {}) {
       autoScaleBudgetNearCompletion: currentSettings.autoScaleBudgetNearCompletion,
       enableTemplatesDrawer: currentSettings.enableTemplatesDrawer,
       enableMilestoneDependencies: currentSettings.enableMilestoneDependencies,
+      enableMilestoneCompaction: currentSettings.enableMilestoneCompaction,
       approvalGate: safeService(ctx, "approvalGate"),
       logger,
     });
+    ctx.goalEngine = fallbackEngine;
     registerPlanModeGuard(ctx, { engine: fallbackEngine, logger });
   }
 
+  // Register addon tools: goal_milestones, goal_checklist, goal_spawn_subgoal
+  registerTools(ctx, {
+    milestoneManager,
+    goalsService: safeService(ctx, "goals"),
+    engine: fallbackEngine,
+    logger,
+  });
+
   // 1. One-click auto-updater registration (Issue #99)
   if (ctx?.webServer?.register) {
     if (typeof ctx?.effect === 'function') {

package/lib/routes.js

@@ -873,6 +873,31 @@ export function registerRoutes(ctx, {
                   break;
                 }
 
+                case 'spawn_subgoal': {
+                  const subTitle = typeof data.title === 'string' ? data.title.trim() : '';
+                  if (!subTitle) {
+                    res.statusCode = 400;
+                    return res.end(JSON.stringify({ error: 'Sub-goal title is required' }));
+                  }
+                  if (engine) {
+                    const spawnRes = engine.spawnSubGoal({
+                      title: subTitle,
+                      prompt: data.prompt || data.description,
+                      maxIterations: data.maxIterations ?? data.max_iterations,
+                      inheritContext: data.inheritContext ?? data.inherit_context,
+                    }, sid);
+                    if (!spawnRes.ok) {
+                      res.statusCode = 400;
+                      return res.end(JSON.stringify({ error: spawnRes.error || 'Failed to spawn sub-goal' }));
+                    }
+                    result = spawnRes;
+                  } else {
+                    res.statusCode = 404;
+                    result = { ok: false, error: 'Goal engine unavailable' };
+                  }
+                  break;
+                }
+
                 case 'instantiate_template': {
                   const tplId = data.templateId || data.id;
                   if (!tplId) {

package/lib/tools.js

@@ -376,5 +376,74 @@ export function registerTools(ctx, { milestoneManager, goalsService, logger = co
       output: JSON_OUTPUT,
       execute: handleGoalAskOperator,
     });
+
+    // Tool 7: goal_spawn_subgoal (Issue #170)
+    const handleGoalSpawnSubgoal = async (args = {}, toolCtx = {}) => {
+      const parentSessionId = args.goalId || args.goal_id || resolveGoalId(toolCtx);
+      const title = args.title || args.goal;
+      if (!title || typeof title !== 'string' || !title.trim()) {
+        throw new Error('Field "title" is required and must be a non-empty string');
+      }
+
+      const engine = ctx.goalEngine || (ctx.get && ctx.get('goalEngine'));
+      if (engine && typeof engine.spawnSubGoal === 'function') {
+        const res = engine.spawnSubGoal({
+          title: title.trim(),
+          prompt: args.prompt || args.description,
+          maxIterations: args.max_iterations ?? args.maxIterations,
+          inheritContext: args.inherit_context ?? args.inheritContext,
+        }, parentSessionId);
+
+        if (!res.ok) {
+          throw new Error(`Failed to spawn sub-goal: ${res.error}`);
+        }
+
+        return {
+          ok: true,
+          parentGoalId: res.parentGoalId,
+          parentSessionId: res.parentSessionId,
+          subGoalId: res.subGoalId,
+          childSessionId: res.childSessionId,
+          title: title.trim(),
+          message: 'Sub-goal spawned with isolated execution context. Complete sub-milestones and invoke goal_finish to conclude.',
+        };
+      }
+
+      return {
+        ok: true,
+        parentSessionId,
+        title: title.trim(),
+        message: 'Sub-goal registered (fallback mode).',
+      };
+    };
+
+    safeRegister({
+      name: 'goal_spawn_subgoal',
+      description: 'Spawn a child sub-goal with isolated context and task checklist (#170). When all sub-milestones are completed, invoking goal_finish returns deliverables and control to the parent goal.',
+      parameters: {
+        type: 'object',
+        properties: {
+          title: {
+            type: 'string',
+            description: 'Clear, actionable title of the sub-goal',
+          },
+          prompt: {
+            type: 'string',
+            description: 'Optional context, detailed instructions, or constraints for the sub-goal',
+          },
+          max_iterations: {
+            type: 'number',
+            description: 'Maximum iteration budget for the sub-goal (default: 15)',
+          },
+          inherit_context: {
+            type: 'boolean',
+            description: 'Whether the child sub-goal inherits parent goal context summary (default: true)',
+          },
+        },
+        required: ['title'],
+      },
+      output: JSON_OUTPUT,
+      execute: handleGoalSpawnSubgoal,
+    });
   });
 }

package/package.json

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