@researai/deepscientist 1.5.12 → 1.5.14

package/src/deepscientist/connector/lingzhu_support.py

@@ -15,6 +15,9 @@ DEFAULT_LINGZHU_AGENT_ID = "main"
 DEFAULT_LINGZHU_SESSION_NAMESPACE = "lingzhu"
 DEFAULT_LINGZHU_TASK_PREFIX = "我现在的任务是"
 DEFAULT_LINGZHU_PASSIVE_CHAT_TYPE = "passive"
+_LINGZHU_COMMAND_PUNCTUATION = "：:，,。.;；!！?？、~～`'\"“”‘’（）()【】[]《》<>"
+_LINGZHU_COMMAND_PUNCT_TRANSLATION = str.maketrans({char: " " for char in _LINGZHU_COMMAND_PUNCTUATION})
+_LINGZHU_PREFIX_SEPARATORS_CLASS = re.escape(_LINGZHU_COMMAND_PUNCTUATION) + r"\s"
 
 _AUTH_AK_SEGMENTS = (8, 4, 4, 4, 12)
 _AUTH_AK_CHARS = "abcdefghijklmnopqrstuvwxyz0123456789"
@@ -237,12 +240,28 @@ def lingzhu_extract_user_text(messages: Any) -> str:
     return "\n".join(parts).strip()
 
 
-def lingzhu_extract_task_text(text: Any) -> str | None:
+def lingzhu_normalize_command_text(text: Any) -> str:
     normalized = str(text or "").strip()
-    if not normalized.startswith(DEFAULT_LINGZHU_TASK_PREFIX):
+    if not normalized:
+        return ""
+    normalized = normalized.translate(_LINGZHU_COMMAND_PUNCT_TRANSLATION)
+    normalized = re.sub(r"\s+", " ", normalized)
+    return normalized.strip()
+
+
+def lingzhu_extract_task_text(text: Any) -> str | None:
+    raw_text = str(text or "").strip()
+    if not raw_text:
+        return None
+    prefix_pattern = r"^[{separators}]*{prefix}[{separators}]*".format(
+        separators=_LINGZHU_PREFIX_SEPARATORS_CLASS,
+        prefix="".join(f"{re.escape(char)}[{_LINGZHU_PREFIX_SEPARATORS_CLASS}]*" for char in DEFAULT_LINGZHU_TASK_PREFIX),
+    )
+    matched = re.match(prefix_pattern, raw_text)
+    if matched is None:
         return None
-    remainder = normalized[len(DEFAULT_LINGZHU_TASK_PREFIX) :].strip()
-    remainder = remainder.lstrip("：:，,。.;；!！?？ ")
+    remainder = raw_text[matched.end() :].strip()
+    remainder = remainder.lstrip(_LINGZHU_COMMAND_PUNCTUATION + " \t\r\n")
     return remainder or None
 
 

package/src/deepscientist/daemon/app.py

