@goodandready/dsh-goal 0.2.30 → 0.2.32

package/lib/engine-diff.js

@@ -0,0 +1,147 @@
+import { execFileSync } from 'node:child_process';
+import { getSafeCwd } from './goal-engine-constants.js';
+import { isGitRepository, isValidGitRef } from './engine-git-branch.js';
+
+/**
+ * Parse git diff --numstat output into structured file statistics
+ * @param {string} output 
+ * @returns {Array<{ path: string, insertions: number, deletions: number, binary: boolean }>}
+ */
+export function parseNumstat(output) {
+  if (!output || typeof output !== 'string') return [];
+  const lines = output.trim().split('\n');
+  const files = [];
+  for (const line of lines) {
+    if (!line.trim()) continue;
+    const parts = line.split('\t');
+    if (parts.length < 3) continue;
+    const [rawIns, rawDel, filePath] = parts;
+    const isBinary = rawIns === '-' || rawDel === '-';
+    const ins = isBinary ? 0 : parseInt(rawIns, 10) || 0;
+    const del = isBinary ? 0 : parseInt(rawDel, 10) || 0;
+    files.push({
+      path: filePath,
+      insertions: ins,
+      deletions: del,
+      binary: isBinary,
+    });
+  }
+  return files;
+}
+
+/**
+ * Get git diff between refs or current working tree
+ * @param {object} options
+ * @returns {object} diff result payload
+ */
+export function getGitDiff({
+  cwd = process.cwd(),
+  base,
+  target,
+  file,
+  allowedRoots = [],
+  maxBytes = 256 * 1024,
+} = {}) {
+  const safeCwd = getSafeCwd(cwd, allowedRoots);
+  if (!safeCwd || !isGitRepository(safeCwd, allowedRoots)) {
+    return { ok: false, error: 'Not a git repository or invalid path' };
+  }
+
+  // Ref validation: disallow flag injection and special chars
+  if (base && !isValidGitRef(base)) {
+    return { ok: false, error: 'Invalid base git ref' };
+  }
+  if (target && !isValidGitRef(target)) {
+    return { ok: false, error: 'Invalid target git ref' };
+  }
+  if (file && (typeof file !== 'string' || file.startsWith('-') || /[\0\r\n]/.test(file))) {
+    return { ok: false, error: 'Invalid file parameter' };
+  }
+
+  try {
+    const rangeArgs = [];
+    if (base && target) {
+      rangeArgs.push(`${base}..${target}`);
+    } else if (base) {
+      rangeArgs.push(base);
+    } else if (target) {
+      rangeArgs.push(target);
+    }
+
+    // 1. Fetch numstat for file summary
+    const numstatArgs = ['diff', '--numstat', ...rangeArgs];
+    if (file) {
+      numstatArgs.push('--', file);
+    }
+    const numstatOut = execFileSync('git', numstatArgs, {
+      cwd: safeCwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+    });
+
+    const files = parseNumstat(numstatOut);
+    const stats = {
+      filesChanged: files.length,
+      insertions: files.reduce((acc, f) => acc + f.insertions, 0),
+      deletions: files.reduce((acc, f) => acc + f.deletions, 0),
+    };
+
+    // 2. Fetch patch
+    const patchArgs = ['diff', '-p', '--no-color', ...rangeArgs];
+    if (file) {
+      patchArgs.push('--', file);
+    }
+    let patchOut = execFileSync('git', patchArgs, {
+      cwd: safeCwd,
+      encoding: 'utf8',
+      stdio: ['ignore', 'pipe', 'pipe'],
+      timeout: 5000,
+      maxBuffer: 2 * 1024 * 1024,
+    });
+
+    let truncated = false;
+    if (patchOut.length > maxBytes) {
+      patchOut = patchOut.slice(0, maxBytes);
+      truncated = true;
+    }
+
+    return {
+      ok: true,
+      cwd: safeCwd,
+      base: base || null,
+      target: target || 'HEAD',
+      stats,
+      files,
+      diff: patchOut,
+      truncated,
+    };
+  } catch (err) {
+    return { ok: false, error: err.message || 'git diff execution failed' };
+  }
+}
+
+/**
+ * GoalEngine helper to fetch diff for active or specified session
+ * @param {object} engine 
+ * @param {string} sessionId 
+ * @param {object} options 
+ * @returns {object} diff result
+ */
+export function getEngineGoalDiff(engine, sessionId = 'default', options = {}) {
+  const sid = sessionId || 'default';
+  const goal = engine.goals?.get(sid);
+  const allowedRoots = options.allowedRoots || engine.config?.allowedRoots || (goal?.cwd ? [goal.cwd, process.cwd()] : [process.cwd()]);
+  const cwd = options.cwd || goal?.cwd || engine.config?.cwd || process.cwd();
+  const base = options.base || goal?.gitStartCommit || null;
+  const target = options.target || goal?.gitBranch || goal?.branchName || 'HEAD';
+
+  return getGitDiff({
+    cwd,
+    base,
+    target,
+    file: options.file,
+    allowedRoots,
+    maxBytes: options.maxBytes,
+  });
+}

