@pheem49/mint 1.15.0 → 1.17.0

package/crates/mint-core/src/orchestration/truncation.rs

@@ -0,0 +1,211 @@
+//! Line-aware Head-Tail Observation Truncation Harness
+//!
+//! Preserves the top execution context (command invocation, parameters, early progress)
+//! and trailing execution context (stack traces, compiler errors, exit summaries)
+//! while omitting intermediate verbose output with a structured diagnostic banner.
+
+/// Configuration bounds for head-tail truncation.
+#[derive(Debug, Clone, Copy, PartialEq, Eq)]
+pub struct TruncationConfig {
+    /// Maximum total characters permitted in the output (including banner).
+    pub max_total_chars: usize,
+    /// Maximum line count threshold before line-based truncation triggers.
+    pub max_total_lines: usize,
+    /// Number of initial lines to preserve from the beginning of output.
+    pub head_lines: usize,
+    /// Number of trailing lines to preserve from the end of output.
+    pub tail_lines: usize,
+}
+
+impl Default for TruncationConfig {
+    fn default() -> Self {
+        Self {
+            max_total_chars: 8_000,
+            max_total_lines: 150,
+            head_lines: 35,
+            tail_lines: 75,
+        }
+    }
+}
+
+impl TruncationConfig {
+    /// Compact configuration for text-rendered context previews and transcript exports.
+    pub const COMPACT: Self = Self {
+        max_total_chars: 2_500,
+        max_total_lines: 60,
+        head_lines: 15,
+        tail_lines: 35,
+    };
+}
+
+/// Truncates `text` using an industry-standard line-aware Head-Tail strategy.
+///
+/// If `text` fits within both `max_total_chars` and `max_total_lines`, it is returned unchanged.
+/// Otherwise, the first `head_lines` and last `tail_lines` are preserved, separated by a
+/// clear omission marker indicating the omitted line and character counts.
+pub fn head_tail_truncate(text: &str, config: TruncationConfig) -> String {
+    if text.is_empty() {
+        return String::new();
+    }
+
+    let char_count = text.chars().count();
+    let lines: Vec<&str> = text.lines().collect();
+    let total_lines = lines.len();
+
+    // Fast path: text is already within both character and line bounds
+    if char_count <= config.max_total_chars && total_lines <= config.max_total_lines {
+        return text.to_owned();
+    }
+
+    // If total lines are fewer than or equal to head + tail, but char count is still exceeded,
+    // we perform character-based head-tail truncation.
+    if total_lines <= config.head_lines + config.tail_lines {
+        return char_head_tail_truncate(text, config.max_total_chars);
+    }
+
+    let head_count = config.head_lines.min(total_lines);
+    let tail_count = config
+        .tail_lines
+        .min(total_lines.saturating_sub(head_count));
+    let omitted_lines = total_lines.saturating_sub(head_count + tail_count);
+
+    let head_text = lines[..head_count].join("\n");
+    let tail_text = lines[total_lines - tail_count..].join("\n");
+
+    let omitted_chars =
+        char_count.saturating_sub(head_text.chars().count() + tail_text.chars().count());
+
+    let banner = format!(
+        "\n\n[... Truncated {omitted_lines} lines ({omitted_chars} chars) to preserve context window — showing initial {head_count} and trailing {tail_count} lines ...]\n\n"
+    );
+
+    let combined_chars =
+        head_text.chars().count() + banner.chars().count() + tail_text.chars().count();
+    if combined_chars <= config.max_total_chars {
+        let mut result = String::with_capacity(head_text.len() + banner.len() + tail_text.len());
+        result.push_str(&head_text);
+        result.push_str(&banner);
+        result.push_str(&tail_text);
+        result
+    } else {
+        // If head + banner + tail still exceeds char limit, enforce character budget on the combined text
+        let remaining_for_tail = config
+            .max_total_chars
+            .saturating_sub(head_text.chars().count() + banner.chars().count());
+        let trimmed_tail: String = if remaining_for_tail > 0 {
+            // Keep the very end of tail
+            let tail_chars_count = tail_text.chars().count();
+            let skip_chars = tail_chars_count.saturating_sub(remaining_for_tail);
+            tail_text.chars().skip(skip_chars).collect()
+        } else {
+            String::new()
+        };
+
+        let mut result = String::with_capacity(head_text.len() + banner.len() + trimmed_tail.len());
+        result.push_str(&head_text);
+        result.push_str(&banner);
+        result.push_str(&trimmed_tail);
+        result
+    }
+}
+
+/// Fallback character-based head-tail truncation when line count is small but individual lines are huge.
+fn char_head_tail_truncate(text: &str, max_chars: usize) -> String {
+    let char_count = text.chars().count();
+    if char_count <= max_chars {
+        return text.to_owned();
+    }
+
+    let head_budget = (max_chars / 3).min(1_000);
+    let head: String = text.chars().take(head_budget).collect();
+
+    let banner_placeholder_len = 100;
+    let tail_budget = max_chars.saturating_sub(head_budget + banner_placeholder_len);
+    let skip_count = char_count.saturating_sub(tail_budget);
+    let tail: String = text.chars().skip(skip_count).collect();
+
+    let omitted_chars = char_count.saturating_sub(head.chars().count() + tail.chars().count());
+    let banner = format!(
+        "\n\n[... Truncated {omitted_chars} chars to preserve context window — showing head and tail ...]\n\n"
+    );
+
+    let mut result = String::with_capacity(head.len() + banner.len() + tail.len());
+    result.push_str(&head);
+    result.push_str(&banner);
+    result.push_str(&tail);
+    result
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn leaves_short_text_untouched() {
+        let short = "Line 1\nLine 2\nLine 3";
+        assert_eq!(
+            head_tail_truncate(short, TruncationConfig::default()),
+            short
+        );
+    }
+
+    #[test]
+    fn truncates_oversized_line_counts_preserving_head_and_tail() {
+        let mut lines = Vec::new();
+        for i in 1..=300 {
+            lines.push(format!("Step log line {i}: details here"));
+        }
+        let input = lines.join("\n");
+
+        let config = TruncationConfig {
+            max_total_chars: 10_000,
+            max_total_lines: 100,
+            head_lines: 10,
+            tail_lines: 20,
+        };
+
+        let result = head_tail_truncate(&input, config);
+        assert!(result.starts_with("Step log line 1:"));
+        assert!(result.contains("Step log line 10:"));
+        assert!(result.contains("Truncated 270 lines"));
+        assert!(result.contains("Step log line 281:"));
+        assert!(result.ends_with("Step log line 300: details here"));
+    }
+
+    #[test]
+    fn preserves_utf8_multibyte_safety() {
+        let thai_line = "การทำงานขั้นตอนที่สำคัญมากสำหรับการทดสอบระบบ";
+        let mut lines = Vec::new();
+        for i in 1..=200 {
+            lines.push(format!("{i}. {thai_line}"));
+        }
+        let input = lines.join("\n");
+
+        let config = TruncationConfig {
+            max_total_chars: 2_000,
+            max_total_lines: 50,
+            head_lines: 5,
+            tail_lines: 5,
+        };
+
+        let result = head_tail_truncate(&input, config);
+        assert!(result.contains("1. การทำงานขั้นตอน"));
+        assert!(result.contains("200. การทำงานขั้นตอน"));
+        assert!(result.contains("Truncated"));
+    }
+
+    #[test]
+    fn handles_single_huge_line_gracefully() {
+        let huge_line = "x".repeat(15_000);
+        let config = TruncationConfig {
+            max_total_chars: 1_000,
+            max_total_lines: 100,
+            head_lines: 10,
+            tail_lines: 10,
+        };
+
+        let result = head_tail_truncate(&huge_line, config);
+        assert!(result.len() < 2_000);
+        assert!(result.contains("Truncated"));
+    }
+}