@@ -54,6 +54,7 @@ from ..network import urlopen_with_proxy as urlopen
 from ..latex_runtime import QuestLatexService
 from ..connector.lingzhu_support import (
     lingzhu_detect_tool_call_from_text,
+    lingzhu_normalize_command_text,
     lingzhu_extract_task_text,
     lingzhu_extract_user_text,
     lingzhu_health_payload,
@@ -102,6 +103,25 @@ LEGACY_CODEX_RETRY_BACKOFF_MULTIPLIER = 2.0
 LEGACY_CODEX_RETRY_MAX_BACKOFF_SEC = 8.0
 _CRASH_AUTO_RESUME_COOLDOWN = timedelta(minutes=10)
 _CRASH_AUTO_RESUME_MAX_RECENT_ATTEMPTS = 2
+_CHINESE_DIGIT_MAP = {
+    "零": 0,
+    "〇": 0,
+    "一": 1,
+    "二": 2,
+    "两": 2,
+    "三": 3,
+    "四": 4,
+    "五": 5,
+    "六": 6,
+    "七": 7,
+    "八": 8,
+    "九": 9,
+}
+_CHINESE_UNIT_MAP = {
+    "十": 10,
+    "百": 100,
+    "千": 1000,
+}
 _LINGZHU_SHORT_COMMAND_DIRECT_MAP = {
     "帮助": "help",
     "列表": "list",
@@ -117,7 +137,7 @@ _LINGZHU_SHORT_COMMAND_PREFIX_MAP = {
     "暂停": "stop",
     "恢复": "resume",
 }
-_LINGZHU_SHORT_LATEST_ALIASES = {"latest", "newest", "最新"}
+_LINGZHU_SHORT_LATEST_ALIASES = {"latest", "newest", "最新", "最新的"}
 _LINGZHU_DELETE_CONFIRM_ALIASES = {"确认", "强制", "--yes", "-y"}
 
 
@@ -3570,10 +3590,8 @@ class DaemonApp:
                             ),
                         }
                     )
-                target_quest = args[0]
-                if target_quest in {"latest", "newest"}:
-                    quests = self.quest_service.list_quests()
-                    target_quest = str(quests[0]["quest_id"]) if quests else ""
+                requested_quest_ref = str(args[0] or "").strip()
+                target_quest = self._resolve_quest_reference(requested_quest_ref) or requested_quest_ref
                 if not (self.home / "quests" / target_quest / "quest.yaml").exists():
                     available = ", ".join(item["quest_id"] for item in self.quest_service.list_quests()[:6]) or "none"
                     return channel.send(
@@ -3581,8 +3599,8 @@ class DaemonApp:
                             "conversation_id": conversation_id,
                             "kind": "ack",
                             "message": self._polite_copy(
-                                zh=f"老师，目前没有找到 quest `{target_quest}`。可用 quest 包括：{available}。",
-                                en=f"I could not find quest `{target_quest}`. Available quests: {available}.",
+                                zh=f"老师，目前没有找到 quest `{requested_quest_ref}`。可用 quest 包括：{available}。",
+                                en=f"I could not find quest `{requested_quest_ref}`. Available quests: {available}.",
                             ),
                         }
                     )
@@ -3626,10 +3644,8 @@ class DaemonApp:
                             ),
                         }
                     )
-                target_quest = str(args[0] or "").strip()
-                if target_quest in {"latest", "newest"}:
-                    quests = self.quest_service.list_quests()
-                    target_quest = str(quests[0]["quest_id"]) if quests else ""
+                requested_quest_ref = str(args[0] or "").strip()
+                target_quest = self._resolve_quest_reference(requested_quest_ref) or requested_quest_ref
                 confirmed = any(str(item).strip().lower() in {"--yes", "--force", "-y"} for item in args[1:])
                 if not confirmed:
                     return channel.send(
@@ -3660,8 +3676,8 @@ class DaemonApp:
                             "conversation_id": conversation_id,
                             "kind": "ack",
                             "message": self._polite_copy(
-                                zh=f"老师，目前没有找到 quest `{target_quest}`。可用 quest 包括：{available}。",
-                                en=f"I could not find quest `{target_quest}`. Available quests: {available}.",
+                                zh=f"老师，目前没有找到 quest `{requested_quest_ref}`。可用 quest 包括：{available}。",
+                                en=f"I could not find quest `{requested_quest_ref}`. Available quests: {available}.",
                             ),
                         }
                     )
@@ -4345,6 +4361,53 @@ class DaemonApp:
         quest_id = str(quests[0].get("quest_id") or "").strip()
         return quest_id or None
 
