@pheem49/mint 1.16.0 → 1.18.0

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

@@ -10,9 +10,7 @@ pub(super) fn looks_skill_worthy(step: usize, action_counts: &BTreeMap<String, u
         "apply_patch",
         "write_file",
         "run_shell",
-        "browser_open",
-        "browser_click",
-        "browser_type",
+        "dispatch_agents",
         "dispatch_subagent",
     ];
     step >= 3
@@ -25,17 +23,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 +44,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 +59,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 +82,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,37 +215,44 @@ 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 || {
             crate::bg_shell::with_context(crate::bg_shell::chat_context(&root, &chat_id), || {
-                run_shell_command(&command, &root, true, &config, Some(&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}")))?
         .map_err(|e| OrchestrationError::Agent(e.to_string()))?
     };
-    let status_str = output
-        .status
-        .map_or_else(|| "unknown".into(), |status| status.to_string());
+    let status_str = if let Some(job_id) = &output.job_id {
+        format!("running_in_background (job_id: {job_id})")
+    } else {
+        output
+            .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
@@ -226,9 +260,24 @@ pub(super) async fn run_shell(
         .map(|warning| format!("\n[Warning] {warning}"))
         .unwrap_or_default();
 
+    let notice = if let Some(job_id) = &output.job_id {
+        format!(
+            "\n[SYSTEM NOTICE] The command exceeded 180s and is STILL RUNNING in the background (job_id: {job_id}). \
+             DO NOT retry or run an alternative script. Use shell_output(job_id: \"{job_id}\") to monitor its progress.\n"
+        )
+    } else {
+        String::new()
+    };
+
     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,
+        notice,
+        output.stdout,
+        output.stderr
     ))
 }
 

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

@@ -1,33 +1,6 @@
 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
-        .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()
-            })
-        })
-}
-
 pub(crate) const PLAN_MODE_ALLOWED_ACTIONS: &[&str] = &[
     "list_files",
     "read_file",
@@ -65,13 +38,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.
@@ -79,7 +45,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
@@ -88,7 +55,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",
@@ -172,14 +138,15 @@ pub fn build_system_prompt(
 ) -> String {
     let mut allowed_actions = base_allowed_actions();
 
-    if browser_endpoint_available(config) {
-        allowed_actions.extend_from_slice(crate::browser::BROWSER_TOOLS);
-    }
-
     if !config.avatar_token.is_empty() {
         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));
@@ -257,34 +224,6 @@ pub fn build_system_prompt(
     if allowed_actions.contains(&"calculation") {
         input_formats.push("- calculation: {\"expression\":\"math or percentage expression e.g. 25% of 8500 or 100 * 3.5\"}");
     }
-    if allowed_actions.contains(&"browser_open") {
-        input_formats.push("- browser_open: {\"url\":\"https://example.com\"}");
-    }
-    if allowed_actions.contains(&"browser_observe") {
-        input_formats.push("- browser_observe: {textOffset?:number,elementOffset?:number,takeoverComplete?:boolean}; browser_tabs: {operation:list|open|select|close,tabId?:string,url?:string}; browser_fill: {elementRef?:string,selector?:string,text:string}; browser_select: {elementRef?:string,selector?:string,value:string}; browser_scroll: {elementRef?:string,selector?:string,x?:number,y?:number}; browser_wait: {condition:url|text|visible|hidden,value?:string,elementRef?:string,selector?:string,timeoutMs?:number}. browser_click/browser_type also accept elementRef instead of selector.");
-    }
-    if allowed_actions.contains(&"browser_click") {
-        input_formats.push("- browser_click: {\"selector\":\"button.submit-btn\"} (CSS selector, or text=Login, contains=Submit, xpath=//button)");
-    }
-    if allowed_actions.contains(&"browser_type") {
-        input_formats
-            .push("- browser_type: {\"selector\":\"input.search-bar\", \"text\":\"search query\"} (CSS selector, or text=Placeholder, contains=Label)");
-    }
-    if allowed_actions.contains(&"browser_read") {
-        input_formats.push("- browser_read: {}");
-    }
-    if allowed_actions.contains(&"browser_mouse_move") {
-        input_formats.push("- browser_mouse_move: {\"x\":640,\"y\":360}");
-    }
-    if allowed_actions.contains(&"browser_mouse_click") {
-        input_formats.push("- browser_mouse_click: {\"x\":640,\"y\":360,\"button\":\"left\"}");
-    }
-    if allowed_actions.contains(&"browser_key_press") {
-        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: {}");
-    }
     if allowed_actions.contains(&"memory_recall") {
         input_formats.push("- memory_recall: {\"query\":\"what did user say about X\"}");
     }
@@ -314,7 +253,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\":\".\"}");
@@ -480,6 +419,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.");
@@ -505,6 +449,7 @@ pub fn build_system_prompt(
         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. When a command reports running_in_background, the process is actively executing — do not restart or retry it with an alternative approach. 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.");
     }
@@ -512,7 +457,9 @@ pub fn build_system_prompt(
         rules.push("6. Verify code changes when possible. If compile or test commands fail (exit status is not 0), analyze the stdout/stderr to locate the bug, edit the code to fix it, and verify again. Do not stop or give up until the errors are resolved.");
     }
     if allowed_actions.contains(&"web_search") {
-        rules.push("7. Use web_search when the user asks to look something up online or needs current information.");
+        rules.push("7. Use web_search when the user asks to look something up online or needs current information.\n\
+- Information Sufficiency: If web_search results already contain the direct answer, official links, social profiles, or overview the user asked for, synthesize the final answer and call `finish` immediately. Do NOT run redundant searches or launch headless Chrome.\n\
+- Follow-up Gate: If search results are incomplete, ambiguous, or if further research could be explored, DO NOT run arbitrary loops or crawl pages autonomously. Instead, summarize what you found so far and call `ask_user` with clear options to confirm whether the user wants to search further and what specific topics or links to explore next.");
     }
     if allowed_actions.contains(&"image_search") {
         rules.push("7i. Use image_search when the user explicitly wants to see, browse, or find pictures/photos of something. Do NOT use it just to decorate a text answer — web_search already attaches a thumbnail automatically when relevant. ALWAYS copy the ```image_search_json ... ``` block from the tool observation into your final summary text so the UI card renders.");
@@ -532,34 +479,8 @@ 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(&"browser_open") {
-        rules.push("7a. Use browser_open to open websites in the automation browser. 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.");
-    }
-    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.");
-    }
-    if allowed_actions.contains(&"browser_type") {
-        rules.push("7c. Use browser_type to enter text into form fields or search boxes. Selector supports the same formats as browser_click.");
-    }
-    if allowed_actions.contains(&"browser_read") {
-        rules.push(
-            "7d. Use browser_read to read the text content of the active page to analyze it.",
-        );
-    }
-    if allowed_actions.contains(&"browser_mouse_move") {
-        rules.push("7e. Use browser_mouse_move to move the real mouse cursor to absolute (x,y) coordinates.");
-    }
-    if allowed_actions.contains(&"browser_mouse_click") {
-        rules.push("7f. Use browser_mouse_click to perform a native mouse click at (x,y) coordinates. Use browser_screenshot first to find the target position.");
-    }
-    if allowed_actions.contains(&"browser_key_press") {
-        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.");
-    }
-    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.");
+    if allowed_actions.contains(&"run_shell") {
+        rules.push("7a. Headless Chrome through run_shell is for deep webpage inspection or rendering, NOT for routine web searches. Use it ONLY when: (a) the user explicitly requests inspecting, reading, or scraping a specific webpage/URL, (b) web_search snippets were blocked or insufficient and direct page reading is required, or (c) rendering local HTML. Never recursively crawl external links found on a page. Mint adds the reliability flags, a throw-away profile and a timeout for you, so write the plain command. (1) Read a page first with `google-chrome --dump-dom <url>` (runs JavaScript, so SPAs work; far cheaper than an image). (2) Only when the visual layout matters: `google-chrome --screenshot=<file>.png <url>` (add --window-size=W,H for a tall or narrow view), then call view_image with that path exactly once per image; a repeated image is not attached again. (3) Never capture the same URL with the same options twice in a turn; Mint refuses repeats unless you pass retryReason because the page really changed. If a result is not what you need, change the URL or options instead of repeating. (4) For clicking, typing or multi-step flows, write a JSON steps file and run `mint browser run --file <file>`. Do NOT scrape modern pages with ad-hoc Python (urllib, requests) or raw curl.");
     }
     if allowed_actions.contains(&"memory_recall") {
         rules.push("8. Use memory_recall to search past interactions before asking the user to repeat context.");
@@ -568,7 +489,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.");
@@ -600,14 +524,13 @@ 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 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 {
+    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.");
+    rules.push("12b. When a command is moved to the background or reports running_in_background, the process is actively executing. NEVER rerun, rewrite, or switch approaches. You must use shell_output to await its completion.");
     let mature_rule = format!("13. {}", persona::MATURE_CONTENT_POLICY);
     rules.push(&mature_rule);
 
@@ -649,3 +572,47 @@ For every JSON-backed card, ensure all properties stay inside their intended obj
     }
     prompt
 }
+
+#[cfg(test)]
+mod headless_playbook_tests {
+    use super::*;
+
+    fn shell_mode_prompt() -> String {
+        let config = MintConfig::default();
+        build_system_prompt(&config, false, false, None, None)
+    }
+
+    #[test]
+    fn shell_mode_teaches_the_headless_chrome_playbook() {
+        let prompt = shell_mode_prompt();
+        for needle in [
+            "--dump-dom",
+            "--screenshot=",
+            "view_image",
+            "once per image",
+            "same URL",
+            "mint browser run",
+        ] {
+            assert!(prompt.contains(needle), "playbook is missing {needle:?}");
+        }
+        assert!(
+            !prompt.contains("browser_open"),
+            "no browser_* tools in shell mode"
+        );
+    }
+
+    #[test]
+    fn web_search_playbook_enforces_information_sufficiency_and_ask_user_gate() {
+        let prompt = shell_mode_prompt();
+        for needle in [
+            "Information Sufficiency",
+            "call `ask_user` with clear options",
+            "Never recursively crawl",
+        ] {
+            assert!(
+                prompt.contains(needle),
+                "web search playbook is missing {needle:?}"
+            );
+        }
+    }
+}