opencode-matrixx-v2 1.1.0 → 1.2.1

package/dist/cli/doctor/checks/context-mode.d.ts

@@ -26,5 +26,14 @@ export declare function evaluateContextModeToolCompat(toolNames: string[]): Chec
  * those sources instead of warning.
  */
 export declare function evaluateContextModeCwd(server: unknown, source?: "mcp" | "local" | "registry" | string): CheckResult;
+export declare const CONTEXT_MODE_VERSION_FLOOR = "2.1.0";
+/**
+ * Pure floor check: major.minor numeric compare against 2.1.
+ * Prerelease suffixes (e.g. 2.1.0-next) are stripped before parsing;
+ * null/unparsable versions fail-open to false (never blocks doctor).
+ */
+export declare function isContextModeVersionBelowFloor(version: string | null | undefined): boolean;
+/** Pure evaluator for the discipline version floor. Below 2.1.0 warns. */
+export declare function evaluateContextModeVersion(version: string | null | undefined): CheckResult;
 export declare const contextModeCwdCheck: DoctorCheck;
 export declare const contextModeCheck: DoctorCheck;

package/dist/cli.js

@@ -7235,6 +7235,22 @@ function loadContextModeMcpServer() {
   }
   return;
 }
+var CONTEXT_MODE_VERSION_FLOOR = "2.1.0";
+function isContextModeVersionBelowFloor(version) {
+  if (typeof version !== "string" || version.length === 0)
+    return false;
+  const core = version.replace(/^[vV]/, "").split("-")[0] ?? "";
+  const parts = core.split(".");
+  const major = Number(parts[0]);
+  const minor = parts.length > 1 ? Number(parts[1]) : 0;
+  if (!Number.isFinite(major) || !Number.isFinite(minor))
+    return false;
+  if (major < 2)
+    return true;
+  if (major > 2)
+    return false;
+  return minor < 1;
+}
 var contextModeCwdCheck = {
   name: "context-mode-cwd",
   category: "integrations",
@@ -7269,13 +7285,16 @@ Cache dir: ${cacheDir} ${hasCache ? "(exists)" : "(not found \u2014 will be crea
     const substituteLine = discipline.path ? `Substitute-File: ${discipline.path}${discipline.version ? ` (v${discipline.version})` : ""}` : "Substitute-File: not found \u2014 fallback table in use; enforcer treats grep/glob as unblocked";
     const ctxTools = isCtxToolsAvailable();
     const ctxToolsLine = ctxTools ? "Ctx-Tools: available" : "Ctx-Tools: unavailable \u2014 enforcer fail-opens (warn-only)";
+    const belowFloor = isContextModeVersionBelowFloor(discipline.version);
+    const floorLine = belowFloor ? `Version-Floor: v${discipline.version} below supported floor v${CONTEXT_MODE_VERSION_FLOOR} \u2014 upgrade context-mode to >=${CONTEXT_MODE_VERSION_FLOOR} (any 2.1.x)` : null;
     return {
       name: "context-mode-integration",
-      status: !discipline.path || !ctxTools ? "warn" : "pass",
-      message: `context-mode plugin registered${hasCache ? ", cache present" : " (cache not yet created)"}${discipline.version ? `, discipline v${discipline.version}` : ""}`,
+      status: !discipline.path || !ctxTools || belowFloor ? "warn" : "pass",
+      message: `context-mode plugin registered${hasCache ? ", cache present" : " (cache not yet created)"}${discipline.version ? `, discipline v${discipline.version}` : ""}${belowFloor ? ` (below floor v${CONTEXT_MODE_VERSION_FLOOR})` : ""}`,
       detail: `Cache: ${cacheDir}
 ${substituteLine}
-${ctxToolsLine}
+${ctxToolsLine}${floorLine ? `
+${floorLine}` : ""}
 Plan tools: plan_create/read/update/list/delete (unconditional)`
     };
   }

package/dist/hooks/auto-update-checker/hook/mcp-startup-toast.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Surface disabled-MCP startup failures as a user-visible warning on the
+ * session-created path. Silent when the startup state holds no failures.
+ */
+export declare function showMcpStartupNoticeIfAny(): Promise<void>;

package/dist/hooks/category-skill-reminder/detector.d.ts

@@ -0,0 +1,13 @@
+export interface NudgeInput {
+    tool: string;
+    sessionID: string;
+    agent?: string;
+    toolCallCount: number;
+    delegationUsed: boolean;
+    reminderShown: boolean;
+}
+export interface NudgeEvent {
+    skill: string;
+    reason: string;
+}
+export declare function detectNudge(input: NudgeInput): NudgeEvent | null;

package/dist/hooks/category-skill-reminder/formatter.d.ts

@@ -1,2 +1,7 @@
 import type { AvailableSkill } from "../../agents/dynamic-agent-prompt-builder";
 export declare function buildReminderMessage(availableSkills: AvailableSkill[]): string;
+export interface NudgeMessageEvent {
+    skill: string;
+    reason: string;
+}
+export declare function buildNudgeMessage(event: NudgeMessageEvent): string;

package/dist/hooks/category-skill-reminder/hook.d.ts

@@ -1,5 +1,7 @@
 import type { AvailableSkill } from "../../agents/dynamic-agent-prompt-builder";
 import type { MatrixxContext } from "../../plugin/context";
+export type { NudgeEvent, NudgeInput } from "./detector";
+export { detectNudge } from "./detector";
 interface ToolExecuteInput {
     tool: string;
     sessionID: string;
@@ -11,9 +13,11 @@ interface ToolExecuteOutput {
     output: string;
     metadata: unknown;
 }
+export interface CategorySkillReminderOptions {
+    now?: () => number;
+}
 import type { V2Event } from "../../plugin/context";
-export declare function createCategorySkillReminderHook(ctx: MatrixxContext, availableSkills?: AvailableSkill[]): {
+export declare function createCategorySkillReminderHook(ctx: MatrixxContext, availableSkills?: AvailableSkill[], options?: CategorySkillReminderOptions): {
     "tool.execute.after": (input: ToolExecuteInput, output: ToolExecuteOutput) => Promise<void>;
     event: (event: V2Event) => Promise<void>;
 };
-export {};

package/dist/index.js

@@ -26192,7 +26192,7 @@ function buildInlineConfig(profile, options) {
   const commands = merged.commands ?? {};
   const manualMode = merged.manualMode ?? {};
   return {
-    $schema: "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/v3.1.14/dcp.schema.json",
+    $schema: "https://raw.githubusercontent.com/Opencode-DCP/opencode-dynamic-context-pruning/v3.2.0/dcp.schema.json",
     enabled: true,
     autoUpdate: merged.autoUpdate ?? false,
     debug: merged.debug ?? false,
@@ -33784,13 +33784,17 @@ async function registerCommandTransform(command, entries, deps) {
 }
 
 // src/mcps/context7.ts
-var context7 = {
-  type: "remote",
-  url: "https://mcp.context7.com/mcp",
-  enabled: true,
-  headers: process.env.CONTEXT7_API_KEY ? { Authorization: `Bearer ${process.env.CONTEXT7_API_KEY}` } : undefined,
-  oauth: false
-};
+function buildContext7Entry(input = {}) {
+  const key = input.context7ApiKey;
+  return {
+    type: "remote",
+    url: "https://mcp.context7.com/mcp",
+    enabled: true,
+    headers: key ? { Authorization: `Bearer ${key}` } : undefined,
+    oauth: false
+  };
+}
+var context7 = buildContext7Entry();
 
 // src/mcps/document-reader.ts
 var document_reader = {
@@ -33810,7 +33814,7 @@ function buildBuiltinMcpEntries(input) {
   const entries = {};
   const failures = [];
   if (!disabledMcps.includes("context7")) {
-    entries.context7 = context7;
+    entries.context7 = buildContext7Entry({ context7ApiKey: input.context7ApiKey || undefined });
   }
   if (!disabledMcps.includes("document_reader")) {
     if (input.uvxAvailable) {
@@ -37962,7 +37966,7 @@ What is the user asking about?
 
 // src/skills/skills/document-reader.ts
 var DOCUMENT_READER_SKILL_NAME = "document-reader";
-var DOCUMENT_READER_SKILL_DESCRIPTION = "Use when reading PDFs, extracting content from documents, or analyzing office files (DOCX, XLSX, PPTX) \u2014 document conversion via document_reader MCP convert_to_markdown supporting file: and https: URIs for local and remote files. Related: ulw-research, dev-browser.";
+var DOCUMENT_READER_SKILL_DESCRIPTION = "Use when reading PDFs, extracting content from documents, or analyzing office files (DOCX, XLSX, PPTX) \u2014 document conversion via document_reader MCP document_reader__convert_to_markdown supporting file: and https: URIs for local and remote files. Related: ulw-research, dev-browser.";
 var documentReaderSkill = {
   name: DOCUMENT_READER_SKILL_NAME,
   description: DOCUMENT_READER_SKILL_DESCRIPTION,
@@ -38009,7 +38013,7 @@ uri: "https://example.com/data.xlsx"
 
 ## MUST NOT DO
 
-- Do NOT guess file contents \u2014 always call \`convert_to_markdown\` first
+- Do NOT guess file contents \u2014 always call \`document_reader__convert_to_markdown\` first
 - Do NOT use the Read tool for PDFs or Office files \u2014 it cannot parse binary formats
 - Do NOT pass a relative path like \`file://./report.pdf\` \u2014 always use absolute paths
 `
@@ -47681,7 +47685,7 @@ task(
 Research documentation and knowledge base files related to: <CURRENT_LEAD>
 
 Read AGENTS.md files, README.md, doc/ directories, and inline documentation.
-For library/framework docs delegate via task(operator) for context7 resolve\u2192query (resolve-library-id then query-docs); do NOT call context7 or websearch directly.
+For library/framework docs delegate via task(operator) for context7 resolve\u2192query (context7_resolve-library-id then context7_query-docs); do NOT call context7 or websearch directly.
 
 OUTPUT: Structured findings from docs with source attribution.
 Flag any claims that contradict other sources.
@@ -56639,7 +56643,30 @@ var startupFailures = [];
 function setMcpStartupFailures(failures) {
   startupFailures = failures;
 }
+function getMcpStartupFailures() {
+  return startupFailures;
+}
 
+// src/mcps/mcp-startup-notice.ts
+var MCP_UVX_INSTALL_FIX = "curl -LsSf https://astral.sh/uv/install.sh | sh";
+var MCP_UVX_WARM_FIX = "uvx --from markitdown-mcp markitdown-mcp --help";
+function buildFailureLine(failure) {
+  if (failure.name === "document_reader") {
+    return "[mcp-startup] document_reader MCP is disabled: uvx (uv package manager) not found in PATH, " + `so document_reader__convert_to_markdown is unavailable.
+` + `\u2192 fix: Install uv/uvx: ${MCP_UVX_INSTALL_FIX}
+` + `Then warm cache: ${MCP_UVX_WARM_FIX}`;
+  }
+  return `[mcp-startup] ${failure.name} MCP is disabled: ${failure.error}`;
+}
+function buildMcpStartupNotice(failures) {
+  if (failures.length === 0)
+    return;
+  return failures.map(buildFailureLine).join(`
+`);
+}
+function getMcpStartupNotice() {
+  return buildMcpStartupNotice(getMcpStartupFailures());
+}
 // src/plugin-handlers/mcp-config-handler.ts
 function captureUserDisabledMcps(userMcp) {
   const disabled = new Set;
@@ -56656,9 +56683,11 @@ async function applyMcpConfig(params) {
   const disabledMcps = params.pluginConfig.disabled_mcps ?? [];
   const userMcp = params.config.mcp;
   const userDisabledMcps = captureUserDisabledMcps(userMcp);
+  const context7ApiKey = process.env.CONTEXT7_API_KEY || undefined;
   const { entries: builtinMcps, failures } = buildBuiltinMcpEntries({
     disabledMcps,
-    uvxAvailable: isCommandAvailable("uvx")
+    uvxAvailable: isCommandAvailable("uvx"),
+    context7ApiKey
   });
   const merged = {
     ...builtinMcps,
@@ -56678,6 +56707,9 @@ async function applyMcpConfig(params) {
     const summary = failures.map((f) => `${f.name}: ${f.error}`).join("; ");
     log(`[mcp-config] MCP startup issues detected: ${summary}`, failures);
     setMcpStartupFailures(failures);
+    const notice = buildMcpStartupNotice(failures);
+    if (notice)
+      log(notice);
   }
   params.config.mcp = merged;
 }
@@ -72286,88 +72318,6 @@ function describeLastMessageParts(messages) {
   return textOf(last).length > 0 ? "text" : "none";
 }
 
-// src/tools/delegate-task/sync-result-fetcher.ts
-function messageText(msg) {
-  const textParts = contentOf(msg).filter((p) => p.type === "text" || p.type === "reasoning");
-  const raw = textParts.map((p) => p.text ?? "").filter(Boolean).join(`
-`);
-  return raw.replace(/<analysis>[\s\S]*?<\/analysis>/gi, "").trim();
-}
-function messageFinalText(msg) {
-  const text = messageText(msg);
-  const trimmed = text.trim();
-  if (trimmed.startsWith("```") && trimmed.endsWith("```")) {
-    const inner = trimmed.slice(3, -3).trim();
-    const firstNewline = inner.indexOf(`
-`);
-    if (firstNewline > 0 && firstNewline < 100) {
-      return inner.slice(firstNewline + 1).trim();
-    }
-    return inner;
-  }
-  return trimmed;
-}
-function extractTaggedDeliverable(messages, tag) {
-  const tagStart = `<${tag}>`;
-  const tagEnd = `</${tag}>`;
-  for (let i = messages.length - 1;i >= 0; i--) {
-    const msg = messages[i];
-    if (!isAssistant(msg))
-      continue;
-    const text = messageText(msg);
-    const startIdx = text.indexOf(tagStart);
-    if (startIdx === -1)
-      continue;
-    const endIdx = text.indexOf(tagEnd, startIdx + tagStart.length);
-    if (endIdx === -1)
-      continue;
-    return {
-      message: msg,
-      text: text.slice(startIdx + tagStart.length, endIdx).trim()
-    };
-  }
-  return;
-}
-async function fetchSyncResult(client, sessionID, anchorMessageCount, options) {
-  const messages = await fetchSessionMessages(client, sessionID);
-  const messagesAfterAnchor = anchorMessageCount !== undefined ? messages.slice(anchorMessageCount) : messages;
-  if (anchorMessageCount !== undefined && messagesAfterAnchor.length === 0) {
-    return {
-      ok: false,
-      error: `Session completed with no new messages after the anchor. Observed: ${describeMessageShape(messages)}. ${DIAGNOSTIC_CAUSES}
-
-Session ID: ${sessionID}`
-    };
-  }
-  if (options?.deliverableTag) {
-    const tagged = extractTaggedDeliverable(messagesAfterAnchor, options.deliverableTag);
-    if (tagged) {
-      const textContent = options.finalTextOnly ? messageFinalText(tagged.message) : tagged.text;
-      return { ok: true, textContent };
-    }
-  }
-  const assistantMessages = messagesAfterAnchor.filter((m) => isAssistant(m)).sort((a, b) => timeOf(b) - timeOf(a));
-  const lastMessage = assistantMessages[0];
-  if (anchorMessageCount !== undefined && !lastMessage) {
-    return {
-      ok: false,
-      error: `Session completed with no new assistant message. Observed: ${describeMessageShape(messagesAfterAnchor)}. ${DIAGNOSTIC_CAUSES}
-
-Session ID: ${sessionID}`
-    };
-  }
-  if (!lastMessage) {
-    return {
-      ok: false,
-      error: `No assistant response found. Observed: ${describeMessageShape(messages)}. ${DIAGNOSTIC_CAUSES}
-
-Session ID: ${sessionID}`
-    };
-  }
-  const textContent = options?.finalTextOnly ? messageFinalText(lastMessage) : messageText(lastMessage);
-  return { ok: true, textContent };
-}
-
 // src/shared/poll-timeout-outcome.ts
 var POLL_TIMEOUT_PREFIX = "Poll timeout reached";
 var LAST_ASSISTANT_TEXT_CAP = 2000;
@@ -72417,6 +72367,26 @@ function createdAtOf(message) {
   const created = timeOf(message);
   return created === 0 ? undefined : created;
 }
+function completedOf(message) {
+  const completed = message?.time?.completed;
+  return typeof completed === "number" && completed > 0 ? completed : undefined;
+}
+function isStreamingAssistant(message, messages) {
+  if (!message || !isAssistant(message))
+    return false;
+  const hostPublishesCompletion = messages.some((candidate) => isAssistant(candidate) && completedOf(candidate) !== undefined);
+  if (!hostPublishesCompletion)
+    return false;
+  return completedOf(message) === undefined;
+}
+function strippedAssistantText(message) {
+  return textOf(message).replace(/<analysis>[\s\S]*?<\/analysis>/gi, "").trim();
+}
+function lastAssistantHasText(message) {
+  if (!message)
+    return false;
+  return strippedAssistantText(message).length > 0;
+}
 function isSessionComplete(messages) {
   let lastUser;
   let lastAssistant;
@@ -72434,6 +72404,8 @@ function isSessionComplete(messages) {
     return false;
   if (NON_TERMINAL_FINISH_REASONS.has(finish))
     return false;
+  if (isStreamingAssistant(lastAssistant, messages))
+    return false;
   if (!lastUser)
     return false;
   const userTime = createdAtOf(lastUser);
@@ -72473,12 +72445,7 @@ function hasToolResultAfterAssistant(messages) {
   return userId > assistantId;
 }
 function hasAssistantContent(messages) {
-  return messages.some((m) => {
-    if (!isAssistant(m))
-      return false;
-    const stripped = textOf(m).replace(/<analysis>[\s\S]*?<\/analysis>/gi, "").trim();
-    return stripped.length > 0;
-  });
+  return messages.some((m) => isAssistant(m) && strippedAssistantText(m).length > 0);
 }
 async function pollSyncSession(ctx, client, input) {
   const syncTiming = getTimingConfig();
@@ -72531,6 +72498,12 @@ Session ID: ${input.sessionID}`;
       break;
     }
     const lastAssistant = [...msgs].reverse().find((m) => isAssistant(m));
+    if (isStreamingAssistant(lastAssistant, msgs)) {
+      idleStallCount = 0;
+      lastMsgCount = 0;
+      stableIdlePolls = 0;
+      continue;
+    }
     const hasText = hasAssistantContent(msgs);
     if (!finishOf(lastAssistant) && hasText) {
       const elapsed = Date.now() - pollStart;
@@ -72585,7 +72558,7 @@ Session ID: ${input.sessionID}`;
         break;
       }
     }
-    if (lastAssistant && msgs.length > 0 && Date.now() - pollStart >= syncTiming.MIN_STABILITY_TIME_MS) {
+    if (lastAssistant && msgs.length > 0 && Date.now() - pollStart >= syncTiming.MIN_STABILITY_TIME_MS && !isStreamingAssistant(lastAssistant, msgs) && lastAssistantHasText(lastAssistant)) {
       const currentMsgCount = msgs.length;
       if (currentMsgCount === lastMsgCount) {
         stableIdlePolls++;
@@ -72613,7 +72586,7 @@ Session ID: ${input.sessionID}`;
   let lastAssistantText;
   try {
     const timeoutMsgs = await fetchSessionMessages(client, input.sessionID);
-    const lastAssistant = [...timeoutMsgs].reverse().find((m) => isAssistant(m));
+    const lastAssistant = [...timeoutMsgs].reverse().find((m) => isAssistant(m) && !isStreamingAssistant(m, timeoutMsgs));
     const textParts = contentOf(lastAssistant).filter((p) => p.type === "text" && p.text).map((p) => p.text);
     if (textParts.length > 0)
       lastAssistantText = textParts.join(`
@@ -72629,6 +72602,99 @@ Session ID: ${input.sessionID}`;
   });
 }
 
+// src/tools/delegate-task/sync-result-fetcher.ts
+function messageText(msg) {
+  const textParts = contentOf(msg).filter((p) => p.type === "text" || p.type === "reasoning");
+  const raw = textParts.map((p) => p.text ?? "").filter(Boolean).join(`
+`);
+  return raw.replace(/<analysis>[\s\S]*?<\/analysis>/gi, "").trim();
+}
+function messageFinalText(msg) {
+  const text = messageText(msg);
+  const trimmed = text.trim();
+  if (trimmed.startsWith("```") && trimmed.endsWith("```")) {
+    const inner = trimmed.slice(3, -3).trim();
+    const firstNewline = inner.indexOf(`
+`);
+    if (firstNewline > 0 && firstNewline < 100) {
+      return inner.slice(firstNewline + 1).trim();
+    }
+    return inner;
+  }
+  return trimmed;
+}
+function extractTaggedDeliverable(messages, tag) {
+  const tagStart = `<${tag}>`;
+  const tagEnd = `</${tag}>`;
+  for (let i = messages.length - 1;i >= 0; i--) {
+    const msg = messages[i];
+    if (!isAssistant(msg))
+      continue;
+    const text = messageText(msg);
+    const startIdx = text.indexOf(tagStart);
+    if (startIdx === -1)
+      continue;
+    const endIdx = text.indexOf(tagEnd, startIdx + tagStart.length);
+    if (endIdx === -1)
+      continue;
+    return {
+      message: msg,
+      text: text.slice(startIdx + tagStart.length, endIdx).trim()
+    };
+  }
+  return;
+}
+async function fetchSyncResult(client, sessionID, anchorMessageCount, options) {
+  const messages = await fetchSessionMessages(client, sessionID);
+  const messagesAfterAnchor = anchorMessageCount !== undefined ? messages.slice(anchorMessageCount) : messages;
+  if (anchorMessageCount !== undefined && messagesAfterAnchor.length === 0) {
+    return {
+      ok: false,
+      error: `Session completed with no new messages after the anchor. Observed: ${describeMessageShape(messages)}. ${DIAGNOSTIC_CAUSES}
+
+Session ID: ${sessionID}`
+    };
+  }
+  const assistantMessages = messagesAfterAnchor.filter((m) => isAssistant(m)).sort((a, b) => timeOf(b) - timeOf(a));
+  const newestAssistant = assistantMessages[0];
+  const hostPublishesCompletion = messages.some((message) => isAssistant(message) && completedOf(message) !== undefined);
+  if (hostPublishesCompletion && isStreamingAssistant(newestAssistant, messages)) {
+    return {
+      ok: false,
+      error: `Session is still streaming its newest assistant message; the result is not complete yet. ${DIAGNOSTIC_CAUSES}
+
+Session ID: ${sessionID}`
+    };
+  }
+  const candidates = hostPublishesCompletion ? assistantMessages.filter((m) => completedOf(m) !== undefined) : assistantMessages;
+  if (options?.deliverableTag) {
+    const tagged = extractTaggedDeliverable(candidates, options.deliverableTag);
+    if (tagged) {
+      const textContent = options.finalTextOnly ? messageFinalText(tagged.message) : tagged.text;
+      return { ok: true, textContent };
+    }
+  }
+  const lastMessage = candidates.find((m) => messageText(m).length > 0) ?? candidates[0];
+  if (anchorMessageCount !== undefined && !lastMessage) {
+    return {
+      ok: false,
+      error: `Session completed with no new assistant message. Observed: ${describeMessageShape(messagesAfterAnchor)}. ${DIAGNOSTIC_CAUSES}
+
+Session ID: ${sessionID}`
+    };
+  }
+  if (!lastMessage) {
+    return {
+      ok: false,
+      error: `No assistant response found. Observed: ${describeMessageShape(messages)}. ${DIAGNOSTIC_CAUSES}
+
+Session ID: ${sessionID}`
+    };
+  }
+  const textContent = options?.finalTextOnly ? messageFinalText(lastMessage) : messageText(lastMessage);
+  return { ok: true, textContent };
+}
+
 // src/tools/delegate-task/sync-continuation-deps.ts
 var syncContinuationDeps = {
   pollSyncSession,
@@ -72727,11 +72793,20 @@ Session ID: ${continuationID}`;
       return result.error;
     }
     const duration = formatDuration(startTime);
+    const textContent = result.textContent.trim();
+    if (textContent.length === 0) {
+      return `Task returned no readable output (empty assistant text).
+
+Resume the same session instead of spawning a new one:
+  task(session_id="${continuationID}", prompt="...")
+
+Session ID: ${continuationID}`;
+    }
     return `Task continued and completed in ${duration}.
 
 ---
 
-${result.textContent || "(No text output)"}
+${textContent}
 
 <task_metadata>
 session_id: ${continuationID}
@@ -73031,13 +73106,22 @@ async function executeSyncTask(args, ctx, executorCtx, parentContext, agentToUse
       }
       didSucceed = true;
       const duration = formatDuration(startTime);
+      const textContent = result.textContent.trim();
+      if (textContent.length === 0) {
+        return `Task returned no readable output (empty assistant text).
+
+Resume the same session instead of spawning a new one:
+  task(session_id="${sessionID}", prompt="...")
+
+Session ID: ${sessionID}`;
+      }
       return `Task completed in ${duration}.
 
 Agent: ${agentToUse}${args.category ? ` (category: ${args.category})` : ""}
 
 ---
 
-${result.textContent || "(No text output)"}
+${textContent}
 
 <task_metadata>
 session_id: ${sessionID}
@@ -75958,6 +76042,14 @@ async function updateAndShowConnectedProvidersCacheStatus(_ctx) {
   }
 }
 
+// src/hooks/auto-update-checker/hook/mcp-startup-toast.ts
+async function showMcpStartupNoticeIfAny() {
+  const notice = getMcpStartupNotice();
+  if (!notice)
+    return;
+  notify("warn", notice);
+}
+
 // src/hooks/auto-update-checker/hook/model-cache-warning.ts
 async function showModelCacheWarningIfNeeded(_ctx) {
   if (isModelCacheAvailable())
@@ -76010,6 +76102,9 @@ v${latestVersion} available. Restart OpenCode to apply.` : "OpenCode is now on S
         return;
       hasChecked = true;
       setTimeout(async () => {
+        showMcpStartupNoticeIfAny().catch((err) => {
+          log("[auto-update-checker] MCP startup notice failed:", err);
+        });
         const cachedVersion = getCachedVersion();
         const localDevVersion = getLocalDevVersion(ctx.directory);
         const displayVersion = localDevVersion ?? cachedVersion;
@@ -76114,6 +76209,51 @@ function createBashFileReadGuardHook() {
     }
   };
 }
+// src/hooks/category-skill-reminder/detector.ts
+var TARGET_AGENTS = new Set([
+  "morpheus",
+  "mouse",
+  "niobe"
+]);
+var DELEGATABLE_WORK_TOOLS = new Set([
+  "edit",
+  "write",
+  "bash",
+  "shell",
+  "read",
+  "grep",
+  "glob"
+]);
+var NUDGE_THRESHOLD = 3;
+var NUDGE_SKILL = "construct";
+function isTargetAgent(sessionID, inputAgent) {
+  const agent = getSessionAgent(sessionID) ?? inputAgent;
+  if (!agent)
+    return false;
+  const agentKey = getAgentConfigKey(agent);
+  return TARGET_AGENTS.has(agentKey) || agentKey.includes("morpheus") || agentKey.includes("niobe");
+}
+function detectNudge(input) {
+  try {
+    if (subagentSessions.has(input.sessionID))
+      return null;
+    if (!isTargetAgent(input.sessionID, input.agent))
+      return null;
+    if (!DELEGATABLE_WORK_TOOLS.has(input.tool.toLowerCase()))
+      return null;
+    if (input.delegationUsed || input.reminderShown)
+      return null;
+    if (input.toolCallCount < NUDGE_THRESHOLD)
+      return null;
+    return {
+      skill: NUDGE_SKILL,
+      reason: `delegatable work without delegation (${input.toolCallCount} ${input.tool} calls)`
+    };
+  } catch {
+    return null;
+  }
+}
+
 // src/hooks/category-skill-reminder/formatter.ts
 function formatSkillNames(skills, limit) {
   if (skills.length === 0)
@@ -76149,12 +76289,12 @@ function buildReminderMessage(availableSkills) {
 }
 
 // src/hooks/category-skill-reminder/hook.ts
-var TARGET_AGENTS = new Set([
+var TARGET_AGENTS2 = new Set([
   "morpheus",
   "mouse",
   "niobe"
 ]);
-var DELEGATABLE_WORK_TOOLS = new Set([
+var DELEGATABLE_WORK_TOOLS2 = new Set([
   "edit",
   "write",
   "bash",
@@ -76167,6 +76307,7 @@ var DELEGATION_TOOLS = new Set([
   "task",
   "subagent"
 ]);
+var DEDUP_WINDOW_MS2 = 60000;
 function hashSnippet(value) {
   let hash = 5381;
   for (let i = 0;i < value.length; i++) {
@@ -76174,9 +76315,11 @@ function hashSnippet(value) {
   }
   return (hash >>> 0).toString(16);
 }
-function createCategorySkillReminderHook(ctx, availableSkills = []) {
+function createCategorySkillReminderHook(ctx, availableSkills = [], options = {}) {
   const sessionStates = new Map;
+  const lastNudgeAt = new Map;
   const reminderMessage = buildReminderMessage(availableSkills);
+  const now = options.now ?? Date.now;
   function getOrCreateState(sessionID) {
     if (!sessionStates.has(sessionID)) {
       sessionStates.set(sessionID, {
@@ -76187,58 +76330,103 @@ function createCategorySkillReminderHook(ctx, availableSkills = []) {
     }
     return sessionStates.get(sessionID);
   }
+  function clearSessionState(sessionID) {
+    sessionStates.delete(sessionID);
+  }
+  function clearSessionDedup(sessionID) {
+    const prefix = `${sessionID}:`;
+    for (const key of lastNudgeAt.keys()) {
+      if (key.startsWith(prefix))
+        lastNudgeAt.delete(key);
+    }
+  }
   function isTargetAgent(sessionID, inputAgent) {
     const agent = getSessionAgent(sessionID) ?? inputAgent;
     if (!agent)
       return false;
     const agentKey = getAgentConfigKey(agent);
-    return TARGET_AGENTS.has(agentKey) || agentKey.includes("morpheus") || agentKey.includes("niobe");
+    return TARGET_AGENTS2.has(agentKey) || agentKey.includes("morpheus") || agentKey.includes("niobe");
   }
   const toolExecuteAfter = async (input, output) => {
-    const { tool, sessionID } = input;
-    const toolLower = tool.toLowerCase();
-    if (!isTargetAgent(sessionID, input.agent)) {
-      return;
-    }
-    const state = getOrCreateState(sessionID);
-    if (DELEGATION_TOOLS.has(toolLower)) {
-      state.delegationUsed = true;
-      log("[category-skill-reminder] Delegation tool used", { sessionID, tool });
-      return;
-    }
-    if (!DELEGATABLE_WORK_TOOLS.has(toolLower)) {
+    try {
+      const { tool, sessionID } = input;
+      const toolLower = tool.toLowerCase();
+      if (subagentSessions.has(sessionID))
+        return;
+      if (!isTargetAgent(sessionID, input.agent)) {
+        return;
+      }
+      const state = getOrCreateState(sessionID);
+      if (DELEGATION_TOOLS.has(toolLower)) {
+        state.delegationUsed = true;
+        log("[category-skill-reminder] Delegation tool used", { sessionID, tool });
+        return;
+      }
+      if (!DELEGATABLE_WORK_TOOLS2.has(toolLower)) {
+        return;
+      }
+      state.toolCallCount++;
+      let nudge = null;
+      try {
+        nudge = detectNudge({
+          tool,
+          sessionID,
+          agent: input.agent,
+          toolCallCount: state.toolCallCount,
+          delegationUsed: state.delegationUsed,
+          reminderShown: state.reminderShown
+        });
+      } catch {
+        nudge = null;
+      }
+      if (nudge) {
+        const dedupKey = `${sessionID}:${toolLower}:${nudge.skill}`;
+        const lastAt = lastNudgeAt.get(dedupKey);
+        const current = now();
+        if (lastAt !== undefined && current - lastAt < DEDUP_WINDOW_MS2) {
+          return;
+        }
+        lastNudgeAt.set(dedupKey, current);
+        output.output += reminderMessage;
+        state.reminderShown = true;
+        log("[category-skill-reminder] Reminder injected", {
+          sessionID,
+          toolCallCount: state.toolCallCount
+        });
+        try {
+          await notifyInjection(ctx, {
+            sessionID,
+            injector: "category-skill-reminder",
+            hash: hashSnippet(reminderMessage),
+            title: "Context injection",
+            message: "Delegation guidance applied"
+          });
+        } catch {
+          return;
+        }
+      }
+    } catch {
       return;
     }
-    state.toolCallCount++;
-    if (state.toolCallCount >= 3 && !state.delegationUsed && !state.reminderShown) {
-      output.output += reminderMessage;
-      state.reminderShown = true;
-      log("[category-skill-reminder] Reminder injected", {
-        sessionID,
-        toolCallCount: state.toolCallCount
-      });
-      await notifyInjection(ctx, {
-        sessionID,
-        injector: "category-skill-reminder",
-        hash: hashSnippet(reminderMessage),
-        title: "Context injection",
-        message: "Delegation guidance applied"
-      });
-    }
   };
   const eventHandler = async (event) => {
-    const props = event.data;
-    if (event.type === "session.deleted") {
-      const sessionInfo = props?.info;
-      if (sessionInfo?.id) {
-        sessionStates.delete(sessionInfo.id);
+    try {
+      const props = event.data;
+      if (event.type === "session.deleted") {
+        const sessionInfo = props?.info;
+        if (sessionInfo?.id) {
+          clearSessionState(sessionInfo.id);
+          clearSessionDedup(sessionInfo.id);
+        }
       }
-    }
-    if (event.type === "session.compacted") {
-      const sessionID = props?.sessionID ?? props?.info?.id;
-      if (sessionID) {
-        sessionStates.delete(sessionID);
+      if (event.type === "session.compacted") {
+        const sessionID = props?.sessionID ?? props?.info?.id;
+        if (sessionID) {
+          clearSessionState(sessionID);
+        }
       }
+    } catch {
+      return;
     }
   };
   return {
@@ -79254,7 +79442,7 @@ var BLOCKED_PATTERNS = [
   /\bpython3?\b[^|&;]*\.(pdf|docx?|xlsx?|pptx?|jpe?g|png|gif|webp|mp3|wav)/,
   /\bmarkitdown\b/
 ];
-var READ_BLOCK_MESSAGE = "[document-reader-guard] BLOCKED: Use document_reader__convert_to_markdown (document_reader MCP, Microsoft MarkItDown) for binary documents \u2014 generic Read cannot parse them. " + "Call convert_to_markdown with an absolute URI like file:///absolute/path/to/report.pdf, then summarize \u2014 do not dump raw output. " + "For context isolation delegate to the construct subagent so the main context stays clean.";
+var READ_BLOCK_MESSAGE = "[document-reader-guard] BLOCKED: Use document_reader__convert_to_markdown (document_reader MCP, Microsoft MarkItDown) for binary documents \u2014 generic Read cannot parse them. " + "Call document_reader__convert_to_markdown with an absolute URI like file:///absolute/path/to/report.pdf, then summarize \u2014 do not dump raw output. " + "For context isolation delegate to the construct subagent so the main context stays clean.";
 var BASH_BLOCK_MESSAGE = "[document-reader-guard] BLOCKED: Do not read documents via bash CLIs (pdftotext, pdfinfo, pandoc, libreoffice, cat/head/tail, python fitz/pypdf/pdfminer/pdfplumber/docx/openpyxl, markitdown CLI). " + "Use document_reader__convert_to_markdown with file:///absolute/path instead \u2014 delegate to construct for summarization.";
 
 // src/hooks/document-reader-guard/hook.ts
@@ -92503,6 +92691,13 @@ async function guard(label, fn) {
 function asRecord8(value) {
   return value !== null && typeof value === "object" ? value : {};
 }
+function hideNativeSubagentTool(editor) {
+  try {
+    editor.remove("subagent");
+  } catch {
+    log("[matrixx] native subagent tool not present, skipping hide");
+  }
+}
 async function registerDomainTools(input) {
   const { ctx, bridge, directory, worktree } = input;
   const tools = bridge.tool;
@@ -92548,6 +92743,7 @@ async function registerDomainTools(input) {
           tool.input = override.parameters;
       });
     }
+    hideNativeSubagentTool(editor);
   }));
   return registration ? [registration] : [];
 }

package/dist/mcps/context7.d.ts

@@ -1,3 +1,15 @@
+export interface BuildContext7EntryInput {
+    context7ApiKey?: string;
+}
+export declare function buildContext7Entry(input?: BuildContext7EntryInput): {
+    type: "remote";
+    url: string;
+    enabled: boolean;
+    headers: {
+        Authorization: string;
+    } | undefined;
+    oauth: false;
+};
 export declare const context7: {
     type: "remote";
     url: string;

package/dist/mcps/index.d.ts

@@ -10,10 +10,13 @@ import { type BuiltinMcpEntry } from "./mcp.transform";
 import { type McpCreationFailure } from "./mcp-validator";
 export type { McpTransformDomain, McpTransformEditor, RegisterMcpTransformResult, } from "./mcp.transform";
 export { type BuiltinMcpEntry, buildBuiltinMcpEntries, registerMcpTransform, toV2McpEntry } from "./mcp.transform";
+export { buildMcpStartupNotice, getMcpStartupNotice, MCP_UVX_INSTALL_FIX, MCP_UVX_WARM_FIX } from "./mcp-startup-notice";
 export type { McpCreationFailure } from "./mcp-validator";
 export { type McpName, McpNameSchema } from "./types";
 export interface CreateBuiltinMcpsOptions {
     isCommandAvailable?: (command: string) => boolean;
+    /** Overrides `process.env.CONTEXT7_API_KEY`; resolved at the edge, never in the builder. */
+    context7ApiKey?: string;
 }
 export interface CreateBuiltinMcpsResult {
     mcps: Record<string, BuiltinMcpEntry>;

package/dist/mcps/mcp-startup-notice.d.ts

@@ -0,0 +1,5 @@
+import type { McpCreationFailure } from "./mcp-validator";
+export declare const MCP_UVX_INSTALL_FIX = "curl -LsSf https://astral.sh/uv/install.sh | sh";
+export declare const MCP_UVX_WARM_FIX = "uvx --from markitdown-mcp markitdown-mcp --help";
+export declare function buildMcpStartupNotice(failures: McpCreationFailure[]): string | undefined;
+export declare function getMcpStartupNotice(): string | undefined;

package/dist/mcps/mcp.transform.d.ts

@@ -23,6 +23,8 @@ export interface BuildBuiltinMcpEntriesInput {
     disabledMcps?: string[];
     /** Resolved by the caller (e.g. `isCommandAvailable("uvx")`); never spawned here. */
     uvxAvailable: boolean;
+    /** Resolved by the caller from `process.env.CONTEXT7_API_KEY` at the edge; never read here. */
+    context7ApiKey?: string;
 }
 export interface BuildBuiltinMcpEntriesResult {
     entries: Record<string, BuiltinMcpEntry>;

package/dist/plugin/setup-domains.d.ts

@@ -104,6 +104,9 @@ export interface DomainRegistration {
  * the empty task response). Join text parts; non-text parts contribute nothing.
  */
 export declare function hookOutputText(content: unknown): string | undefined;
+export declare function hideNativeSubagentTool(editor: {
+    remove(id: string): void;
+}): void;
 /**
  * Applies the assembled `Hooks` onto the V2 context.
  * Returns the registration set whose `dispose` tears everything down.

package/dist/tools/delegate-task/sync-session-poller.d.ts

@@ -1,5 +1,20 @@
 import type { SessionMessage } from "../../shared/session-message";
 import type { NativeClient, ToolContextWithMetadata } from "./types";
+/**
+ * `time.completed` from the flat message shape. The shared `session-message`
+ * surface is frozen (see tests/shared/no-v1-shape.test.ts), so this accessor
+ * lives with its only consumer instead of graduating into `shared/`.
+ */
+export declare function completedOf(message: unknown): number | undefined;
+/**
+ * OpenCode V2 publishes `time.completed` on assistant messages: the row is
+ * created when a step starts and completed when it ends, so an assistant
+ * message without `time.completed` is still streaming. Older payloads (and
+ * test corpora) never carry the field — when no assistant message in the
+ * observed set carries it, the host does not expose completion and every
+ * message must be treated as settled.
+ */
+export declare function isStreamingAssistant(message: SessionMessage | undefined, messages: SessionMessage[]): boolean;
 export declare function isSessionComplete(messages: SessionMessage[]): boolean;
 export declare function hasToolResultAfterAssistant(messages: SessionMessage[]): boolean;
 export declare function hasAssistantContent(messages: SessionMessage[]): boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "opencode-matrixx-v2",
-  "version": "1.1.0",
+  "version": "1.2.1",
   "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -78,7 +78,7 @@
     "@code-yeongyu/comment-checker": "^0.6.1",
     "@cucumber/gherkin": "^34.0.0",
     "@modelcontextprotocol/sdk": "^1.25.1",
-    "context-mode": "2.0.0-next.24",
+    "context-mode": "2.1.*",
     "js-yaml": "^4.1.1",
     "jsonc-parser": "^3.3.1",
     "picomatch": "^4.0.2",