+    @staticmethod
+    def _strip_quest_reference_noise(value: str | None) -> str:
+        normalized = lingzhu_normalize_command_text(value)
+        if not normalized:
+            return ""
+        normalized = re.sub(r"^(?:第|quest|Quest|任务|项目)\s*", "", normalized).strip()
+        normalized = re.sub(r"\s*(?:号|个|个任务|任务)\s*$", "", normalized).strip()
+        return normalized
+
+    @staticmethod
+    def _parse_chinese_numeric_reference(value: str) -> str | None:
+        normalized = str(value or "").strip()
+        if not normalized:
+            return None
+        if all(char in _CHINESE_DIGIT_MAP for char in normalized):
+            return "".join(str(_CHINESE_DIGIT_MAP[char]) for char in normalized)
+        if not all(char in _CHINESE_DIGIT_MAP or char in _CHINESE_UNIT_MAP for char in normalized):
+            return None
+        total = 0
+        current = 0
+        for char in normalized:
+            if char in _CHINESE_DIGIT_MAP:
+                current = _CHINESE_DIGIT_MAP[char]
+                continue
+            unit = _CHINESE_UNIT_MAP.get(char)
+            if unit is None:
+                return None
+            total += (current or 1) * unit
+            current = 0
+        total += current
+        return str(total) if total > 0 else None
+
+    def _resolve_numeric_quest_id(self, value: str | None) -> str | None:
+        normalized = str(value or "").strip()
+        if not normalized or not normalized.isdigit():
+            return None
+        if self._quest_exists(normalized):
+            return normalized
+        target_numeric = int(normalized)
+        for item in self.quest_service.list_quests():
+            quest_id = str(item.get("quest_id") or "").strip()
+            if not quest_id.isdigit():
+                continue
+            if int(quest_id) == target_numeric:
+                return quest_id
+        return None
+
     def _quest_exists(self, quest_id: str | None) -> bool:
         normalized = str(quest_id or "").strip()
         if not normalized:
@@ -4352,11 +4415,22 @@ class DaemonApp:
         return (self.home / "quests" / normalized / "quest.yaml").exists()
 
     def _resolve_quest_reference(self, value: str | None) -> str | None:
-        normalized = str(value or "").strip()
+        normalized = self._strip_quest_reference_noise(value)
         if not normalized:
             return None
         if normalized in {"latest", "newest"}:
             return self._latest_quest_id()