package/crates/mint-core/src/orchestration/verification.rs

@@ -13,6 +13,7 @@ pub(super) fn looks_skill_worthy(step: usize, action_counts: &BTreeMap<String, u
         "browser_open",
         "browser_click",
         "browser_type",
+        "dispatch_agents",
         "dispatch_subagent",
     ];
     step >= 3
@@ -25,17 +26,17 @@ pub(super) fn looks_skill_worthy(step: usize, action_counts: &BTreeMap<String, u
 
 /// Whether `finish` should be rejected because the run modified a file
 /// (`apply_patch`/`write_file`) without a subsequent `verify` call and without
-/// an explicit written reason in the `finish` action's `verification` field.
+/// a subsequent check. An explanation cannot stand in for execution evidence.
 pub(super) fn unverified_modification(
     last_modify_step: Option<usize>,
     last_verify_step: Option<usize>,
-    verification_field: &str,
+    _verification_field: &str,
 ) -> bool {
     let Some(modify_step) = last_modify_step else {
         return false;
     };
     let verified_since = last_verify_step.is_some_and(|verify_step| verify_step >= modify_step);
-    !verified_since && meaningful_verification(verification_field).is_empty()
+    !verified_since
 }
 
 /// Whether any `run_shell`/`verify` command in `result` — which may join
@@ -46,7 +47,7 @@ pub(super) fn unverified_modification(
 pub(super) fn shell_result_failed(result: &str) -> bool {
     result.lines().any(|line| {
         line.strip_prefix("exit: ")
-            .is_some_and(|code| !matches!(code.trim(), "0" | "unknown"))
+            .is_some_and(|code| code.trim() != "0")
     })
 }
 
@@ -61,9 +62,9 @@ pub(super) fn shell_result_failed(result: &str) -> bool {
 /// run has nobody watching live to catch it.
 pub(super) fn unacknowledged_verify_failure(
     last_verify_failed: Option<bool>,
-    verification_field: &str,
+    _verification_field: &str,
 ) -> bool {
-    last_verify_failed == Some(true) && meaningful_verification(verification_field).is_empty()
+    last_verify_failed == Some(true)
 }
 
 pub(super) fn meaningful_verification(value: &str) -> &str {
@@ -84,3 +85,32 @@ pub(super) fn meaningful_verification(value: &str) -> &str {
         value
     }
 }
+
+#[cfg(test)]
+mod reliability_regressions {
+    use super::*;
+
+    #[test]
+    fn success_prose_cannot_override_a_failed_check() {
+        assert!(unacknowledged_verify_failure(
+            Some(true),
+            "All tests passed."
+        ));
+    }
+
+    #[test]
+    fn success_prose_cannot_verify_an_unchecked_edit() {
+        assert!(unverified_modification(
+            Some(2),
+            None,
+            "Verified successfully."
+        ));
+    }
+
+    #[test]
+    fn an_unknown_exit_is_not_a_passed_check() {
+        assert!(shell_result_failed(
+            "exit: unknown\nCommand moved to the background"
+        ));
+    }
+}

package/crates/mint-core/src/orchestration/workspace_helpers.rs

@@ -127,7 +127,7 @@ pub(super) async fn read_diagnostics(
         }
     };
     match command {
-        Some(command) => run_shell(root, config, chat_id, command).await,
+        Some(command) => run_shell(root, config, chat_id, command, "").await,
         None => Ok("No diagnostics command detected.".into()),
     }
 }
@@ -155,19 +155,46 @@ pub(super) fn view_image(path: &Path, config: &MintConfig) -> Result<String, Orc
     };
     let metadata = std::fs::metadata(&path)
         .map_err(|e| OrchestrationError::Agent(format!("cannot stat image: {e}")))?;