package/lib/engine-kanban-sync.js

@@ -0,0 +1,242 @@
+import { MilestoneStatus } from './goal-engine-constants.js';
+
+export const MILESTONE_TO_KANBAN_COLUMN = {
+  [MilestoneStatus.PENDING]: 'todo',
+  [MilestoneStatus.IN_PROGRESS]: 'in_progress',
+  [MilestoneStatus.COMPLETED]: 'done',
+  pending: 'todo',
+  in_progress: 'in_progress',
+  active: 'in_progress',
+  completed: 'done',
+  PENDING: 'todo',
+  ACTIVE: 'in_progress',
+  COMPLETED: 'done',
+};
+
+export const KANBAN_COLUMN_TO_MILESTONE_STATUS = {
+  backlog: MilestoneStatus.PENDING,
+  todo: MilestoneStatus.PENDING,
+  in_progress: MilestoneStatus.IN_PROGRESS,
+  doing: MilestoneStatus.IN_PROGRESS,
+  active: MilestoneStatus.IN_PROGRESS,
+  review: MilestoneStatus.COMPLETED,
+  done: MilestoneStatus.COMPLETED,
+  completed: MilestoneStatus.COMPLETED,
+};
+
+/**
+ * Format externalRef string for a goal milestone
+ * @param {string} goalId 
+ * @param {string} milestoneId 
+ * @returns {string}
+ */
+export function formatMilestoneExternalRef(goalId, milestoneId) {
+  return `dsh-goal:${goalId || 'default'}:${milestoneId}`;
+}
+
+/**
+ * Parse milestone externalRef
+ * @param {string} externalRef 
+ * @returns {{ goalId: string, milestoneId: string } | null}
+ */
+export function parseMilestoneExternalRef(externalRef) {
+  if (typeof externalRef !== 'string' || !externalRef.startsWith('dsh-goal:')) {
+    return null;
+  }
+  const parts = externalRef.split(':');
+  if (parts.length < 3) return null;
+  return {
+    goalId: parts[1],
+    milestoneId: parts.slice(2).join(':'),
+  };
+}
+
+/**
+ * Resolve active kanban service or store from context/options
+ * @param {object} options 
+ * @returns {{ service: object | null, store: object | null }}
+ */
+export function resolveKanbanServices(options = {}) {
+  const ctx = options.ctx;
+  let service = options.kanbanService || null;
+  let store = options.store || null;
+
+  if (!service && ctx) {
+    service = ctx.dshKanban || (typeof ctx.get === 'function' ? ctx.get('dshKanban') : null);
+  }
+
+  if (!store) {
+    if (service && typeof service.getStore === 'function') {
+      store = service.getStore();
+    } else if (ctx?.kanbanStore) {
+      store = ctx.kanbanStore;
+    }
+  }
+
+  return { service, store };
+}
+
+/**
+ * Synchronize all milestones of a goal with dsh-kanban
+ * Safe degradation if kanban is not available
+ * @param {object} engine 
+ * @param {string} sessionId 
+ * @param {object} options 
+ * @returns {Promise<object>} sync summary
+ */
+export async function syncGoalToKanban(engine, sessionId = 'default', options = {}) {
+  const sid = sessionId || 'default';
+  const goal = engine.goals?.get(sid);
+  if (!goal) {
+    return { ok: false, error: 'Goal not found' };
+  }
+  if (!goal.milestones || goal.milestones.length === 0) {
+    return { ok: true, synced: 0, reason: 'No milestones in goal' };
+  }
+
+  const { service, store } = resolveKanbanServices({
+    kanbanService: options.kanbanService || engine.kanbanService,
+    store: options.store || engine.kanbanStore,
+    ctx: options.ctx || engine.ctx,
+    ...options,
+  });
+
+  if (!service && !store) {
+    return { ok: false, skipped: true, reason: 'kanban-unavailable' };
+  }
+
+  const results = [];
+  for (const ms of goal.milestones) {
+    const externalRef = formatMilestoneExternalRef(goal.id, ms.id);
+    const col = MILESTONE_TO_KANBAN_COLUMN[ms.status] || 'todo';
+    const title = `[Goal] ${ms.title}`;
+    const body = ms.notes || `Milestone ${ms.id} for goal: ${goal.title}`;
+
+    try {
+      if (service && typeof service.createTask === 'function') {
+        const res = await service.createTask({
+          title,
+          body,
+          column: col,
+          externalRef,
+          labels: ['dsh-goal', String(goal.id)],
+        });
+        results.push({ milestoneId: ms.id, taskId: res.taskId || res.task?.id, ok: res.ok, alreadyExists: res.alreadyExists });
+      } else if (store && typeof store.createTask === 'function') {
+        const existing = typeof store.findTaskByExternalRef === 'function' ? store.findTaskByExternalRef(externalRef) : null;
+        if (!existing) {
+          const task = store.createTask({
+            title,
+            body,
+            column: col,
+            externalRef,
+            labels: ['dsh-goal', String(goal.id)],
+          });
+          results.push({ milestoneId: ms.id, taskId: task.id, ok: true, alreadyExists: false });
+        } else {
+          results.push({ milestoneId: ms.id, taskId: existing.id, ok: true, alreadyExists: true });
+        }
+      }
+    } catch (err) {
+      engine.logger?.warn?.(`[dsh-goal] Kanban milestone sync failed for ${ms.id}:`, err?.message || err);
+      results.push({ milestoneId: ms.id, ok: false, error: err?.message || String(err) });
+    }
+  }
+
+  return { ok: true, synced: results.filter((r) => r.ok).length, total: goal.milestones.length, results };
+}
+
+/**
+ * Update corresponding kanban card column when milestone status changes
+ * @param {object} milestone 
+ * @param {object} options 
+ * @returns {Promise<object>}
+ */
+export async function syncMilestoneStatusToKanban(milestone, { goal, ctx, store, kanbanService } = {}) {
+  if (!milestone || !goal) return { ok: false, error: 'Invalid milestone or goal' };
+
+  const { store: activeStore } = resolveKanbanServices({
+    store,
+    kanbanService,
+    ctx,
+  });
+  if (!activeStore || typeof activeStore.findTaskByExternalRef !== 'function') {
+    return { ok: false, skipped: true, reason: 'kanban-store-unavailable' };
+  }
+
+  const externalRef = formatMilestoneExternalRef(goal.id, milestone.id);
+  const targetCol = MILESTONE_TO_KANBAN_COLUMN[milestone.status] || 'todo';
+
+  try {
+    const task = activeStore.findTaskByExternalRef(externalRef);
+    if (!task) {
+      return { ok: false, skipped: true, reason: 'kanban-task-not-found' };
+    }
+
+    if (task.column !== targetCol && typeof activeStore.moveTask === 'function') {
+      activeStore.moveTask(task.id, { column: targetCol });
+      return { ok: true, synced: true, taskId: task.id, column: targetCol };
+    }
+
+    return { ok: true, synced: true, taskId: task.id, column: task.column, unchanged: true };
+  } catch (err) {
+    return { ok: false, error: err?.message || String(err) };
+  }
+}
+
+/**
+ * Handle external card movement from dsh-kanban board
+ * @param {object} engine 
+ * @param {object} payload 
+ * @param {string} sessionId 
+ * @returns {object}
+ */
+export function handleKanbanCardMoved(engine, payload = {}, sessionId = 'default') {
+  const externalRef = payload.externalRef;
+  const column = payload.column;
+  const targetStatus = payload.status || (column ? KANBAN_COLUMN_TO_MILESTONE_STATUS[column] : null);
+
+  if (!targetStatus) {
+    return { ok: false, error: 'Invalid or missing target milestone status/column' };
+  }
+
+  let goalId = null;
+  let milestoneId = payload.milestoneId || null;
+
+  if (externalRef) {
+    const parsed = parseMilestoneExternalRef(externalRef);
+    if (parsed) {
+      goalId = parsed.goalId;
+      milestoneId = parsed.milestoneId;
+    }
+  }
+
+  const candidateSessions = sessionId && sessionId !== 'default'
+    ? [sessionId, 'default']
+    : ['default', ...engine.goals.keys()];
+
+  for (const sid of candidateSessions) {
+    const goal = engine.goals?.get(sid);
+    if (!goal || (goalId && String(goal.id) !== String(goalId))) continue;
+
+    const ms = goal.milestones?.find((m) => String(m.id) === String(milestoneId) || m.title === payload.title);
+    if (ms) {
+      const updateRes = engine.updateMilestone(
+        ms.id,
+        targetStatus,
+        `Synced from Kanban card move to column '${column || targetStatus}'`,
+        sid
+      );
+      return {
+        ok: true,
+        sessionId: sid,
+        milestoneId: ms.id,
+        prevStatus: ms.status,
+        newStatus: targetStatus,
+        updateResult: updateRes,
+      };
+    }
+  }
+
+  return { ok: false, error: 'Matching milestone not found for external reference' };
+}

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 : [];
+}