+        literal_match = normalized if self._quest_exists(normalized) else None
+        if literal_match:
+            return literal_match
+        numeric_match = self._resolve_numeric_quest_id(normalized)
+        if numeric_match:
+            return numeric_match
+        chinese_numeric = self._parse_chinese_numeric_reference(normalized)
+        if chinese_numeric:
+            numeric_match = self._resolve_numeric_quest_id(chinese_numeric)
+            if numeric_match:
+                return numeric_match
         return normalized
 
     def _connector_control_reply(
@@ -4795,7 +4869,7 @@ class DaemonApp:
 
     @staticmethod
     def _parse_lingzhu_short_command(text: str) -> tuple[str, list[str]] | None:
-        normalized = re.sub(r"\s+", " ", str(text or "").strip())
+        normalized = lingzhu_normalize_command_text(text)
         if not normalized or normalized.startswith("/"):
             return None
         direct = _LINGZHU_SHORT_COMMAND_DIRECT_MAP.get(normalized)
@@ -4822,6 +4896,27 @@ class DaemonApp:
             return command_name, []
         return None
 
+    def _lingzhu_status_hint_text(self, quest_id: str | None) -> str:
+        if not quest_id:
+            latest = str(self._latest_quest_id() or "").strip()
+            bind_hint = f"绑定{latest}" if latest else "绑定最新"
+            return f"未绑定。可说：{bind_hint}/列表/帮助"
+        snapshot = self.quest_service.snapshot(quest_id)
+        runtime_status = str(snapshot.get("runtime_status") or snapshot.get("status") or "").strip().lower()
+        latest = str(self._latest_quest_id() or "").strip()
+        bind_hint = f"绑定{latest}" if latest and latest != quest_id else "绑定最新"
+        if runtime_status in {"running", "active"}:
+            return f"绑{quest_id}，进行中。可说：状态/总结/{bind_hint}"
+        if runtime_status == "waiting_for_user":
+            return f"绑{quest_id}，等你确认。可说：状态/总结/{bind_hint}"
+        if runtime_status in {"paused", "stopped"}:
+            return f"绑{quest_id}，已暂停。可说：恢复/{bind_hint}/列表"
+        if runtime_status == "completed":
+            return f"绑{quest_id}，已完成。可说：总结/{bind_hint}/列表"
+        if runtime_status == "error":
+            return f"绑{quest_id}，出错了。可说：状态/恢复/{bind_hint}"
+        return f"绑{quest_id}，暂无新进展。可说：状态/总结/{bind_hint}"
+
     def _lingzhu_unbound_help_text(self) -> str:
         latest = str(self._latest_quest_id() or "none")
         return (
@@ -5354,21 +5449,7 @@ class DaemonApp:
         return emitted
 
     def _lingzhu_short_status_text(self, quest_id: str | None) -> str:
-        if not quest_id:
-            return self._lingzhu_unbound_help_text()
-        snapshot = self.quest_service.snapshot(quest_id)
-        runtime_status = str(snapshot.get("runtime_status") or snapshot.get("status") or "").strip().lower()
-        if runtime_status in {"running", "active"}:
-            return "进行中"
-        if runtime_status == "waiting_for_user":
-            return "等你确认"
-        if runtime_status in {"paused", "stopped"}:
-            return "已暂停"
-        if runtime_status == "completed":
-            return "已完成"
-        if runtime_status == "error":
-            return "出错了"
-        return "暂无新进展"
+        return self._lingzhu_status_hint_text(quest_id)
 
     @staticmethod
     def _lingzhu_reply_payload(result: dict[str, Any]) -> tuple[str, str | None, str]:

package/src/deepscientist/mcp/server.py

@@ -11,6 +11,7 @@ from ..artifact import ArtifactService
 from ..artifact.metrics import MetricContractValidationError
 from ..bash_exec import BashExecService
 from ..memory import MemoryService
+from ..quest import QuestService
 from .context import McpContext
 
 DEFAULT_INLINE_BASH_LOG_LINE_LIMIT = 2000
@@ -18,16 +19,123 @@ DEFAULT_INLINE_BASH_LOG_HEAD_LINES = 500
 DEFAULT_INLINE_BASH_LOG_TAIL_LINES = 1500
 DEFAULT_INLINE_BASH_LOG_WINDOW_LINES = 200
 MAX_INLINE_BASH_LOG_WINDOW_LINES = 2000
+INTERACTION_WATCHDOG_TOOL_CALL_THRESHOLD = 25
+INTERACTION_WATCHDOG_SILENCE_THRESHOLD_SECONDS = 30 * 60
 LONG_BASH_LOG_HINT = (
     "Use `bash_exec(mode='read', id=..., start=..., tail=...)` to inspect a specific log window, "
     "or `bash_exec(mode='read', id=..., tail=...)` to inspect the latest rendered lines."
 )
+ARTIFACT_STATE_CHANGE_WATCHDOG_NOTES = {
+    "confirm_baseline": (
+        "Baseline confirmation changed durable quest state and this tool does not send a user-visible "
+        "summary on its own. Send one concise artifact.interact(...) update now."
+    ),
+    "waive_baseline": (
+        "Baseline waiver changed durable quest state and this tool does not send a user-visible summary "
+        "on its own. Send one concise artifact.interact(...) update now."
+    ),
+    "submit_paper_outline": (
+        "Paper outline state changed durably and this tool does not send a user-visible summary on its own. "
+        "Send one concise artifact.interact(...) update now."
+    ),
+    "publish_baseline": (
+        "Baseline publication changed durable state and this tool does not send a user-visible summary "
+        "on its own. Send one concise artifact.interact(...) update now."
+    ),
+    "attach_baseline": (
+        "Baseline attachment changed durable quest state and this tool does not send a user-visible summary "
+        "on its own. Send one concise artifact.interact(...) update now."
+    ),
+    "complete_quest": (
+        "Quest completion changed durable state and this tool does not send a final user-visible summary "
+        "on its own. Send one concise artifact.interact(...) closing update now unless the user already "
+        "received an equivalent completion summary."
+    ),
+}
 
 
 def _metric_validation_error_payload(exc: MetricContractValidationError) -> dict[str, Any]:
     return exc.as_payload()
 
 
+def _progress_watchdog_note(tool_call_count: int) -> str:
+    return (
+        "By the way, you have gone "
+        f"{tool_call_count} tool calls without notifying the user via artifact.interact(...). "
+        "Please report your latest progress now."
+    )
+
+
+def _visibility_watchdog_note(seconds_since_last_update: int) -> str:
+    minutes = max(1, seconds_since_last_update // 60)
+    return (
+        "By the way, it has been "
+        f"{minutes} minutes since the last user-visible artifact.interact(...). "
+        "Send one concise progress update now before continuing with background work."
+    )
+
+
+def _collect_interaction_watchdog_notes(
+    watchdog: dict[str, Any],
+    *,
+    state_change_note: str | None = None,
+) -> list[dict[str, str]]:
+    notes: list[dict[str, str]] = []
+    count = int((watchdog or {}).get("tool_calls_since_last_artifact_interact") or 0)
+    if count >= INTERACTION_WATCHDOG_TOOL_CALL_THRESHOLD:
+        notes.append(
+            {
+                "kind": "progress",
+                "message": _progress_watchdog_note(count),
+            }
+        )
+    silence_seconds = int((watchdog or {}).get("seconds_since_last_artifact_interact") or 0)
+    if count > 0 and silence_seconds >= INTERACTION_WATCHDOG_SILENCE_THRESHOLD_SECONDS:
+        notes.append(
+            {
+                "kind": "visibility",
+                "message": _visibility_watchdog_note(silence_seconds),
+            }
+        )
+    if state_change_note:
+        notes.append(
+            {
+                "kind": "state_change",
+                "message": state_change_note,
+            }
+        )
+    return notes
+
+
+def _attach_interaction_watchdog(
+    payload: dict[str, Any],
+    watchdog: dict[str, Any],
+    *,
+    state_change_note: str | None = None,
+) -> dict[str, Any]:
+    enriched = dict(payload)
+    enriched["interaction_watchdog"] = dict(watchdog or {})
+    notes = _collect_interaction_watchdog_notes(
+        watchdog,
+        state_change_note=state_change_note,
+    )
+    if not notes:
+        return enriched
+    enriched["watchdog_notes"] = notes
+    for item in notes:
+        kind = str(item.get("kind") or "").strip()
+        message = str(item.get("message") or "").strip()
+        if not message:
+            continue
+        if kind == "progress":
+            enriched["progress_watchdog_note"] = message
+        elif kind == "visibility":
+            enriched["visibility_watchdog_note"] = message
+        elif kind == "state_change":
+            enriched["state_change_watchdog_note"] = message
+    return enriched
+
+
 def _split_bash_log_lines(log_text: str) -> list[str]:
     return log_text.splitlines()
 
@@ -341,6 +449,7 @@ def build_memory_server(context: McpContext) -> FastMCP:
 
 def build_artifact_server(context: McpContext) -> FastMCP:
     service = ArtifactService(context.home)
+    quest_service = service.quest_service
     server = FastMCP(
         "artifact",
         instructions=(
@@ -351,6 +460,19 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         log_level="ERROR",
     )
 
+    def finalize_state_changing_artifact_tool(payload: dict[str, Any], *, tool_name: str) -> dict[str, Any]:
+        quest_root = context.require_quest_root().resolve()
+        quest_service.record_tool_activity(
+            quest_root,
+            tool_name=f"artifact.{tool_name}",
+        )
+        watchdog = quest_service.artifact_interaction_watchdog_status(quest_root)
+        return _attach_interaction_watchdog(
+            payload,
+            watchdog,
+            state_change_note=ARTIFACT_STATE_CHANGE_WATCHDOG_NOTES.get(tool_name),
+        )
+
     @server.tool(name="record", description="Write a structured artifact record under the current quest.")
     def record(payload: dict[str, Any], comment: str | dict[str, Any] | None = None) -> dict[str, Any]:
         enriched = dict(payload)
@@ -620,7 +742,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         selected_reason: str | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.submit_paper_outline(
+        result = service.submit_paper_outline(
             context.require_quest_root(),
             mode=mode,
             outline_id=outline_id,
@@ -632,6 +754,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             review_result=review_result,
             selected_reason=selected_reason,
         )
+        return finalize_state_changing_artifact_tool(result, tool_name="submit_paper_outline")
 
     @server.tool(
         name="list_paper_outlines",
@@ -733,7 +856,8 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         if comment is not None and "comment" not in enriched:
             enriched["comment"] = comment
         enriched.setdefault("source", {"kind": "artifact_publish", "quest_id": context.quest_id, "quest_root": str(context.require_quest_root())})
-        return service.publish_baseline(context.require_quest_root(), enriched)
+        result = service.publish_baseline(context.require_quest_root(), enriched)
+        return finalize_state_changing_artifact_tool(result, tool_name="publish_baseline")
 
     @server.tool(name="attach_baseline", description="Attach a published baseline to the current quest.")
     def attach_baseline(
@@ -741,7 +865,8 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         variant_id: str | None = None,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.attach_baseline(context.require_quest_root(), baseline_id, variant_id)
+        result = service.attach_baseline(context.require_quest_root(), baseline_id, variant_id)
+        return finalize_state_changing_artifact_tool(result, tool_name="attach_baseline")
 
     @server.tool(
         name="confirm_baseline",
@@ -764,7 +889,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         try:
-            return service.confirm_baseline(
+            result = service.confirm_baseline(
                 context.require_quest_root(),
                 baseline_path=baseline_path,
                 comment=comment,
@@ -779,6 +904,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
                 auto_advance=auto_advance,
                 strict_metric_contract=True,
             )
+            return finalize_state_changing_artifact_tool(result, tool_name="confirm_baseline")
         except MetricContractValidationError as exc:
             return _metric_validation_error_payload(exc)
 
@@ -791,12 +917,13 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         auto_advance: bool = True,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.waive_baseline(
+        result = service.waive_baseline(
             context.require_quest_root(),
             reason=reason,
             comment=comment,
             auto_advance=auto_advance,
         )
+        return finalize_state_changing_artifact_tool(result, tool_name="waive_baseline")
 
     @server.tool(
         name="arxiv",
@@ -852,7 +979,7 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         supersede_open_requests: bool = True,
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.interact(
+        result = service.interact(
             context.require_quest_root(),
             kind=kind,
             message=message,
@@ -873,6 +1000,8 @@ def build_artifact_server(context: McpContext) -> FastMCP:
             reply_to_interaction_id=reply_to_interaction_id,
             supersede_open_requests=supersede_open_requests,
         )
+        result["interaction_watchdog"] = quest_service.artifact_interaction_watchdog_status(context.require_quest_root())
+        return result
 
     @server.tool(
         name="complete_quest",
@@ -885,16 +1014,20 @@ def build_artifact_server(context: McpContext) -> FastMCP:
         summary: str = "",
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
-        return service.complete_quest(
+        result = service.complete_quest(
             context.require_quest_root(),
             summary=summary,
         )
+        if result.get("ok") is True and str(result.get("status") or "").strip() == "completed":
+            return finalize_state_changing_artifact_tool(result, tool_name="complete_quest")
+        return result
 
     return server
 
 
 def build_bash_exec_server(context: McpContext) -> FastMCP:
     service = BashExecService(context.home)
+    quest_service = QuestService(context.home)
     server = FastMCP(
         "bash_exec",
         instructions=(
@@ -944,6 +1077,15 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
         comment: str | dict[str, Any] | None = None,
     ) -> dict[str, Any]:
         quest_root = context.require_quest_root().resolve()
+
+        def finalize(payload: dict[str, Any]) -> dict[str, Any]:
+            quest_service.record_tool_activity(
+                quest_root,
+                tool_name=f"bash_exec.{normalized_mode}",
+            )
+            watchdog = quest_service.artifact_interaction_watchdog_status(quest_root)
+            return _attach_interaction_watchdog(payload, watchdog)
+
         normalized_mode = (mode or "detach").strip().lower()
         if normalized_mode == "create":
             normalized_mode = "await"
@@ -973,12 +1115,12 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
                 "history_lines": history_lines,
             }
             if normalized_mode == "history":
-                return {
+                return finalize({
                     "count": len(items),
                     "lines": history_lines,
                     "items": items,
-                }
-            return payload
+                })
+            return finalize(payload)
         if normalized_mode == "read":
             bash_id = service.resolve_session_id(quest_root, id)
             session = service.get_session(quest_root, bash_id)
@@ -1007,7 +1149,7 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
                         tail=tail if tail is not None else tail_limit,
                     )
                 )
-                return payload
+                return finalize(payload)
             use_tail = tail_limit is not None or before_seq is not None or after_seq is not None or normalized_order != "asc"
             if use_tail:
                 resolved_tail_limit = max(1, min(int(tail_limit or 200), 1000))
@@ -1034,7 +1176,7 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
                 payload["after_seq"] = tail_meta.get("after_seq")
                 payload["before_seq"] = tail_meta.get("before_seq")
                 payload["order"] = normalized_order
-                return payload
+                return finalize(payload)
             payload = service.build_tool_result(
                 context,
                 session=session,
@@ -1043,7 +1185,7 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
                 export_log_to=export_log_to,
             )
             payload.update(_build_default_bash_log_payload_from_path(service.terminal_log_path(quest_root, bash_id)))
-            return payload
+            return finalize(payload)
         if normalized_mode == "kill":
             bash_id = service.resolve_session_id(quest_root, id)
             session = service.request_stop(
@@ -1055,17 +1197,17 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
             )
             if wait:
                 session = service.wait_for_session(quest_root, bash_id, timeout_seconds=timeout_seconds)
-            return service.build_tool_result(context, session=session, include_log=False)
+            return finalize(service.build_tool_result(context, session=session, include_log=False))
         if normalized_mode == "await" and not command:
             bash_id = service.resolve_session_id(quest_root, id)
             session = service.wait_for_session(quest_root, bash_id, timeout_seconds=timeout_seconds)
-            return service.build_tool_result(
+            return finalize(service.build_tool_result(
                 context,
                 session=session,
                 include_log=False,
                 export_log=export_log,
                 export_log_to=export_log_to,
-            )
+            ))
         if not (command or "").strip():
             raise ValueError("command is required for `detach` and `await`.")
         session = service.start_session(
@@ -1078,15 +1220,15 @@ def build_bash_exec_server(context: McpContext) -> FastMCP:
             comment=comment,
         )
         if normalized_mode == "detach":
-            return service.build_tool_result(context, session=session, include_log=False)
+            return finalize(service.build_tool_result(context, session=session, include_log=False))
         session = service.wait_for_session(quest_root, str(session["bash_id"]), timeout_seconds=timeout_seconds)
-        return service.build_tool_result(
+        return finalize(service.build_tool_result(
             context,
             session=session,
             include_log=False,
             export_log=export_log,
             export_log_to=export_log_to,
-        )
+        ))
 
     return server