-    if metadata.len() > 2_000_000 {
-        return Ok(format!(
-            "Image exists but is too large to inline ({} bytes): {}",
-            metadata.len(),
-            path.display()
+    if metadata.len() > crate::media::tool_images::ORIGINAL_LIMIT as u64 {
+        return Err(OrchestrationError::Agent(
+            "Image exceeds 20 MiB; use a smaller capture.".into(),
         ));
     }
     let bytes = std::fs::read(&path)
         .map_err(|e| OrchestrationError::Agent(format!("cannot read image: {e}")))?;
-    Ok(format!(
-        "data:{mime};base64,{}",
-        BASE64_STANDARD.encode(bytes)
-    ))
+    crate::media::tool_images::prepare(&bytes, mime)
+        .map(|image| image.data_uri)
+        .map_err(OrchestrationError::Agent)
+}
+
+#[cfg(test)]
+mod image_size_regressions {
+    use super::*;
+    #[test]
+    fn a_large_valid_image_is_prepared_for_the_model_instead_of_discarded() {
+        let path =
+            std::env::temp_dir().join(format!("mint-large-image-{}.png", uuid::Uuid::new_v4()));
+        let mut seed = 123456789u32;
+        let image = image::RgbImage::from_fn(1400, 900, |_, _| {
+            let mut p = [0; 3];
+            for v in &mut p {
+                seed ^= seed << 13;
+                seed ^= seed >> 17;
+                seed ^= seed << 5;
+                *v = seed as u8;
+            }
+            image::Rgb(p)
+        });
+        image.save(&path).unwrap();
+        assert!(std::fs::metadata(&path).unwrap().len() > 2_000_000);
+        let mut config = MintConfig::default();
+        config.allowed_read_paths.push(std::env::temp_dir());
+        let result = view_image(&path, &config);
+        let _ = std::fs::remove_file(path);
+        let image = result.unwrap();
+        assert!(image.starts_with("data:image/"));
+        assert!(image.len() < 2_700_000);
+    }
 }
 
 // `async` and dispatched onto tokio's blocking-thread-pool via
@@ -188,15 +215,31 @@ pub(super) async fn run_shell(
     config: &MintConfig,
     chat_id: &str,
     command: &str,
+    retry_reason: &str,
 ) -> Result<String, OrchestrationError> {
+    tools::shell::prevent_duplicate_browser_launch(command).await?;
+    run_control::check()?;
+    if let Err(reason) = reliability::before_shell(command, retry_reason) {
+        return Ok(format!("Skipped: {reason}"));
+    }
     let root = root.to_path_buf();
     let config = config.clone();
     let chat_id = chat_id.to_owned();
     let command = command.to_owned();
+    let cancellation = run_control::token();
     let output = {
         let command = command.clone();
         tokio::task::spawn_blocking(move || {
-            run_shell_command(&command, &root, true, &config, Some(&chat_id))
+            crate::bg_shell::with_context(crate::bg_shell::chat_context(&root, &chat_id), || {
+                crate::shell::run_shell_command_cancellable(
+                    &command,
+                    &root,
+                    true,
+                    &config,
+                    Some(&chat_id),
+                    cancellation.as_ref(),
+                )
+            })
         })
         .await
         .map_err(|e| OrchestrationError::Agent(format!("shell command task panicked: {e}")))?
@@ -206,16 +249,7 @@ pub(super) async fn run_shell(
         .status
         .map_or_else(|| "unknown".into(), |status| status.to_string());
 
-    let mut hint = "";
-    let cmd_lower = command.to_lowercase();
-    if output.success
-        && (cmd_lower.contains("open")
-            || cmd_lower.contains("launch")
-            || cmd_lower.contains("chrome")
-            || cmd_lower.contains("firefox"))
-    {
-        hint = "\nNote: Opening URLs, files, folders, or launching applications are background processes. Even if there are warnings or stdout/stderr outputs, since the command exited successfully with status 0, the operation has succeeded and you should now use the 'finish' action to inform the user.";
-    }
+    reliability::record_shell(&output);
 
     let warning_line = output
         .sandbox_warning
@@ -224,8 +258,8 @@ pub(super) async fn run_shell(
         .unwrap_or_default();
 
     Ok(format!(
-        "exit: {}\nmode: {}\nsandboxed: {}{}\nstdout:\n{}\nstderr:\n{}{}",
-        status_str, output.mode, output.sandboxed, warning_line, output.stdout, output.stderr, hint
+        "exit: {}\nmode: {}\nsandboxed: {}{}\nstdout:\n{}\nstderr:\n{}",
+        status_str, output.mode, output.sandboxed, warning_line, output.stdout, output.stderr
     ))
 }
 

package/crates/mint-core/src/prompts/agent.rs

@@ -1,31 +1,12 @@
 use super::persona;
 use crate::MintConfig;
 
-pub(crate) fn browser_endpoint_available(config: &MintConfig) -> bool {
-    use std::net::{TcpStream, ToSocketAddrs};
-    use std::time::Duration;
-    let endpoint = config
+pub(crate) fn browser_tools_enabled(config: &MintConfig) -> bool {
+    config
         .extra
-        .get("browserDebugUrl")
-        .and_then(serde_json::Value::as_str)
-        .unwrap_or("http://127.0.0.1:9222/json/list");
-    let Ok(url) = reqwest::Url::parse(endpoint) else {
-        return false;
-    };
-    let Some(host) = url.host_str() else {
-        return false;
-    };
-    let Some(port) = url.port_or_known_default() else {
-        return false;
-    };
-    (host, port)
-        .to_socket_addrs()
-        .ok()
-        .is_some_and(|mut addresses| {
-            addresses.any(|address| {
-                TcpStream::connect_timeout(&address, Duration::from_millis(50)).is_ok()
-            })
-        })
+        .get("browserAutomationEnabled")
+        .and_then(serde_json::Value::as_bool)
+        != Some(false)
 }
 
 pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
@@ -46,6 +27,9 @@ pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
     "stock",
     "calculation",
     "memory_recall",
+    "mod_help",
+    "mod_list",
+    "mod_validate",
     "git_status",
     "git_diff",
     "git_log",
@@ -62,13 +46,6 @@ pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
     "video_waveform",
     "note_write",
     "mcp_list_tools",
-    "browser_open",
-    "browser_read",
-    "browser_observe",
-    "browser_wait",
-    "browser_scroll",
-    "browser_mouse_move",
-    "browser_screenshot",
     "run_shell",
     // Read-only poll of a background job's buffered output; the run_shell
     // call that started it is still gated to read-only commands above.
@@ -76,7 +53,8 @@ pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
     // Cosmetic/non-mutating — no reason to block it during read-only
     // plan-mode investigation.
     "avatar_signal",
-    "conversation_summary",
+    "dispatch_agents",
+    "dispatch_subagent",
 ];
 
 /// The full set of coding-agent actions before plan-mode/disabled-tools/browser
@@ -85,7 +63,6 @@ pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
 /// two paths can never drift on which actions exist.
 pub(crate) fn base_allowed_actions() -> Vec<&'static str> {
     vec![
-        "conversation_summary",
         "list_files",
         "read_file",
         "search_code",
@@ -102,6 +79,10 @@ pub(crate) fn base_allowed_actions() -> Vec<&'static str> {
         "stock",
         "calculation",
         "memory_recall",
+        "mod_help",
+        "mod_list",
+        "mod_validate",
+        "mod_publish",
         "git_status",
         "git_diff",
         "git_log",
@@ -165,7 +146,7 @@ pub fn build_system_prompt(
 ) -> String {
     let mut allowed_actions = base_allowed_actions();
 
-    if browser_endpoint_available(config) {
+    if browser_tools_enabled(config) {
         allowed_actions.extend_from_slice(crate::browser::BROWSER_TOOLS);
     }
 
@@ -173,6 +154,11 @@ pub fn build_system_prompt(
         allowed_actions.push("avatar_signal");
     }
 
+    if native {
+        allowed_actions.push("dispatch_agents");
+        allowed_actions.push("dispatch_subagent");
+    }
+
     allowed_actions.retain(|action| !config.disabled_tools.contains(&action.to_string()));
     if plan_mode {
         allowed_actions.retain(|action| PLAN_MODE_ALLOWED_ACTIONS.contains(action));
@@ -185,6 +171,7 @@ pub fn build_system_prompt(
     let actions_str = allowed_actions.join("|");
 
     let mut input_formats = Vec::new();
+    input_formats.push("- mod_help / mod_list: {}. mod_validate / mod_publish: {\"arguments\":{\"manifest\":{...},\"source\":\"export function register(mint) {...}\",\"readme\":\"...\",\"expectedHash\":\"existing hash when replacing\"}}.");
     if allowed_actions.contains(&"list_files") {
         input_formats.push(
             "- list_files: {\"path\":\".\",\"limit\":100} (workspace path, ~/path, or allowed user folder like Downloads)",
@@ -275,7 +262,7 @@ pub fn build_system_prompt(
         input_formats.push("- browser_key_press: {\"key\":\"Enter\"} (keys: Enter,Tab,Escape,Backspace,Delete,ArrowUp,ArrowDown,ArrowLeft,ArrowRight,F1-F12,Space)");
     }
     if allowed_actions.contains(&"browser_screenshot") {
-        input_formats.push("- browser_screenshot: {}");
+        input_formats.push("- browser_screenshot: {mode?:viewport|fullPage|element,selector?:string,elementRef?:string}");
     }
     if allowed_actions.contains(&"memory_recall") {
         input_formats.push("- memory_recall: {\"query\":\"what did user say about X\"}");
@@ -306,7 +293,7 @@ pub fn build_system_prompt(
         input_formats.push("- request_user_approval: {\"title\":\"short title\",\"summary\":\"what needs approval\"}");
     }
     if allowed_actions.contains(&"ask_user") {
-        input_formats.push("- ask_user: {\"query\":\"short question\",\"header\":\"optional short tag\",\"multiSelect\":false,\"options\":[{\"label\":\"choice 1\",\"description\":\"optional detail\"},{\"label\":\"choice 2\"}]} (header, multiSelect, and options are all optional; options is max 3 choices, each with an optional one-line description; set multiSelect true to let the user pick more than one; omit options entirely for a free-text question — the user can always type a custom answer instead of picking a choice. Use this only when you're blocked on a decision that is genuinely the user's to make — one you can't resolve from the request, the code, or a sensible default. Don't use it to ask for permission to proceed or to confirm something you can just go do.)");
+        input_formats.push("- ask_user: {\"query\":\"short question\",\"header\":\"optional short tag\",\"multiSelect\":false,\"options\":[{\"label\":\"choice 1\",\"description\":\"optional detail\"},{\"label\":\"choice 2\"}]} (header, multiSelect, and options are all optional; options is max 3 choices, each with an optional one-line description; set multiSelect true to let the user pick more than one; omit options entirely for a free-text question — the user can always type a custom answer instead of picking a choice. Use this tool when you need the user's direction, or after proposing a plan/recommendation to ask how they want to proceed before mutating code. Avoid using it for trivial micro-steps that the user already explicitly authorized.)");
     }
     if allowed_actions.contains(&"detect_project") {
         input_formats.push("- detect_project: {\"path\":\".\"}");
@@ -451,6 +438,9 @@ pub fn build_system_prompt(
     let input_formats_str = input_formats.join("\n");
 
     let mut rules = Vec::new();
+    if allowed_actions.contains(&"mod_help") {
+        rules.push("MINT MODS: When asked to create or change a mod, call mod_help and mod_list first. Use the guide to draft the single-file source directly in mod_validate tool arguments, with at most one short progress sentence. Choose reasonable implementation defaults and proceed to validation. After validation succeeds, call mod_publish in execution mode if available; use expectedHash when replacing source. Creation is complete only after the publication result confirms the path in workspace/.mint-mods/<id>/ and activation state. In plan mode, present the draft/plan for approval. Follow the guide's bounded validation retries and report actual diagnostics if blocked.");
+    }
     if plan_mode {
         rules.push(
             "0p. PLAN MODE IS ACTIVE: you may only investigate (read files, search, inspect diagnostics, etc.). Mutating tools such as write_file, apply_patch, and most run_shell/mcp_tool/run_plugin calls are unavailable and will be blocked. Once you have a clear implementation plan, call exit_plan_mode with the full plan; the user will approve or reject it. Do not attempt to edit files or run mutating commands before that approval.",
@@ -469,6 +459,11 @@ pub fn build_system_prompt(
             "0. For casual conversation or questions that need no local tool, use finish immediately.",
         );
     }
+    if allowed_actions.contains(&"ask_user") {
+        rules.push(
+            "0q. When proposing plans, architectural options, or recommendations, do not treat casual affirmations (such as 'OK', 'ดีมาก', 'เข้าใจแล้ว') as immediate orders to modify code. Instead, call ask_user with clear options (Option 1 with '(Recommended)', alternative options, and allowing custom input) to confirm whether the user wants to execute the plan or merely review it.",
+        );
+    }
     if allowed_actions.contains(&"list_files") || allowed_actions.contains(&"read_file") {
         rules.push("1. Inspect the workspace before editing.");
         rules.push("1a. For user folders such as Downloads, Documents, Desktop, Pictures, Music, or Videos, use list_files with that folder name or ~/folder before using shell.");
@@ -492,7 +487,9 @@ pub fn build_system_prompt(
         || allowed_actions.contains(&"apply_patch")
     {
         rules.push("4. Shell commands and file edits require user approval. Mint handles approval after you request the tool.");
+        rules.push("4a. SKILL CHANGES: Create or edit reusable skills only when the user asks for that work. Otherwise complete the current task and suggest the skill in your summary. Use write_file or apply_patch for skill files so Mint can show the concrete diff and request approval for each change. A general file or session permission does not authorize changing persistent skill instructions. After approval, report the saved skill path and what changed.");
     }
+    rules.push("Execution evidence: distinguish succeeded, failed, running, cancelled and unknown. Inspect background jobs with shell_output before claiming completion. Retry a command after relevant changes or with retryReason, but observe ambiguous side effects before repeating them. finish.completionStatus must be verified, unverified, blocked or failed; a verification explanation cannot override failed or pending checks. When checks cannot run, finish honestly with unverified/blocked and the reason. Opening a browser or starting a process completes only that step, not the user's entire task.");
     if allowed_actions.contains(&"run_shell") {
         rules.push("5. Shell commands are classified as readOnly, test, network, or mutating. Only policy-allowed modes may run after approval. Never request destructive commands such as rm -rf, git reset --hard, git checkout --, or git clean -f.");
     }
@@ -520,8 +517,11 @@ pub fn build_system_prompt(
     if allowed_actions.contains(&"avatar_signal") {
         rules.push("7v. A Project Avatar is connected. Call avatar_signal when your reply carries an emotional beat the automatic tool-based reactions can't express — greeting, joking, apologizing, thinking something over. Don't call it for routine tool-driven turns (shell, browser, image/video generation); those already react on their own.");
     }
+    if allowed_actions.contains(&"run_shell") && !allowed_actions.contains(&"browser_open") {
+        rules.push("7a. For browsing, viewing, or capturing websites/webpages: use run_shell to run headless browser commands directly (e.g. google-chrome --headless=new --screenshot=screenshot.png <url>). ALWAYS call view_image with the generated image path (e.g. view_image(path: \"screenshot.png\")) immediately after capturing a screenshot so you and the user can inspect the visual result. Do NOT write ad-hoc Python scraping scripts (urllib, requests) or raw curl to scrape modern web pages when browser tools or headless chrome commands are available.");
+    }
     if allowed_actions.contains(&"browser_open") {
-        rules.push("7a. Use browser_open to navigate the virtual browser to a URL.");
+        rules.push("7a. Use browser_open to open websites; Mint starts an isolated browser session automatically (headless by default). Inspect the returned page observation, then use browser_observe/browser_read to read the page or browser_screenshot for visual inspection; verify the requested URL/content with browser_wait before finishing. A successful browser_open already opens the website for the user: do not also launch it through run_shell, xdg-open, open, Start-Process, or another browser. Keep website navigation and interaction in the automation browser. If the user explicitly requests an external browser, use that route instead of first opening the website in automation. If automation is unavailable or blocked, report that and ask the user before switching browsers. For a predefined command-line workflow, write a JSON steps file and run mint browser run --file <file> through run_shell; --headed explicitly shows its window. Use the shared engine rather than hand-written browser scripts. Web scraping restriction: NEVER write ad-hoc Python scripts (e.g., using urllib, requests, BeautifulSoup) or raw curl commands to scrape or inspect web pages. Modern websites require JavaScript rendering via the browser engine. Always prioritize browser_open when given a web URL.");
     }
     if allowed_actions.contains(&"browser_click") {
         rules.push("7b. Use browser_click to click elements. Selector can be: CSS selector (button.class, #id, [attr=val]), text=ExactText to find by visible text, contains=PartialText for partial match, or xpath=//expr for XPath. Prefer text= or contains= when the element has visible text but no unique CSS class.");
@@ -544,10 +544,10 @@ pub fn build_system_prompt(
         rules.push("7g. Use browser_key_press to press a keyboard key (e.g. Enter, Tab, Escape, ArrowDown). Use after browser_type or browser_mouse_click to interact with focused elements.");
     }
     if allowed_actions.contains(&"browser_screenshot") {
-        rules.push("7h. Use browser_screenshot to capture the current page as a PNG image (base64). Use it to inspect the visual state of the page before deciding where to click.");
+        rules.push("7h. Use browser_screenshot to capture the page as a durable image artifact, shown in chat and attached to the model. Use it to inspect the visual state of the page before deciding where to click, and to capture visual verification of page content for the user.");
     }
     if allowed_actions.contains(&"browser_observe") {
-        rules.push("7i. Browser workflow: browser_observe -> action -> inspect the returned observation -> verify the expected result with browser_wait. Each run starts in its own tab. Use browser_tabs to list/open/select/close tabs; select new popup tabs explicitly. Prefer elementRef from the most recent observation over guessing selectors. Old refs expire after observation refresh, navigation, removed nodes, or tab selection. browser_fill replaces text; browser_type appends. browser_select handles native dropdowns; browser_scroll scrolls the viewport or a target. browser_wait accepts condition url/text/visible/hidden, value or target, and timeoutMs (default 10000, maximum 30000). Observations support textOffset and elementOffset pagination. Coordinate actions require a screenshot of the selected tab within 30 seconds. Never retry an ambiguous click or submission automatically; observe and check the result first. input_dispatched is not task completion. Cite observed URL/text/field evidence in finish.verification, or say the task is unverified/blocked. If blocked by login, CAPTCHA, or repeated lack of progress, ask_user for manual takeover; only after user confirmation call browser_observe with takeoverComplete=true.");
+        rules.push("7i. Browser workflow: browser_observe -> action -> inspect the returned observation -> verify the expected result with browser_wait. Each run starts in its own tab. Use browser_tabs to list/open/select/close tabs; select new popup tabs explicitly. Prefer elementRef from the most recent observation over guessing selectors. Old refs expire after observation refresh, navigation, removed nodes, or tab selection. browser_fill replaces text; browser_type appends. browser_select handles native dropdowns; browser_scroll scrolls the viewport or a target. browser_wait accepts condition url/text/visible/hidden, value or target, and timeoutMs (default 10000, maximum 30000). Observations support textOffset and elementOffset pagination. Coordinate actions require a screenshot of the selected tab within 30 seconds. Never retry an ambiguous click or submission automatically; observe and check the result first. input_dispatched is not task completion. Cite observed URL/text/field evidence in finish.verification, or say the task is unverified/blocked. Age Gate & Cookie Consent Handling: If an age gate (18+ confirmation), cookie banner, or disclaimer modal blocks page content, locate standard confirmation buttons (e.g. \"I am 18 or older\", \"Enter Site\", \"Yes\", \"Agree\", \"Accept\") and dismiss it using browser_click. If the overlay presents sensitive warnings requiring explicit user discretion or consent, capture a browser_screenshot and use ask_user to confirm before proceeding. If blocked by login, CAPTCHA, or repeated lack of progress, ask_user for manual takeover; only after user confirmation call browser_observe with takeoverComplete=true.");
     }
     if allowed_actions.contains(&"memory_recall") {
         rules.push("8. Use memory_recall to search past interactions before asking the user to repeat context.");
@@ -556,7 +556,10 @@ pub fn build_system_prompt(
         rules.push("8a. Use git_status and git_diff before summarizing local code changes.");
     }
     if allowed_actions.contains(&"create_plan") || allowed_actions.contains(&"update_plan") {
-        rules.push("8b. When the user asks to plan, structure, or inspect a workflow ('วางแผน', 'plan', 'structure', 'audit'), call `create_plan` FIRST with your step checklist before doing deep execution. Keep investigation focused and concise: NEVER recursively read dozens of source files when a directory listing, symbols, search_code, or architectural overview is sufficient.");
+        rules.push("8b. Plan Mode & Pre-Planning Reconnaissance: When in plan mode or when the user asks to plan, structure, or inspect a workflow ('วางแผน', 'plan', 'structure', 'audit'), call `create_plan` FIRST with your step checklist before doing deep execution. When investigating, gathering facts across multiple files, tracing workflows, or verifying architecture, ALWAYS delegate broad exploration to parallel read-only subagents (`dispatch_agents` with base 'explorer') rather than sequentially reading dozens of files in the main turn. Subagents explore concurrently in isolated sandboxes and return concise dossiers, keeping your planning context clean and fast. Formulate your structured step checklist (`create_plan`) and final plan based on their synthesized findings.");
+    }
+    if allowed_actions.contains(&"dispatch_agents") {
+        rules.push("8c. Subagent Swarm Delegation (`dispatch_agents`): Delegate independent, broad, or exploratory tasks to parallel subagents to keep the main conversation context clean. Provide `tasks: [{ role, base, instruction }]`. In plan mode, all subagents run strictly read-only ('explorer') to gather reconnaissance without side-effects. Outside plan mode, read-only subagents run concurrently up to the parallel limit while write tasks serialize in a single lane. Subagents return capped structured dossiers directly back into your context — you synthesize their findings and present the final answer to the user.");
     }
     if allowed_actions.contains(&"note_write") {
         rules.push("9. Use note_write to save information to ~/.config/mint/notes/ when asked to remember something.");
@@ -588,11 +591,14 @@ For every JSON-backed card, ensure all properties stay inside their intended obj
 - Feature showcases: use fenced ```ui-card with JSON array:\n```ui-card\n[{\"title\": \"...\", \"subtitle\": \"...\", \"icon\": \"file-text\", \"badge\": \"...\", \"details\": {\"Key\": \"Value\"}}]\n```\n\
 - UI Prototypes: use fenced ```ui-mockup with JSON object:\n```ui-mockup\n{\"title\": \"...\", \"subtitle\": \"...\", \"dropzoneText\": \"...\", \"metrics\": {...}}\n```\n\
 - Key insights / alerts: use GitHub callouts (> [!NOTE], > [!TIP], > [!IMPORTANT], > [!WARNING]). Always converse naturally and smoothly; never prefix conversational phrases or greetings with artificial status tags or badge pills. Always put opening and closing ``` fences on their own separate lines.");
-    if native {
+    if allowed_actions.contains(&"browser_open") {
+        rules.push("12. Shell commands may open local files/folders or launch apps when requested. For websites, follow rule 7a and verify the automation browser's observed page; a shell launch is not evidence that a browser task is complete.");
+    } else if native {
         rules.push("12. Commands that open URLs, files, folders, or launch apps (e.g. xdg-open, open) run in the background. Once they succeed (exit: 0), you are done. Use the finish tool immediately.");
     } else {
         rules.push("12. Commands that open URLs, files, folders, or launch apps (e.g. xdg-open, open) run in the background. Once they succeed (exit: 0), you are done. Use the 'finish' action immediately.");
     }
+    rules.push("12a. Development servers and watchers must use run_shell with background: true so the tool returns a job_id immediately. For Python use python3 -u -m http.server <port>. Inspect shell_output and verify an HTTP response before claiming a server is ready; a job_id alone only proves it started. Keep existing background jobs alive when finishing a response or cancelling AI work, unless the user asks to stop them. Use kill_shell to stop only the requested job.");
     let mature_rule = format!("13. {}", persona::MATURE_CONTENT_POLICY);
     rules.push(&mature_rule);