@kkelly-offical/kkcode 0.2.3-preview.1 → 0.2.3

package/README.md

@@ -1,6 +1,6 @@
 # kkcode
 
-[![npm version](https://img.shields.io/npm/v/@kkelly-offical/kkcode?label=v0.2.3-preview.1)](https://www.npmjs.com/package/@kkelly-offical/kkcode)
+[![npm version](https://img.shields.io/npm/v/@kkelly-offical/kkcode?label=v0.2.3)](https://www.npmjs.com/package/@kkelly-offical/kkcode)
 [![GitHub Release](https://img.shields.io/github/v/release/kkelly-offical/kkcode)](https://github.com/kkelly-offical/kkcode/releases)
 ![Node](https://img.shields.io/badge/Node.js-%3E%3D22-green)
 ![License](https://img.shields.io/badge/License-GPL--3.0-blue)
@@ -219,18 +219,25 @@ For a deeper boundary matrix, see [CLI General Assistant Capability Matrix](docs
 
 **English**
 - kkcode supports bounded delegation through the `task` surface.
+- Assistant mode may call subagents directly when the user explicitly asks for one or more agents.
+- Use `task_group` to launch multiple parallel background subagents as one observable group.
+- Use `kkcode agent list --json` to inspect built-in, custom, and configured subagent roles.
 - Use `fresh_agent` for isolated implementation work.
 - Use `fork_context` for read-only sidecar work such as research or verification.
 - Do not outsource core understanding when the main thread must synthesize the result.
 
 **中文**
 - kkcode 通过 `task` 能力支持有边界的委派。
+- 当用户显式要求一个或多个智能体工作时，Assistant 模式可以直接调用子智能体。
+- 使用 `task_group` 可以把多个后台子智能体作为同一个并行组启动和观察。
+- 使用 `kkcode agent list --json` 查看内置、自定义和配置覆盖后的子智能体角色。
 - `fresh_agent` 适合隔离实现任务。
 - `fork_context` 适合研究、审计、验证这类只读 sidecar 任务。
 - 如果主线程必须综合判断，就不要把理解工作本身外包出去。
 
 **Background task contract / 后台任务契约**
 - 通过 `background_output` 查看后台任务输出
+- 通过 `kkcode background parallel` 查看并行子智能体分组和 lane 状态
 - 通过 `background_cancel` 取消后台任务
 - 终态固定为 `completed` / `cancelled` / `error` / `interrupted`
 
@@ -376,16 +383,20 @@ update:
 <a id="release-status"></a>
 ## Release Status / 发布状态
 
-**Current preview / 当前预览版本**: `v0.2.3-preview.1`
+**Current stable / 当前稳定版本**: `v0.2.3`
 **Latest releases / 最新发布**: [GitHub Releases](https://github.com/kkelly-offical/kkcode/releases)  
 **Package / 包地址**: [npm](https://www.npmjs.com/package/@kkelly-offical/kkcode)
 
 **English**
-- `0.2.3-preview.1` is the Preview V1 updater release: kkcode can check npm dist-tags at startup and exposes `kkcode update` for manual upgrades.
+- `0.2.3` is the stable assistant/subagent/context release: Assistant can explicitly delegate to one or many subagents, parallel lanes are observable, updater support is included, and context compaction keeps prior summaries plus recent evidence.
+- `0.2.3-preview.2` validated the context compaction path.
+- `0.2.3-preview.1` validated updater checks and the `kkcode update` command.
 - `0.2.1` rebuilt kkcode around Assistant as the default general-purpose lane, with dedicated Agent and LongAgent modes for coding work.
 
 **中文**
-- `0.2.3-preview.1` 是 Preview V1 更新器版本：kkcode 可在启动时检查 npm dist-tag，并提供 `kkcode update` 手动升级入口。
+- `0.2.3` 是稳定版 Assistant / 子智能体 / 上下文版本：Assistant 可以显式委派一个或多个子智能体，并行 lane 可观察，包含更新器能力，上下文压缩会保留旧摘要和近期证据。
+- `0.2.3-preview.2` 验证了上下文压缩路径。
+- `0.2.3-preview.1` 验证了更新检查和 `kkcode update` 命令。
 - `0.2.1` 将 kkcode 重构为以 Assistant 为默认入口的通用个人助手，同时保留专门面向代码工作的 Agent 和 LongAgent 模式。
 
 ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kkelly-offical/kkcode",
-  "version": "0.2.3-preview.1",
+  "version": "0.2.3",
   "description": "CLI-first personal assistant with dedicated coding and LongAgent modes for governed terminal workflows, MCP integrations, and extensible automation.",
   "type": "module",
   "packageManager": "pnpm@10.5.2",
@@ -8,7 +8,7 @@
   "author": "kkelly-offical",
   "repository": {
     "type": "git",
-    "url": "https://github.com/kkelly-offical/kkcode.git"
+    "url": "git+https://github.com/kkelly-offical/kkcode.git"
   },
   "homepage": "https://github.com/kkelly-offical/kkcode",
   "bugs": {
@@ -25,7 +25,7 @@
     "mcp"
   ],
   "bin": {
-    "kkcode": "./src/index.mjs"
+    "kkcode": "src/index.mjs"
   },
   "files": [
     "src/",

package/src/commands/agent.mjs

@@ -1,17 +1,55 @@
 import { Command } from "commander"
 import { buildContext, printContextWarnings } from "../context.mjs"
 import { LongAgentManager } from "../orchestration/longagent-manager.mjs"
+import { listAgents } from "../agent/agent.mjs"
+import { CustomAgentRegistry } from "../agent/custom-agent-loader.mjs"
 
 export function createAgentCommand() {
   const cmd = new Command("agent").description("inspect subagents and longagent runs")
 
   cmd
     .command("list")
-    .description("list configured subagents")
-    .action(async () => {
+    .description("list active subagent roles and configured overrides")
+    .option("--json", "print structured JSON")
+    .option("--configured", "print only config-defined agent.subagents overrides")
+    .option("--include-hidden", "include hidden internal roles")
+    .action(async (options) => {
       const ctx = await buildContext()
       printContextWarnings(ctx)
-      console.log(JSON.stringify(ctx.configState.config.agent.subagents || {}, null, 2))
+      await CustomAgentRegistry.initialize(process.cwd())
+      const configured = ctx.configState.config.agent?.subagents || {}
+      if (options.configured) {
+        console.log(JSON.stringify(configured, null, 2))
+        return
+      }
+      const roles = listAgents({ includeHidden: options.includeHidden === true })
+        .filter((agent) => agent.mode === "subagent")
+        .map((agent) => {
+          const override = configured[agent.name] || null
+          return {
+            name: agent.name,
+            description: agent.description || "",
+            permission: agent.permission || "default",
+            model: override?.model || agent.model || null,
+            providerType: override?.providerType || override?.provider_type || null,
+            tools: agent.tools || null,
+            custom: agent._customAgent === true,
+            scope: agent._scope || null,
+            source: agent._source || null,
+            configured: Boolean(override)
+          }
+        })
+      if (options.json) {
+        console.log(JSON.stringify(roles, null, 2))
+        return
+      }
+      for (const role of roles) {
+        const flags = [role.permission, role.custom ? "custom" : "builtin", role.configured ? "configured" : ""].filter(Boolean).join(", ")
+        const model = role.model ? " model=" + role.model : ""
+        const provider = role.providerType ? " provider=" + role.providerType : ""
+        console.log(role.name + " [" + flags + "]" + model + provider)
+        if (role.description) console.log("  " + role.description)
+      }
     })
 
   cmd

package/src/commands/background.mjs

@@ -14,6 +14,9 @@ function printTaskSummary(task) {
   if (!summary) return
   console.log(`[${summary.status}] ${summary.id} :: ${summary.description}`)
   console.log(`  attempt=${summary.attempt} subagent=${summary.subagent || "-"} execution_mode=${summary.execution_mode || "-"} session=${summary.session_id || "-"}`)
+  if (summary.group_id) {
+    console.log(`  group=${summary.group_id} label=${summary.group_label || "-"}`)
+  }
   if (summary.interruption_reason) {
     console.log(`  interruption=${summary.interruption_reason}`)
   }
@@ -56,6 +59,32 @@ export function createBackgroundCommand() {
       })
     })
 
+
+  cmd
+    .command("parallel")
+    .description("show delegated background tasks grouped as parallel subagent lanes")
+    .option("--json", "print raw JSON")
+    .action(async (options) => {
+      await withContext(async () => {
+        const groups = BackgroundManager.summarizeParallel(await BackgroundManager.list())
+        if (options.json) {
+          console.log(JSON.stringify(groups, null, 2))
+          return
+        }
+        if (groups.length === 0) {
+          console.log("no parallel subagent groups")
+          return
+        }
+        for (const group of groups) {
+          console.log("[group] " + group.group_id + " :: " + group.group_label + " total=" + group.total + " active=" + group.active)
+          for (const lane of group.lanes) {
+            console.log("  [" + lane.status + "] " + lane.id + " subagent=" + (lane.subagent || "-") + " task=" + (lane.logical_task_id || "-") + " session=" + (lane.session_id || "-"))
+            if (lane.result_preview) console.log("    preview=" + lane.result_preview)
+          }
+        }
+      })
+    })
+
   cmd
     .command("output")
     .description("print the terminal result payload for one background task")

package/src/orchestration/background-manager.mjs

@@ -70,6 +70,8 @@ function summarizeTask(task) {
     background_mode: task.backgroundMode || null,
     subagent: task.payload?.subagent || task.payload?.subagentType || null,
     execution_mode: task.payload?.executionMode || null,
+    group_id: task.payload?.groupId || null,
+    group_label: task.payload?.groupLabel || null,
     session_id: task.payload?.subSessionId || null,
     parent_session_id: task.payload?.parentSessionId || null,
     stage_id: task.payload?.stageId || null,
@@ -104,10 +106,47 @@ function summarizeTaskList(tasks = []) {
     recent_terminal: tasks
       .filter((task) => TERMINAL_STATES.has(task.status))
       .slice(0, 3)
-      .map((task) => summarizeTask(task))
+      .map((task) => summarizeTask(task)),
+    parallel_groups: summarizeParallelGroups(tasks)
   }
 }
 
+function summarizeParallelGroups(tasks = []) {
+  const groups = new Map()
+  for (const task of tasks) {
+    const payload = task.payload || {}
+    const groupId = payload.groupId || payload.parentSessionId || "ungrouped"
+    const groupLabel = payload.groupLabel || payload.parentSessionId || "ungrouped"
+    if (!groups.has(groupId)) {
+      groups.set(groupId, {
+        group_id: groupId,
+        group_label: groupLabel,
+        parent_session_id: payload.parentSessionId || null,
+        total: 0,
+        active: 0,
+        counts: { pending: 0, running: 0, completed: 0, cancelled: 0, error: 0, interrupted: 0 },
+        lanes: []
+      })
+    }
+    const group = groups.get(groupId)
+    const status = task.status || "unknown"
+    group.total += 1
+    if (group.counts[status] !== undefined) group.counts[status] += 1
+    if (status === "pending" || status === "running") group.active += 1
+    group.lanes.push({
+      id: task.id,
+      status,
+      subagent: payload.subagent || payload.subagentType || null,
+      execution_mode: payload.executionMode || null,
+      logical_task_id: payload.logicalTaskId || null,
+      session_id: payload.subSessionId || null,
+      description: task.description || "",
+      result_preview: extractTaskResultPreview(task)
+    })
+  }
+  return [...groups.values()].sort((a, b) => b.active - a.active || b.total - a.total)
+}
+
 function resolveWorkerTimeoutMs(config = {}, payload = {}) {
   const raw = Number(payload.workerTimeoutMs || config.background?.worker_timeout_ms || 900000)
   return Number.isFinite(raw) ? Math.max(1000, raw) : 900000
@@ -430,6 +469,10 @@ export const BackgroundManager = {
     return summarizeTaskList(tasks)
   },
 
+  summarizeParallel(tasks) {
+    return summarizeParallelGroups(tasks)
+  },
+
   async list() {
     await ensureBackgroundTaskRuntimeDir()
     return readAllTasks()

package/src/orchestration/task-scheduler.mjs

@@ -195,7 +195,8 @@ async function ensureDelegatedSession({ executionMode, parentSessionId, subSessi
 
 export function createTaskDelegate({ config, parentSessionId, model, providerType, runSubtask }) {
   return async function delegateTask(args = {}) {
-    const executionModeResult = normalizeExecutionMode(args.execution_mode)
+    const requestedExecutionMode = args.inherit_context === true && !args.execution_mode ? "fork_context" : args.execution_mode
+    const executionModeResult = normalizeExecutionMode(requestedExecutionMode)
     if (executionModeResult.error) return { error: executionModeResult.error }
     const executionMode = executionModeResult.mode
     const isolationResult = normalizeIsolation(args.isolation)
@@ -211,7 +212,7 @@ export function createTaskDelegate({ config, parentSessionId, model, providerTyp
     })
 
     const subSessionId = String(args.session_id || `sub_${parentSessionId}_${Date.now()}`)
-    const prompt = buildDelegationPrompt(args)
+    const prompt = buildDelegationPrompt({ ...args, execution_mode: executionMode })
 
     const subModel = subagent.model || model
     const subProvider = subagent.providerType || providerType
@@ -229,7 +230,9 @@ export function createTaskDelegate({ config, parentSessionId, model, providerTyp
         model: subModel,
         providerType: subProvider,
         subagent,
-        allowQuestion: args.allow_question === true
+        allowQuestion: args.allow_question === true,
+        groupId: args.group_id || null,
+        groupLabel: args.group_label || null
       })
       await log(out.reply)
       if (isCancelled()) return { cancelled: true }
@@ -243,7 +246,9 @@ export function createTaskDelegate({ config, parentSessionId, model, providerTyp
         reply: out.reply,
         tool_events: out.toolEvents?.length || 0,
         file_changes: fileChanges,
-        edit_feedback: editFeedback
+        edit_feedback: editFeedback,
+        group_id: args.group_id || null,
+        group_label: args.group_label || null
       }
     }
 
@@ -265,7 +270,9 @@ export function createTaskDelegate({ config, parentSessionId, model, providerTyp
           stageId: args.stage_id || null,
           logicalTaskId: args.task_id || null,
           plannedFiles: Array.isArray(args.planned_files) ? args.planned_files : [],
-          allowQuestion: args.allow_question === true
+          allowQuestion: args.allow_question === true,
+          groupId: args.group_id || null,
+          groupLabel: args.group_label || null
         },
         config
       })
@@ -274,7 +281,9 @@ export function createTaskDelegate({ config, parentSessionId, model, providerTyp
         status: task.status,
         session_id: subSessionId,
         execution_mode: executionMode,
-        isolation
+        isolation,
+        group_id: args.group_id || null,
+        group_label: args.group_label || null
       }
     }
 

package/src/session/compaction.mjs

@@ -5,36 +5,36 @@ import { saveCheckpoint } from "./checkpoint.mjs"
 import { recordTurn } from "../usage/usage-meter.mjs"
 import { loadPricing, calculateCost } from "../usage/pricing.mjs"
 
-const COMPACTION_SYSTEM = `You are a conversation summarizer. Create a structured summary preserving all critical information for continued work.
+const COMPACTION_SYSTEM = `You are a conversation summarizer. Create a structured, merge-safe summary preserving all critical information for continued work.
 
 ## Output Format
 
+Return exactly:
+
+<context-state>
+{
+  "goal": "The user's current overall goal",
+  "completed": ["Completed work with specific file paths, function names, and line numbers"],
+  "in_progress": ["Current work being done"],
+  "files_modified": [{"path":"path/to/file","changes":["specific change"]}],
+  "key_decisions": ["Decision, constraint, or user preference"],
+  "errors_resolved": ["Error -> fix applied"],
+  "evidence": ["Important command output, test result, provider error, or exact failure detail"],
+  "next_steps": ["Specific next action item"]
+}
+</context-state>
+
 <summary>
-<goal>The user's overall goal or current task</goal>
-<completed>
-- Completed task with specific details (file paths, function names, line numbers)
-</completed>
-<in_progress>Current work being done, if any</in_progress>
-<files_modified>
-- path/to/file: specific change description
-</files_modified>
-<key_decisions>
-- Decision and reasoning
-- User preferences or constraints
-</key_decisions>
-<errors_resolved>
-- Error description → fix applied
-</errors_resolved>
-<next_steps>
-- Specific next action items
-</next_steps>
+Concise human-readable continuation summary.
 </summary>
 
 Rules:
 - Use the SAME LANGUAGE as the conversation
+- Merge the prior context state with the new conversation delta; do not summarize the prior state as another chat message
 - Preserve ALL file paths, function names, variable names, and technical identifiers exactly
 - Include specific code changes, not just "modified file X"
 - Omit tool call metadata and message formatting details
+- Preserve exact errors, failing test names, package versions, release labels, and user constraints in evidence
 - Be concise but never drop actionable information`
 
 const DEFAULT_THRESHOLD_MESSAGES = 50
@@ -42,6 +42,118 @@ const DEFAULT_THRESHOLD_RATIO = 0.7
 const DEFAULT_KEEP_RECENT = 6
 const DEFAULT_KEEP_RECENT_TURNS = 3
 const TOOL_RESULT_PREVIEW_LIMIT = 200
+const EVIDENCE_PREVIEW_LIMIT = 900
+const PATH_RE = /(?:^|\s)([A-Za-z0-9_.@~/-]+\.(?:mjs|js|ts|tsx|jsx|json|yaml|yml|md|txt|rs|go|py|sh|toml|lock))(?:[:\s]|$)/g
+const IMPORTANT_LINE_RE = /(error|failed|failure|exception|traceback|assert|reject|denied|unauthorized|context|compact|version|publish|npm|test|lint|typecheck|diff|modified)/i
+
+export function isCompactionSummaryMessage(msg) {
+  const content = msg?.content
+  if (typeof content === "string") return content.includes("<compaction-summary")
+  if (Array.isArray(content)) {
+    return content.some((block) => {
+      if (typeof block === "string") return block.includes("<compaction-summary")
+      return block?.type === "text" && typeof block.text === "string" && block.text.includes("<compaction-summary")
+    })
+  }
+  return false
+}
+
+export function extractCompactionSummary(content) {
+  const text = Array.isArray(content)
+    ? content.map((block) => typeof block === "string" ? block : (block?.text || block?.content || "")).join("\n")
+    : String(content || "")
+  const match = text.match(/<compaction-summary(?:\s[^>]*)?>\s*([\s\S]*?)\s*<\/compaction-summary>/i)
+  return (match ? match[1] : "").trim()
+}
+
+function clip(text, limit = EVIDENCE_PREVIEW_LIMIT) {
+  const raw = String(text || "")
+  if (raw.length <= limit) return raw
+  return raw.slice(0, limit) + "... [truncated " + raw.length + " chars]"
+}
+
+function extractPaths(text) {
+  const paths = new Set()
+  let match
+  PATH_RE.lastIndex = 0
+  while ((match = PATH_RE.exec(String(text || ""))) !== null) {
+    paths.add(match[1])
+    if (paths.size >= 12) break
+  }
+  return [...paths]
+}
+
+function importantLines(text, limit = 12) {
+  return String(text || "")
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter((line) => line && IMPORTANT_LINE_RE.test(line))
+    .slice(0, limit)
+}
+
+export function collectEvidenceLedger(messages, previewLimit = EVIDENCE_PREVIEW_LIMIT) {
+  const evidence = []
+  for (const msg of messages) {
+    const content = msg.content
+    const blocks = Array.isArray(content) ? content : [{ type: "text", text: content }]
+    for (const block of blocks) {
+      const raw = String(block?.content || block?.text || "")
+      if (!raw) continue
+      if (block.type === "tool_result") {
+        const lines = importantLines(raw)
+        const paths = extractPaths(raw)
+        if (block.is_error || lines.length || paths.length) {
+          evidence.push([
+            "- role=" + msg.role + " tool_result" + (block.is_error ? " ERROR" : ""),
+            paths.length ? "  paths: " + paths.join(", ") : "",
+            lines.length ? "  key_lines:\n" + lines.map((line) => "    " + clip(line, 220)).join("\n") : "  preview: " + clip(raw, previewLimit)
+          ].filter(Boolean).join("\n"))
+        }
+      } else if (typeof content === "string" && raw.length > 1000) {
+        const lines = importantLines(raw)
+        const paths = extractPaths(raw)
+        if (lines.length || paths.length) {
+          evidence.push([
+            "- role=" + msg.role + " long_text",
+            paths.length ? "  paths: " + paths.join(", ") : "",
+            lines.length ? "  key_lines:\n" + lines.map((line) => "    " + clip(line, 220)).join("\n") : ""
+          ].filter(Boolean).join("\n"))
+        }
+      }
+      if (evidence.length >= 20) return evidence
+    }
+  }
+  return evidence
+}
+
+export function buildCompactionPrompt({ previousSummary = "", messages, evidence = [] }) {
+  const transcript = messages.map((m) => {
+    const content = m.content
+    if (Array.isArray(content)) {
+      return "[" + m.role + "]: " + content.map((b) => {
+        if (b.type === "text") return b.text || ""
+        if (b.type === "tool_use") return "[tool_use:" + b.name + "(" + JSON.stringify(b.input || {}).slice(0, 120) + ")]"
+        if (b.type === "tool_result") return "[tool_result:" + (b.is_error ? "ERROR " : "") + (b.content || "") + "]"
+        return ""
+      }).filter(Boolean).join("\n")
+    }
+    return "[" + m.role + "]: " + content
+  }).join("\n\n")
+
+  return [
+    "<prior-context-state>",
+    previousSummary || "No prior compacted context.",
+    "</prior-context-state>",
+    "",
+    "<evidence-ledger>",
+    evidence.length ? evidence.join("\n") : "No extracted evidence ledger.",
+    "</evidence-ledger>",
+    "",
+    "<conversation-delta>",
+    transcript,
+    "</conversation-delta>"
+  ].join("\n")
+}
 
 // Estimate tokens from a string, accounting for CJK characters (~1.5 chars/token vs ~4 for Latin)
 export function estimateStringTokens(str) {
@@ -193,8 +305,12 @@ export async function compactSession({
   baseUrl = null,
   apiKeyEnv = null
 }) {
-  const history = await getConversationHistory(sessionId, 9999)
+  const history = await getConversationHistory(sessionId, 9999, { includeMetadata: true })
   if (history.length <= keepRecent + 2) return { compacted: false, reason: "too few messages" }
+  const previousSummary = isCompactionSummaryMessage(history[0])
+    ? extractCompactionSummary(history[0].content)
+    : ""
+  const workingHistory = previousSummary ? history.slice(1) : history
 
   // Turn-based split: keep last keepRecentTurns complete turns
   // A "turn" = one user interaction cycle (user msg + model response + all tool calls)
@@ -202,7 +318,7 @@ export async function compactSession({
   let splitIdx
   const turnIds = []
   const seenTurns = new Set()
-  for (const msg of history) {
+  for (const msg of workingHistory) {
     if (msg.turnId && !seenTurns.has(msg.turnId)) {
       seenTurns.add(msg.turnId)
       turnIds.push(msg.turnId)
@@ -210,29 +326,19 @@ export async function compactSession({
   }
   if (turnIds.length > keepRecentTurns) {
     const keepFromTurnId = turnIds[turnIds.length - keepRecentTurns]
-    splitIdx = history.findIndex(msg => msg.turnId === keepFromTurnId)
-    if (splitIdx < 0) splitIdx = history.length - keepRecent
+    splitIdx = workingHistory.findIndex(msg => msg.turnId === keepFromTurnId)
+    if (splitIdx < 0) splitIdx = workingHistory.length - keepRecent
   } else {
     // Fallback: not enough turns, use message count
-    splitIdx = history.length - keepRecent
+    splitIdx = workingHistory.length - keepRecent
   }
-  const toSummarize = history.slice(0, splitIdx)
-  const kept = history.slice(splitIdx)
+  const toSummarize = workingHistory.slice(0, splitIdx)
+  const kept = workingHistory.slice(splitIdx)
 
-  // Layer 1: prune large tool outputs before sending to LLM
+  // Layer 1: extract exact evidence, then prune large tool outputs before sending to LLM
+  const evidence = collectEvidenceLedger(toSummarize)
   const pruned = pruneForSummary(toSummarize)
-  const summaryPrompt = pruned.map((m) => {
-    const content = m.content
-    if (Array.isArray(content)) {
-      return `[${m.role}]: ${content.map((b) => {
-        if (b.type === "text") return b.text || ""
-        if (b.type === "tool_use") return `[tool_use:${b.name}(${JSON.stringify(b.input || {}).slice(0, 120)})]`
-        if (b.type === "tool_result") return `[tool_result:${b.is_error ? "ERROR " : ""}${b.content || ""}]`
-        return ""
-      }).filter(Boolean).join("\n")}`
-    }
-    return `[${m.role}]: ${content}`
-  }).join("\n\n")
+  const summaryPrompt = buildCompactionPrompt({ previousSummary, messages: pruned, evidence })
 
   const hookPayload = await HookBus.sessionCompacting({
     sessionId,
@@ -266,7 +372,7 @@ export async function compactSession({
   // Replace all messages with: [summary] + [kept recent messages]
   const summaryMessage = {
     role: "user",
-    content: `<compaction-summary>\n${summaryText}\n</compaction-summary>`
+    content: `<compaction-summary version="2">\n${summaryText}\n</compaction-summary>`
   }
   await replaceMessages(sessionId, [summaryMessage, ...kept])
 
@@ -285,8 +391,10 @@ export async function compactSession({
     compactedAt: Date.now(),
     summarizeCount: toSummarize.length,
     keepCount: kept.length,
-    summaryVersion: 1,
-    summaryLength: summaryText.length
+    summaryVersion: 2,
+    summaryLength: summaryText.length,
+    previousSummaryLength: previousSummary.length,
+    evidenceCount: evidence.length
   })
 
   return {

package/src/session/store.mjs

@@ -323,7 +323,7 @@ export async function listSessions({ cwd = null, limit = 100, includeChildren =
   })
 }
 
-export async function getConversationHistory(sessionId, limit = 30) {
+export async function getConversationHistory(sessionId, limit = 30, options = {}) {
   return withLock(async () => {
     await ensureLoadedUnsafe()
     const data = await loadSessionDataUnsafe(sessionId)
@@ -339,10 +339,19 @@ export async function getConversationHistory(sessionId, limit = 30) {
     const sliced = firstIsCompaction
       ? [msgs[0], ...msgs.slice(1).slice(-limit)]
       : msgs.slice(-limit)
-    return sliced.map((msg) => ({
-      role: msg.role,
-      content: msg.content
-    }))
+    return sliced.map((msg) => {
+      const base = {
+        role: msg.role,
+        content: msg.content
+      }
+      if (!options.includeMetadata) return base
+      return {
+        ...base,
+        turnId: msg.turnId,
+        step: msg.step,
+        synthetic: msg.synthetic
+      }
+    })
   })
 }
 

package/src/session/system-prompt.mjs

@@ -97,7 +97,7 @@ export async function agentPrompt(agent) {
 // Layer 4: Mode reminder (stable within mode)
 export async function modeReminder(mode) {
   const contractBlock = renderPublicModeContract()
-  if (mode === "assistant") return `${contractBlock}\n\nAssistant mode active. Treat this as the default CLI personal assistant lane for bounded terminal-native work: local files, logs, system checks, web lookup, Git/GitHub assistance, notes, task organization, and lightweight automation. Escalate to agent/code for explicit coding mutations and to longagent for staged multi-file delivery.`
+  if (mode === "assistant") return `${contractBlock}\n\nAssistant mode active. Treat this as the default CLI personal assistant lane for bounded terminal-native work: local files, logs, system checks, web lookup, Git/GitHub assistance, notes, task organization, and lightweight automation. Escalate to agent/code for explicit coding mutations and to longagent for staged multi-file delivery. When the user explicitly asks to summon, call, delegate to, or run one or more subagents, you must use task for one subagent or task_group for multiple parallel subagents. Use inherit_context=true or execution_mode=fork_context only for read-only sidecar work that needs the parent transcript; use fresh_agent for implementation work.`
   if (mode === "plan") return `${contractBlock}\n\n${await loadSessionPrompt("plan.txt")}`
   if (mode === "agent") return `${contractBlock}\n\n${await loadSessionPrompt("agent.txt")}\n\nCoding lane active. Focus on inspect/patch/verify coding work, keep diffs small, and validate with the narrowest useful tests.`
   if (mode === "longagent") {
@@ -244,7 +244,7 @@ export async function buildSystemPromptBlocks({ mode, model, cwd, agent = null,
 
   // Block 5.5: Available sub-agents (stable — changes only when custom agents change)
   const allAgents = listAgents({ includeHidden: false })
-  const customSubagents = allAgents.filter((a) => a.mode === "subagent" && a._customAgent)
+  const customSubagents = allAgents.filter((a) => a.mode === "subagent" && a.hidden !== true)
   if (customSubagents.length) {
     const agentLines = customSubagents.map((a) => {
       const perms = a.permission === "readonly" ? " (read-only)" : a.permission === "full" ? " (full access)" : ""
@@ -254,7 +254,7 @@ export async function buildSystemPromptBlocks({ mode, model, cwd, agent = null,
       "# Available Sub-agents",
       "",
       "Delegate specialized work to these sub-agents using the `task` tool with `subagent_type` parameter.",
-      "Use sub-agents when a task is self-contained and would benefit from a specialist, or to save context window space.",
+      "Use sub-agents when a task is self-contained and would benefit from a specialist, to save context window space, or whenever the user explicitly asks for subagents. Use task_group for multiple independent lanes.",
       "",
       ...agentLines
     ].join("\n")

package/src/tool/prompt/task_group.txt

@@ -0,0 +1,10 @@
+Use `task_group` when the user explicitly asks for multiple subagents, parallel agents, separate specialist lanes, or a comparison between independent agent findings.
+
+Behavior:
+- Launches every lane as a background delegated task.
+- Returns a shared `group_id`, `group_label`, per-lane task ids, and a compact visualization payload.
+- Use `inherit_context=true` or `execution_mode="fork_context"` only for read-only sidecar work that needs the parent transcript.
+- Use `fresh_agent` for implementation or mutation work.
+- Provide `subagent_type`, `objective` or `prompt`, `write_scope`, and `deliverable` for each lane when possible.
+
+After launching a group, use `task_parallel`, `task_list`, or `task_output` to observe progress and collect results.

package/src/tool/prompt/task_parallel.txt

@@ -0,0 +1,3 @@
+Use task_parallel to inspect delegated background tasks grouped as parallel subagent lanes.
+
+It returns groups with group_id, group_label, aggregate status counts, active lane counts, and per-lane status/result previews. Use it after task_group or when summarizing concurrent subagent progress for the user.

package/src/tool/registry.mjs

@@ -8,7 +8,7 @@ import { pathToFileURL } from "node:url"
 import { atomicWriteFile, replaceInFileTransactional, replaceAllInFileTransactional, diffLineCount, buildStructuredPatch } from "./edit-transaction.mjs"
 import { withFileLock } from "./file-lock-manager.mjs"
 import { BackgroundManager } from "../orchestration/background-manager.mjs"
-import { createTaskTool } from "./task-tool.mjs"
+import { createTaskTool, createTaskGroupTool } from "./task-tool.mjs"
 import { McpRegistry } from "../mcp/registry.mjs"
 import { SkillRegistry } from "../skill/registry.mjs"
 import { askQuestionInteractive } from "./question-prompt.mjs"
@@ -881,6 +881,17 @@ function builtinTools(config) {
     }
   }
 
+
+  const taskParallelTool = {
+    name: "task_parallel",
+    description: "Show delegated background tasks grouped as parallel subagent lanes.",
+    inputSchema: { type: "object", properties: {}, required: [] },
+    async execute() {
+      const tasks = await BackgroundManager.list()
+      return BackgroundManager.summarizeParallel(tasks)
+    }
+  }
+
   const taskGetTool = {
     name: "task_get",
     description: "Retrieve one delegated background task summary and result payload by task_id.",
@@ -1570,7 +1581,7 @@ function builtinTools(config) {
   const gitTools = config?.git_auto?.enabled !== false ? gitAutoTools : []
   const gitFullAutoToolsList = config?.git_auto?.full_auto === true ? gitFullAutoTools : []
   
-  return [listTool, sysinfoTool, readTool, writeTool, editTool, patchTool, multieditTool, globTool, grepTool, bashTool, createTaskTool(), outputTool, cancelTool, taskListTool, taskGetTool, taskStopTool, taskOutputTool, todowriteTool, questionTool, skillTool, webfetchTool, websearchTool, codesearchTool, notebookeditTool, enterPlanTool, exitPlanTool, ...gitTools, ...gitFullAutoToolsList]
+  return [listTool, sysinfoTool, readTool, writeTool, editTool, patchTool, multieditTool, globTool, grepTool, bashTool, createTaskTool(), createTaskGroupTool(), outputTool, cancelTool, taskListTool, taskParallelTool, taskGetTool, taskStopTool, taskOutputTool, todowriteTool, questionTool, skillTool, webfetchTool, websearchTool, codesearchTool, notebookeditTool, enterPlanTool, exitPlanTool, ...gitTools, ...gitFullAutoToolsList]
 }
 
 function mcpTools() {
@@ -1593,7 +1604,7 @@ function mcpTools() {
 
 function toolAllowedByMode(toolName, mode) {
   if (mode === "plan") {
-    return !["write", "edit", "patch", "multiedit", "notebookedit", "bash", "task", "git_snapshot", "git_restore", "git_apply_patch", "git_delete_snapshot"].includes(toolName)
+    return !["write", "edit", "patch", "multiedit", "notebookedit", "bash", "task", "task_group", "git_snapshot", "git_restore", "git_apply_patch", "git_delete_snapshot"].includes(toolName)
   }
   return true
 }

package/src/tool/task-tool.mjs

@@ -1,36 +1,90 @@
+function taskProperties() {
+  return {
+    prompt: { type: "string", description: "self-contained task brief for the delegated subagent" },
+    objective: { type: "string", description: "primary outcome to achieve when synthesizing a delegation brief" },
+    why: { type: "string", description: "context or decision pressure behind the delegated work" },
+    write_scope: { type: "string", description: "explicit write scope such as read-only, specific files, or no mutations" },
+    description: { type: "string", description: "short task description for background task tracking" },
+    subagent_type: { type: "string", description: "explicit subagent type" },
+    category: { type: "string", description: "routing category" },
+    session_id: { type: "string", description: "continue from an existing delegated sub-session instead of starting fresh" },
+    stage_id: { type: "string", description: "optional stage id for orchestration" },
+    task_id: { type: "string", description: "optional logical task id" },
+    group_id: { type: "string", description: "optional parallel group id for related delegated tasks" },
+    group_label: { type: "string", description: "optional human-readable parallel group label" },
+    starting_points: { type: "array", items: { type: "string" }, description: "relevant files, symbols, tests, or commands the subagent should start from" },
+    constraints: { type: "array", items: { type: "string" }, description: "architectural boundaries, forbidden edits, or safety constraints for the delegated run" },
+    deliverable: { type: "string", description: "expected output from the subagent, such as a patch, findings, or a concise summary" },
+    execution_mode: { type: "string", enum: ["fresh_agent", "fork_context"], description: "delegation mode: fresh_agent for isolated work, fork_context for read-only sidecars that inherit the parent transcript" },
+    inherit_context: { type: "boolean", description: "shortcut for execution_mode=fork_context; only valid for read-only sidecar work" },
+    isolation: { type: "string", enum: ["default", "worktree"], description: "execution isolation for delegated work" },
+    run_in_background: { type: "boolean", description: "run async in background for non-blocking sidecar work" },
+    planned_files: { type: "array", items: { type: "string" }, description: "planned files for this task" },
+    allow_question: { type: "boolean", description: "allow question tool during delegated run; foreground only" }
+  }
+}
+
+function newGroupId() {
+  return "grp_" + Date.now().toString(36) + "_" + Math.random().toString(36).slice(2, 8)
+}
+
 export function createTaskTool() {
   return {
     name: "task",
-    description: "Delegate complex multi-step work to a subagent that makes its own LLM calls. Prefer staying local for simple edits or critical-path work that immediately depends on your next action. New delegated runs start with fresh context unless you explicitly set execution_mode='fork_context' or continue an existing sub-session via session_id. `fork_context` is reserved for read-only sidecar work such as audits, reviews, and follow-up verification. You may provide either a fully written prompt or structured brief fields (objective/why/write_scope/starting_points/constraints/deliverable) for kkcode to synthesize a directive delegation brief. IMPORTANT: Do NOT use this for simple file operations — use 'write' to create files and 'edit' to modify files directly. Background tasks (run_in_background) spawn a separate worker process for sidecar work, cannot ask interactive questions, and must be observed via deterministic status/result retrieval.",
+    description: "Delegate complex multi-step work to a subagent that makes its own LLM calls. Use inherit_context=true or execution_mode=fork_context for read-only sidecars that need the parent transcript. Background tasks spawn a separate worker process and must be observed via task_list/task_output.",
+    inputSchema: { type: "object", properties: taskProperties(), required: [] },
+    async execute(args, ctx) {
+      if (typeof ctx.delegateTask === "function") return ctx.delegateTask(args || {})
+      return { error: "task delegate unavailable" }
+    }
+  }
+}
+
+export function createTaskGroupTool() {
+  return {
+    name: "task_group",
+    description: "Launch multiple delegated subagents as one parallel background group. Use this when the user explicitly asks to summon multiple agents, run agents in parallel, split research/review/verification lanes, or compare independent specialist findings.",
     inputSchema: {
       type: "object",
       properties: {
-        prompt: { type: "string", description: "self-contained task brief for the delegated subagent" },
-        objective: { type: "string", description: "primary outcome to achieve when synthesizing a delegation brief" },
-        why: { type: "string", description: "context or decision pressure behind the delegated work" },
-        write_scope: { type: "string", description: "explicit write scope such as read-only, specific files, or no mutations" },
-        starting_points: { type: "array", items: { type: "string" }, description: "relevant files, symbols, tests, or commands the subagent should start from" },
-        constraints: { type: "array", items: { type: "string" }, description: "architectural boundaries, forbidden edits, or safety constraints for the delegated run" },
-        deliverable: { type: "string", description: "expected output from the subagent, such as a patch, findings, or a concise summary" },
-        description: { type: "string", description: "short task description for background task tracking" },
-        subagent_type: { type: "string", description: "explicit subagent type" },
-        category: { type: "string", description: "routing category" },
-        execution_mode: { type: "string", enum: ["fresh_agent", "fork_context"], description: "delegation mode: 'fresh_agent' (default) for implementation or isolated new work, or 'fork_context' for read-only sidecar work that must inherit the parent transcript" },
-        isolation: { type: "string", enum: ["default", "worktree"], description: "execution isolation: 'default' runs in the main workspace, 'worktree' creates a local detached git worktree for isolated background sidecar execution" },
-        run_in_background: { type: "boolean", description: "run async in background for non-blocking sidecar work; background delegates cannot ask interactive questions" },
-        session_id: { type: "string", description: "continue from an existing delegated sub-session instead of starting fresh" },
-        stage_id: { type: "string", description: "optional stage id for orchestration" },
-        task_id: { type: "string", description: "optional logical task id" },
-        planned_files: { type: "array", items: { type: "string" }, description: "planned files for this task" },
-        allow_question: { type: "boolean", description: "allow question tool during delegated run; foreground only, not supported for run_in_background=true" }
+        group_id: { type: "string", description: "optional stable parallel group id" },
+        group_label: { type: "string", description: "human-readable label for the parallel group" },
+        inherit_context: { type: "boolean", description: "default context inheritance for tasks that do not specify execution_mode" },
+        execution_mode: { type: "string", enum: ["fresh_agent", "fork_context"], description: "default execution mode for tasks" },
+        isolation: { type: "string", enum: ["default", "worktree"], description: "default isolation mode for tasks" },
+        tasks: { type: "array", description: "subagent tasks to launch in parallel", items: { type: "object", properties: taskProperties(), required: [] } }
       },
-      required: []
+      required: ["tasks"]
     },
     async execute(args, ctx) {
-      if (typeof ctx.delegateTask !== "function") {
-        return { error: "task delegate unavailable" }
+      if (typeof ctx.delegateTask !== "function") return { error: "task delegate unavailable" }
+      const tasks = Array.isArray(args?.tasks) ? args.tasks : []
+      if (tasks.length === 0) return { error: "task_group.tasks must contain at least one task" }
+      const groupId = String(args.group_id || newGroupId())
+      const groupLabel = String(args.group_label || "parallel subagents")
+      const results = []
+      for (let i = 0; i < tasks.length; i++) {
+        const task = tasks[i] || {}
+        const merged = {
+          ...task,
+          group_id: task.group_id || groupId,
+          group_label: task.group_label || groupLabel,
+          run_in_background: true,
+          inherit_context: task.inherit_context ?? args.inherit_context,
+          execution_mode: task.execution_mode || args.execution_mode,
+          isolation: task.isolation || args.isolation || "default",
+          description: task.description || task.objective || task.prompt || groupLabel,
+          task_id: task.task_id || "lane_" + (i + 1)
+        }
+        results.push(await ctx.delegateTask(merged))
+      }
+      return {
+        group_id: groupId,
+        group_label: groupLabel,
+        status: results.some((r) => r?.error) ? "partial_error" : "launched",
+        tasks: results,
+        visualization: results.map((result, index) => ({ lane: index + 1, task_id: result.background_task_id || null, subagent: tasks[index]?.subagent_type || tasks[index]?.category || "default-subagent", status: result.status || (result.error ? "error" : "unknown"), session_id: result.session_id || null, error: result.error || null }))
       }
-      return ctx.delegateTask(args || {})
     }
   }
 }

package/src/ui/repl-background-panel.mjs

@@ -1,7 +1,12 @@
 export function renderBackgroundSummaryPanel(backgroundSummary) {
   if (!backgroundSummary) return []
-  return [
+  const groups = Array.isArray(backgroundSummary.parallel_groups) ? backgroundSummary.parallel_groups : []
+  const activeGroups = groups.filter((group) => Number(group.active || 0) > 0).length
+  const activeLanes = groups.reduce((sum, group) => sum + Number(group.active || 0), 0)
+  const lines = [
     `background=${backgroundSummary.active} active (pending:${backgroundSummary.counts.pending}, running:${backgroundSummary.counts.running})`,
     `background.terminal=completed:${backgroundSummary.counts.completed} interrupted:${backgroundSummary.counts.interrupted} error:${backgroundSummary.counts.error}`
   ]
+  if (groups.length) lines.push(`parallel=${activeGroups} active group(s), ${activeLanes} active lane(s)`)
+  return lines
 }

package/src/version.mjs

@@ -1,3 +1,3 @@
 export const PACKAGE_NAME = "@kkelly-offical/kkcode"
-export const PACKAGE_VERSION = "0.2.3-preview.1"
-export const RELEASE_LABEL = "0.2.3 Preview V1"
+export const PACKAGE_VERSION = "0.2.3"
+export const RELEASE_LABEL = "0.2.3"