@researai/deepscientist 1.5.14 → 1.5.15

package/src/deepscientist/quest/stage_views.py

@@ -62,6 +62,26 @@ def _field(label: str, value: object, *, tone: str = "default") -> dict[str, Any
     }
 
 
+def _selection_score_summary(value: object) -> str | None:
+    if not isinstance(value, dict):
+        return None
+    parts: list[str] = []
+    for key, raw in value.items():
+        name = str(key or "").strip()
+        if not name:
+            continue
+        if isinstance(raw, float):
+            rendered = f"{raw:.4f}".rstrip("0").rstrip(".")
+        else:
+            rendered = str(raw).strip()
+        if not rendered:
+            continue
+        parts.append(f"{name}={rendered}")
+        if len(parts) >= 4:
+            break
+    return " · ".join(parts) or None
+
+
 def _evaluation_summary(value: object) -> dict[str, Any]:
     if not isinstance(value, dict):
         return {}
@@ -215,6 +235,8 @@ class QuestStageViewBuilder:
     def build(self) -> dict[str, Any]:
         selection_type = str(self.selection.get("selection_type") or "").strip()
         self.stage_key = self._resolve_effective_stage_key()
+        if selection_type == "idea_candidate":
+            return self._build_idea_candidate()
         if selection_type == "branch_node" and self.stage_key not in {"experiment", "analysis", "paper"}:
             return self._build_branch()
         if self.stage_key == "baseline":
@@ -280,6 +302,8 @@ class QuestStageViewBuilder:
             normalized = [str(item).strip() for item in raw if str(item).strip()]
             if normalized:
                 return normalized
+        if str(self.selection.get("selection_type") or "").strip() == "idea_candidate":
+            return self._idea_candidate_scope_paths()
         if str(self.selection.get("selection_type") or "").strip() == "branch_node":
             return self._branch_scope_paths()
         defaults = {
@@ -693,6 +717,13 @@ class QuestStageViewBuilder:
             "artifacts/reports",
         ]
 
+    def _idea_candidate_scope_paths(self) -> list[str]:
+        candidate_id = str(self.selection.get("selection_ref") or self.selection.get("idea_id") or "").strip()
+        return [
+            *( [f"memory/ideas/_candidates/{candidate_id}"] if candidate_id else []),
+            "artifacts/reports",
+        ]
+
     def _experiment_scope_paths(self, run_id: str | None) -> list[str]:
         return [
             *( [f"experiments/main/{run_id}"] if run_id else []),
@@ -917,6 +948,25 @@ class QuestStageViewBuilder:
                     items.append(item)
         return items
 
+    def _idea_candidate_stage_items(self) -> list[dict[str, Any]]:
+        candidate_id = str(self.selection.get("selection_ref") or self.selection.get("idea_id") or "").strip()
+        if not candidate_id:
+            return []
+        items: list[dict[str, Any]] = []
+        for item in self.artifacts:
+            payload = self._payload(item)
+            if str(payload.get("kind") or "").strip() != "idea":
+                continue
+            if str(payload.get("idea_id") or "").strip() != candidate_id:
+                continue
+            flow_type = str(payload.get("flow_type") or "").strip()
+            protocol_step = str(payload.get("protocol_step") or "").strip()
+            details = dict(payload.get("details") or {}) if isinstance(payload.get("details"), dict) else {}
+            submission_mode = str(details.get("submission_mode") or payload.get("submission_mode") or "").strip().lower()
+            if flow_type == "idea_submission" and (protocol_step == "candidate" or submission_mode == "candidate"):
+                items.append(item)
+        return items
+
     def _build_idea(self) -> dict[str, Any]:
         idea_items = self._idea_stage_items()
         latest = idea_items[-1] if idea_items else None
@@ -944,6 +994,8 @@ class QuestStageViewBuilder:
         draft_md_rel_path = self._relative_path_or_raw(draft_md_path)
         draft_markdown = self._markdown_body_for_path(draft_md_path)
         lineage_intent = str(payload.get("lineage_intent") or details.get("lineage_intent") or "").strip() or None
+        selection_scores = details.get("selection_scores")
+        selection_score_summary = _selection_score_summary(selection_scores)
         note = (
             str(payload.get("summary") or payload.get("reason") or "").strip()
             or "No durable idea submission has been recorded yet."
@@ -987,6 +1039,11 @@ class QuestStageViewBuilder:
                 _field("Problem", details.get("problem") or "Not recorded"),
                 _field("Hypothesis", details.get("hypothesis") or "Not recorded"),
                 _field("Mechanism", details.get("mechanism") or "Not recorded"),
+                _field("Method Brief", details.get("method_brief") or "Not recorded"),
+                _field("Selection Scores", selection_score_summary or "Not recorded"),
+                _field("Mechanism Family", details.get("mechanism_family") or "Not recorded"),
+                _field("Change Layer", details.get("change_layer") or "Not recorded"),
+                _field("Source Lens", details.get("source_lens") or "Not recorded"),
                 _field("Expected Gain", details.get("expected_gain") or "Not recorded"),
                 _field("Risks", details.get("risks") or "Not recorded"),
                 _field("Evidence Paths", details.get("evidence_paths") or "Not recorded"),
@@ -1009,6 +1066,11 @@ class QuestStageViewBuilder:
                     "problem": details.get("problem"),
                     "hypothesis": details.get("hypothesis"),
                     "mechanism": details.get("mechanism"),
+                    "method_brief": details.get("method_brief"),
+                    "selection_scores": selection_scores or None,
+                    "mechanism_family": details.get("mechanism_family"),
+                    "change_layer": details.get("change_layer"),
+                    "source_lens": details.get("source_lens"),
                     "expected_gain": details.get("expected_gain"),
                     "risks": details.get("risks") or [],
                     "evidence_paths": details.get("evidence_paths") or [],
@@ -1028,6 +1090,101 @@ class QuestStageViewBuilder:
             subviews=["overview", "details", "draft"] if draft_markdown else ["overview", "details"],
         )
 
+    def _build_idea_candidate(self) -> dict[str, Any]:
+        candidate_items = self._idea_candidate_stage_items()
+        latest = candidate_items[-1] if candidate_items else None
+        payload = self._payload(latest or {})
+        details = dict(payload.get("details") or {}) if isinstance(payload.get("details"), dict) else {}
+        candidate_id = str(self.selection.get("selection_ref") or payload.get("idea_id") or "candidate").strip() or "candidate"
+        title_text = (
+            str(details.get("title") or self.selection.get("label") or candidate_id).strip() or candidate_id
+        )
+        paths = dict(payload.get("paths") or {}) if isinstance(payload.get("paths"), dict) else {}
+        candidate_root = paths.get("candidate_root") or str(self.quest_root / "memory" / "ideas" / "_candidates" / candidate_id)
+        idea_md_path = paths.get("idea_md") or str(Path(candidate_root) / "idea.md")
+        draft_md_path = paths.get("idea_draft_md") or details.get("idea_draft_path") or str(Path(candidate_root) / "draft.md")
+        idea_markdown = self._markdown_body_for_path(idea_md_path)
+        draft_markdown = self._markdown_body_for_path(draft_md_path)
+        idea_md_rel_path = self._relative_path_or_raw(idea_md_path)
+        draft_md_rel_path = self._relative_path_or_raw(draft_md_path)
+        candidate_root_rel_path = self._relative_path_or_raw(candidate_root)
+        selection_scores = details.get("selection_scores")
+        selection_score_summary = _selection_score_summary(selection_scores)
+        note = (
+            str(payload.get("summary") or payload.get("reason") or self.selection.get("summary") or "").strip()
+            or "No durable candidate brief summary has been recorded yet."
+        )
+        lineage_intent = str(payload.get("lineage_intent") or details.get("lineage_intent") or "").strip() or None
+        parent_branch = str(payload.get("parent_branch") or details.get("parent_branch") or self.selection.get("branch_name") or "").strip() or None
+        foundation_reason = str(payload.get("foundation_reason") or details.get("foundation_reason") or "").strip() or None
+        return self._base_payload(
+            title=f"Candidate Brief · {title_text}",
+            note=note,
+            status=str(payload.get("status") or "candidate").strip() or "candidate",
+            tags=[
+                "candidate-brief",
+                details.get("mechanism_family") or "",
+                details.get("change_layer") or "",
+                details.get("source_lens") or "",
+                lineage_intent or "",
+            ],
+            overview=[
+                _field("Candidate ID", candidate_id),
+                _field("Parent Branch", parent_branch or "Not recorded"),
+                _field("Next Target", details.get("next_target") or "optimize"),
+                _field("Candidate Root", candidate_root_rel_path or candidate_root),
+            ],
+            key_facts=[
+                _field("Problem", details.get("problem") or "Not recorded"),
+                _field("Hypothesis", details.get("hypothesis") or "Not recorded"),
+                _field("Mechanism", details.get("mechanism") or "Not recorded"),
+                _field("Method Brief", details.get("method_brief") or "Not recorded"),
+                _field("Selection Scores", selection_score_summary or "Not recorded"),
+                _field("Mechanism Family", details.get("mechanism_family") or "Not recorded"),
+                _field("Change Layer", details.get("change_layer") or "Not recorded"),
+                _field("Source Lens", details.get("source_lens") or "Not recorded"),
+                _field("Expected Gain", details.get("expected_gain") or "Not recorded"),
+                _field("Foundation Reason", foundation_reason or "Not recorded"),
+            ],
+            key_files=self._dedupe_files(
+                [
+                    self._file_entry(candidate_root, label="Candidate Root", description="Branchless candidate brief workspace.", expected_kind="directory"),
+                    self._file_entry(idea_md_path, label="Candidate Markdown", description="Durable candidate brief document."),
+                    self._file_entry(draft_md_path, label="Candidate Draft", description="Long-form candidate brief draft."),
+                ]
+            ),
+            history=self._artifact_history(candidate_items),
+            details={
+                "idea": {
+                    "idea_id": candidate_id,
+                    "title": title_text,
+                    "problem": details.get("problem"),
+                    "hypothesis": details.get("hypothesis"),
+                    "mechanism": details.get("mechanism"),
+                    "method_brief": details.get("method_brief"),
+                    "selection_scores": selection_scores or None,
+                    "mechanism_family": details.get("mechanism_family"),
+                    "change_layer": details.get("change_layer"),
+                    "source_lens": details.get("source_lens"),
+                    "expected_gain": details.get("expected_gain"),
+                    "next_target": details.get("next_target") or "optimize",
+                    "lineage_intent": lineage_intent,
+                    "parent_branch": parent_branch,
+                    "candidate_root": candidate_root_rel_path or candidate_root,
+                    "idea_path": idea_md_rel_path,
+                    "idea_markdown": idea_markdown,
+                    "draft_path": draft_md_rel_path,
+                    "draft_markdown": draft_markdown,
+                    "decision_reason": payload.get("reason"),
+                },
+                "latest_artifact": self._artifact_detail(latest, payload),
+            },
+            lineage_intent=lineage_intent,
+            idea_draft_path=draft_md_rel_path,
+            draft_available=bool(draft_markdown),
+            subviews=["overview", "details", "draft"] if draft_markdown else ["overview", "details"],
+        )
+
     def _build_branch(self) -> dict[str, Any]:
         idea_items = [
             item
@@ -1050,6 +1207,8 @@ class QuestStageViewBuilder:
         idea_title = str(latest_idea_details.get("title") or "").strip() or None
         idea_problem = str(latest_idea_details.get("problem") or "").strip() or None
         next_target = str(latest_idea_details.get("next_target") or "").strip() or None
+        selection_scores = latest_idea_details.get("selection_scores")
+        selection_score_summary = _selection_score_summary(selection_scores)
         lineage_intent = str(
             latest_idea_payload.get("lineage_intent")
             or latest_idea_details.get("lineage_intent")
@@ -1169,6 +1328,11 @@ class QuestStageViewBuilder:
             key_facts=[
                 _field("Idea Title", idea_title or "Not recorded"),
                 _field("Idea Problem", idea_problem or "Not recorded"),
+                _field("Method Brief", latest_idea_details.get("method_brief") or "Not recorded"),
+                _field("Selection Scores", selection_score_summary or "Not recorded"),
+                _field("Mechanism Family", latest_idea_details.get("mechanism_family") or "Not recorded"),
+                _field("Change Layer", latest_idea_details.get("change_layer") or "Not recorded"),
+                _field("Source Lens", latest_idea_details.get("source_lens") or "Not recorded"),
                 _field("Foundation", foundation_label or "Current head"),
                 _field("Foundation Reason", foundation_reason or "Not recorded"),
                 _field("Next Target", next_target or "Not recorded"),
@@ -1224,6 +1388,11 @@ class QuestStageViewBuilder:
                     "lineage_intent": lineage_intent,
                     "idea_title": idea_title,
                     "idea_problem": idea_problem,
+                    "method_brief": latest_idea_details.get("method_brief"),
+                    "selection_scores": selection_scores or None,
+                    "mechanism_family": latest_idea_details.get("mechanism_family"),
+                    "change_layer": latest_idea_details.get("change_layer"),
+                    "source_lens": latest_idea_details.get("source_lens"),
                     "next_target": next_target,
                     "idea_draft_path": idea_draft_rel_path,
                     "idea_draft_markdown": idea_draft_markdown,
@@ -1579,11 +1748,13 @@ class QuestStageViewBuilder:
                 for path in candidates
             ],
             self._file_entry(paper_root / "selected_outline.json", label="Selected Outline", description="Chosen paper outline."),
+            self._file_entry(paper_root / "outline" / "manifest.json", label="Outline Manifest", description="Author-facing paper outline manifest."),
             self._file_entry(paper_root / "outline_selection.md", label="Outline Selection Note", description="Outline selection rationale."),
             self._file_entry(paper_root / "draft.md", label="Draft Markdown", description="Current paper draft."),
             self._file_entry(paper_root / "writing_plan.md", label="Writing Plan", description="Paper writing plan."),
             self._file_entry(paper_root / "references.bib", label="References", description="Bibliography file."),
             self._file_entry(paper_root / "claim_evidence_map.json", label="Claim-Evidence Map", description="Claim to evidence mapping."),
+            self._file_entry(paper_root / "paper_line_state.json", label="Paper Line State", description="Derived summary state for the active paper line."),
             self._file_entry(paper_root / "baseline_inventory.json", label="Baseline Inventory", description="Canonical and supplementary baseline inventory for writing."),
             self._file_entry(paper_root / "build" / "compile_report.json", label="Compile Report", description="Paper build/compile report."),
             self._file_entry(paper_root / "paper_bundle_manifest.json", label="Bundle Manifest", description="Final paper bundle manifest."),

package/src/deepscientist/runners/base.py

@@ -17,6 +17,8 @@ class RunRequest:
     approval_policy: str
     sandbox_mode: str
     turn_reason: str = "user_message"
+    turn_intent: str = "continue_stage"
+    turn_mode: str = "stage_execution"
     reasoning_effort: str | None = None
     turn_id: str | None = None
     attempt_index: int = 1

package/src/deepscientist/runners/codex.py

@@ -24,6 +24,50 @@ _TOOL_EVENT_ARGS_TEXT_LIMIT = 8_000
 _TOOL_EVENT_OUTPUT_TEXT_LIMIT = 16_000
 _MAX_QUEST_EVENT_JSON_BYTES = 2_000_000
 _OVERSIZED_EVENT_PREVIEW_TEXT_LIMIT = 12_000
+_BUILTIN_MCP_TOOL_APPROVALS: dict[str, tuple[str, ...]] = {
+    "memory": (
+        "write",
+        "read",
+        "search",
+        "list_recent",
+        "promote_to_global",
+    ),
+    "artifact": (
+        "record",
+        "checkpoint",
+        "prepare_branch",
+        "activate_branch",
+        "submit_idea",
+        "list_research_branches",
+        "resolve_runtime_refs",
+        "get_paper_contract_health",
+        "get_quest_state",
+        "get_global_status",
+        "get_method_scoreboard",
+        "get_optimization_frontier",
+        "read_quest_documents",
+        "get_conversation_context",
+        "get_analysis_campaign",
+        "record_main_experiment",
+        "create_analysis_campaign",
+        "submit_paper_outline",
+        "list_paper_outlines",
+        "submit_paper_bundle",
+        "record_analysis_slice",
+        "publish_baseline",
+        "attach_baseline",
+        "confirm_baseline",
+        "waive_baseline",
+        "arxiv",
+        "refresh_summary",
+        "render_git_graph",
+        "interact",
+        "complete_quest",
+    ),
+    "bash_exec": (
+        "bash_exec",
+    ),
+}
 
 
 def _compact_text(value: object, *, limit: int = 1200) -> str:
@@ -322,9 +366,11 @@ def _tool_output(event: dict[str, Any], item: dict[str, Any]) -> str:
             item.get("result"),
             item.get("output"),
             item.get("content"),
+            item.get("error"),
             event.get("result"),
             event.get("output"),
             event.get("content"),
+            event.get("error"),
             item.get("aggregated_output"),
             event.get("aggregated_output"),
         ):
@@ -338,11 +384,13 @@ def _tool_output(event: dict[str, Any], item: dict[str, Any]) -> str:
         item.get("output"),
         item.get("result"),
         item.get("content"),
+        item.get("error"),
         event.get("aggregated_output"),
         event.get("changes"),
         event.get("output"),
         event.get("result"),
         event.get("content"),
+        event.get("error"),
     ):
         text = _compact_text(value, limit=1200)
         if text:
@@ -642,6 +690,8 @@ class CodexRunner:
             user_message=request.message,
             model=request.model,
             turn_reason=request.turn_reason,
+            turn_intent=request.turn_intent,
+            turn_mode=request.turn_mode,
             retry_context=request.retry_context,
         )
         write_text(run_root / "prompt.md", prompt)
@@ -663,6 +713,8 @@ class CodexRunner:
                 "workspace_root": str(workspace_root),
                 "cwd": str(workspace_root),
                 "turn_reason": request.turn_reason,
+                "turn_intent": request.turn_intent,
+                "turn_mode": request.turn_mode,
             },
         )
 
@@ -672,7 +724,10 @@ class CodexRunner:
             env_key = str(key or "").strip()
             if not env_key or value is None:
                 continue
-            env[env_key] = str(value)
+            env_value = str(value)
+            if env_value == "":
+                continue
+            env[env_key] = env_value
         env["CODEX_HOME"] = str(codex_home)
         env["DEEPSCIENTIST_HOME"] = str(self.home)
         env["DS_HOME"] = str(self.home)
@@ -681,6 +736,8 @@ class CodexRunner:
         env["DS_WORKTREE_ROOT"] = str(workspace_root)
         env["DS_RUN_ID"] = request.run_id
         env["DS_TURN_REASON"] = request.turn_reason
+        env["DS_TURN_INTENT"] = request.turn_intent
+        env["DS_TURN_MODE"] = request.turn_mode
         quest_yaml = read_yaml(request.quest_root / "quest.yaml", {})
         env["DS_ACTIVE_ANCHOR"] = str(quest_yaml.get("active_anchor", "baseline"))
         env["DS_CONVERSATION_ID"] = f"quest:{request.quest_id}"
@@ -740,6 +797,13 @@ class CodexRunner:
                 timestamp = utc_now()
                 append_jsonl(history_events, {"timestamp": timestamp, "event": payload})
                 append_jsonl(stdout_events, {"timestamp": timestamp, "line": line})
+                try:
+                    self.artifact_service.quest_service.schedule_projection_refresh(
+                        request.quest_root,
+                        kinds=("details",),
+                    )
+                except Exception:
+                    pass
                 tool_event = _tool_event(
                     payload,
                     quest_id=request.quest_id,
@@ -810,6 +874,14 @@ class CodexRunner:
             }
             write_json(run_root / "result.json", result_payload)
             write_json(history_root / "meta.json", result_payload)
+            try:
+                self.artifact_service.quest_service.schedule_projection_refresh(
+                    request.quest_root,
+                    kinds=("details",),
+                    throttle_seconds=0.0,
+                )
+            except Exception:
+                pass
             self.logger.log(
                 "info",
                 "runner.codex.completed",
@@ -822,6 +894,7 @@ class CodexRunner:
                 request.quest_root,
                 {
                     "kind": "run",
+                    "status": "completed" if exit_code == 0 else "failed",
                     "run_id": request.run_id,
                     "run_kind": request.skill_id,
                     "model": request.model,
@@ -954,10 +1027,11 @@ class CodexRunner:
         for filename in ("config.toml", "auth.json"):
             source_path = source / filename
             target_path = target / filename
-            if source_path.exists() and not target_path.exists():
-                if source_path.resolve() == target_path.resolve():
-                    continue
-                shutil.copy2(source_path, target_path)
+            if not source_path.exists():
+                continue
+            if source_path.resolve() == target_path.resolve():
+                continue
+            shutil.copy2(source_path, target_path)
         config_path = target / "config.toml"
         if profile and config_path.exists():
             adapted_text, _ = adapt_profile_only_provider_config(read_text(config_path), profile=profile)
@@ -1043,6 +1117,7 @@ class CodexRunner:
         args = ["-m", "deepscientist.mcp.server", "--namespace", name]
         lines = [
             f"[mcp_servers.{name}]",
+            'transport = "stdio"',
             f'command = "{sys.executable}"',
             f"args = [{', '.join(json.dumps(item) for item in args)}]",
         ]
@@ -1057,6 +1132,14 @@ class CodexRunner:
         )
         for key, value in env.items():
             lines.append(f"{key} = {json.dumps(value)}")
+        for tool_name in _BUILTIN_MCP_TOOL_APPROVALS.get(name, ()):
+            lines.extend(
+                [
+                    "",
+                    f"[mcp_servers.{name}.tools.{tool_name}]",
+                    'approval_mode = "approve"',
+                ]
+            )
         return "\n".join(lines)
 
     def _load_runner_config(self) -> dict[str, Any]:

package/src/deepscientist/runners/runtime_overrides.py

@@ -17,6 +17,18 @@ def _as_bool_env(name: str) -> bool:
     return value.lower() in {"1", "true", "yes", "on", "y"}
 
 
+def _as_optional_bool_env(name: str) -> bool | None:
+    value = _as_text(os.environ.get(name))
+    if value is None:
+        return None
+    normalized = value.lower()
+    if normalized in {"1", "true", "yes", "on", "y"}:
+        return True
+    if normalized in {"0", "false", "no", "off", "n"}:
+        return False
+    return True
+
+
 def codex_runtime_overrides() -> dict[str, str]:
     binary = _as_text(os.environ.get("DEEPSCIENTIST_CODEX_BINARY") or os.environ.get("DS_CODEX_BINARY"))
     approval_policy = _as_text(os.environ.get("DEEPSCIENTIST_CODEX_APPROVAL_POLICY"))
@@ -24,9 +36,13 @@ def codex_runtime_overrides() -> dict[str, str]:
     profile = _as_text(os.environ.get("DEEPSCIENTIST_CODEX_PROFILE"))
     model = _as_text(os.environ.get("DEEPSCIENTIST_CODEX_MODEL"))
 
-    if _as_bool_env("DEEPSCIENTIST_CODEX_YOLO"):
+    yolo_enabled = _as_optional_bool_env("DEEPSCIENTIST_CODEX_YOLO")
+    if yolo_enabled is True:
         approval_policy = approval_policy or "never"
         sandbox_mode = sandbox_mode or "danger-full-access"
+    elif yolo_enabled is False:
+        approval_policy = approval_policy or "on-request"
+        sandbox_mode = sandbox_mode or "workspace-write"
 
     overrides: dict[str, str] = {}
     if binary:

package/src/prompts/contracts/shared_interaction.md

@@ -6,12 +6,21 @@ This shared contract is injected once per turn and applies across the stage and
 
 - Treat `artifact.interact(...)` as the main long-lived communication thread across TUI, web, and bound connectors.
 - If `artifact.interact(...)` returns queued user requirements, treat them as the highest-priority user instruction bundle before continuing the current stage or companion-skill task.
-- Immediately follow any non-empty mailbox poll with another `artifact.interact(...)` update that confirms receipt; if the request is directly answerable, answer there, otherwise say the current subtask is paused, give a short plan plus nearest report-back point, and handle that request first.
+- Immediately follow any non-empty mailbox poll with another `artifact.interact(...)` update that confirms receipt; if the request is directly answerable, answer there with `kind='answer'`, otherwise say the current subtask is paused, give a short plan plus nearest report-back point, and handle that request first.
+- If you are explicitly answering or continuing a specific prior interaction thread, use `reply_to_interaction_id` instead of assuming the runtime will always infer the right target.
 - Stage-kickoff rule: after entering any stage or companion skill, send one `artifact.interact(kind='progress', reply_mode='threaded', ...)` update within the first 3 tool calls of substantial work.
 - Reading/planning keepalive rule: if you spend 5 consecutive tool calls on reading, searching, comparison, or planning without a user-visible update, send one concise checkpoint even if the route is not finalized yet.
+- Visibility-bound rule: do not drift beyond roughly 12 tool calls or about 8 minutes without a user-visible update when the user-visible state has materially changed.
 - Subtask-boundary rule: send a user-visible update whenever the active subtask changes materially, especially across intake -> audit, audit -> experiment planning, experiment planning -> run launch, run result -> drafting, or drafting -> review/rebuttal.
-- Emit `artifact.interact(kind='progress', reply_mode='threaded', ...)` when there is real user-visible progress: a meaningful checkpoint, route-shaping update, or a concise keepalive once active work has crossed roughly 6 tool calls with a human-meaningful delta. Do not let ordinary active work drift beyond roughly 12 tool calls or about 8 minutes without a user-visible update.
+- Emit `artifact.interact(kind='progress', reply_mode='threaded', ...)` when there is real user-visible progress: a meaningful checkpoint, route-shaping update, blocker, recovery, or a concise keepalive when silence would otherwise hide a meaningful change. Do not reflexively send another progress update if the user-visible state is unchanged.
 - Keep progress updates chat-like and easy to understand: say what changed, what it means, and what happens next.
-- Default to plain-language summaries. Do not mention file paths, artifact ids, branch/worktree ids, session ids, raw commands, or raw logs unless the user asks or needs them to act.
+- Keep the tone respectful and easy to understand. In Chinese, natural respectful phrasing is good; in English, keep a polite professional tone.
+- Assume the user may not know the codebase or internal runtime objects. Explain progress in beginner-friendly task language before technical detail.
+- If there are `2-3` options, tradeoffs, or next steps, prefer a short numbered list instead of a dense block of prose.
+- If a key distinction is quantitative and the number is known, include the number or one short concrete example instead of only saying `better`, `slower`, or `more stable`.
+- Default to plain-language summaries. Do not mention file paths, file names, artifact ids, branch/worktree ids, session ids, raw commands, or raw logs unless the user asks or needs them to act. First translate them into user-facing meaning such as baseline record, draft, experiment result, or supplementary run.
+- When the user is plainly asking a direct question, answer it directly in plain language before resuming background stage work.
 - Use `reply_mode='blocking'` only for real user decisions that cannot be resolved from local evidence.
-- For any blocking decision request, provide 1 to 3 concrete options, put the recommended option first, explain each option's actual content plus pros and cons, and wait up to 1 day when feasible. If the blocker is a missing external credential or secret that only the user can provide, keep the quest waiting, ask the user to supply it or choose an alternative, and do not self-resolve; if resumed without that credential and no other work is possible, a long low-frequency wait such as `bash_exec(command='sleep 3600', mode='await', timeout_seconds=3700)` is acceptable. Otherwise choose the best option yourself and notify the user of the chosen option if the timeout expires.
+- Keep `deliver_to_bound_conversations=True` for normal user-visible continuity. If `delivery_results` or `attachment_issues` show that requested delivery failed, treat that as a real failure and adapt instead of assuming the user already received the message or file.
+- Use `dedupe_key`, `suppress_if_unchanged`, and `min_interval_seconds` only to suppress repeated unchanged `progress` updates, not to suppress a real answer or milestone.
+- For any blocking decision request, provide 1 to 3 concrete options, put the recommended option first, and explain for each option: what it means, how strongly you recommend it, its likely impact on speed / quality / cost / risk, and when it is preferable. Make the user's reply format obvious and wait up to 1 day when feasible. If the blocker is a missing external credential or secret that only the user can provide, keep the quest waiting, ask the user to supply it or choose an alternative, and do not self-resolve; if resumed without that credential and no other work is possible, a long low-frequency wait such as `bash_exec(command='sleep 3600', mode='await', timeout_seconds=3700)` is acceptable. Otherwise choose the best option yourself and notify the user of the chosen option if the timeout expires.