@pheem49/mint 1.15.0 → 1.16.0

package/crates/mint-core/src/orchestration/tools/plugins_mcp.rs

@@ -1,6 +1,298 @@
 use std::path::Path;
 
 use super::super::*;
+use crate::integrations::mcp_result::{ToolOutcome, ToolStatus, normalize_mcp_result};
+
+pub(in crate::orchestration) async fn execute_mcp_outcome(
+    action: &str,
+    input: &AgentInput,
+    config: &MintConfig,
+    chat_id: &str,
+    call_id: &str,
+    approve: &mut (dyn FnMut(&AgentApproval) -> Result<ApprovalOutcome, String> + Send),
+    progress: &mut (dyn FnMut(AgentProgress) + Send),
+) -> Result<ToolOutcome, OrchestrationError> {
+    execute_reviewed(
+        action, input, config, chat_id, call_id, None, approve, progress,
+    )
+    .await
+}
+
+fn authorize(
+    cfg: &mut MintConfig,
+    server: &str,
+    tool: &str,
+    arguments: Value,
+    approve: &mut (dyn FnMut(&AgentApproval) -> Result<ApprovalOutcome, String> + Send),
+) -> Result<Option<ToolOutcome>, OrchestrationError> {
+    super::super::run_control::check()?;
+    if crate::mcp::is_mcp_tool_allowed(cfg, server, tool) {
+        return Ok(None);
+    }
+    let approval = approve(&AgentApproval::McpTool {
+        server: server.into(),
+        tool: tool.into(),
+        arguments,
+    })
+    .map_err(OrchestrationError::Agent)?;
+    super::super::run_control::check()?;
+    match approval {
+        ApprovalOutcome::Approved => {
+            crate::mcp::allow_tool_in(cfg, server, tool);
+        }
+        ApprovalOutcome::Intercepted(answer) if answer == MCP_ALLOW_ALL_SENTINEL => {
+            crate::mcp::allow_mcp_tool(server, "*")
+                .map_err(|e| OrchestrationError::Agent(e.to_string()))?;
+            crate::mcp::allow_tool_in(cfg, server, "*");
+        }
+        ApprovalOutcome::Denied => {
+            return Ok(Some(ToolOutcome::from(format!(
+                "User denied MCP tool call: {server} {tool}"
+            ))));
+        }
+        ApprovalOutcome::Intercepted(answer) => {
+            return Ok(Some(ToolOutcome {
+                text: format!(
+                    "MCP call was not approved; no command was executed. User feedback: {answer}"
+                ),
+                status: ToolStatus::Failed,
+                ..Default::default()
+            }));
+        }
+    }
+    Ok(None)
+}
+
+fn failure(error: crate::mcp::McpError) -> ToolOutcome {
+    use crate::mcp::McpError;
+    let status = match error {
+        McpError::Timeout | McpError::TimeoutUndelivered => ToolStatus::TimedOut,
+        McpError::Cancelled | McpError::CancelledUndelivered => ToolStatus::Cancelled,
+        _ => ToolStatus::Failed,
+    };
+    let text = if status == ToolStatus::TimedOut {
+        format!(
+            "Error: {error}; remote completion is unconfirmed. Do not automatically retry this operation."
+        )
+    } else {
+        format!("Error: {error}")
+    };
+    ToolOutcome {
+        text,
+        status,
+        ..Default::default()
+    }
+}
+
+/// Preparation returns an observation, never a command execution record.
+pub(in crate::orchestration) async fn prepare(
+    input: &AgentInput,
+    config: &MintConfig,
+    chat: &str,
+    review: &mut mcp_review::McpReview,
+    approve: &mut (dyn FnMut(&AgentApproval) -> Result<ApprovalOutcome, String> + Send),
+    progress: &mut (dyn FnMut(AgentProgress) + Send),
+) -> Result<Option<ToolOutcome>, OrchestrationError> {
+    let server = required(&input.server, "server")?;
+    let tool = required(&input.tool, "tool")?;
+    // Reading definitions is separately authorized and does not grant execution.
+    if !review.discovery_grants.contains(server)
+        && !crate::mcp::is_mcp_tool_allowed(config, server, tool)
+        && !crate::mcp::is_mcp_tool_allowed(config, server, "list_tools")
+    {
+        let mut cfg = config.clone();
+        if let Some(out) = authorize(
+            &mut cfg,
+            server,
+            "list_tools",
+            serde_json::json!({}),
+            approve,
+        )? {
+            return Ok(Some(out));
+        }
+        review.discovery_grants.insert(server.into());
+    }
+    let definition = match crate::mcp::catalog::describe_tool(config, server, tool, chat).await {
+        Ok(d) => d,
+        Err(e) => return Ok(Some(failure(e))),
+    };
+    let mut read = review.knows(server, tool, &definition.fingerprint, &definition.value);
+    if let Some(status) = crate::mcp::device::status_tool(&definition)
+        .map_err(|e| OrchestrationError::Agent(e.to_string()))?
+    {
+        let status_definition = crate::mcp::catalog::describe_tool(config, server, &status, chat)
+            .await
+            .map_err(|e| OrchestrationError::Agent(e.to_string()))?;
+        read = review.knows(
+            server,
+            &status,
+            &status_definition.fingerprint,
+            &status_definition.value,
+        ) && read;
+    }
+    if read {
+        return Ok(None);
+    }
+    let message="Tool definition loaded for the next model request. No tools/call was sent. Read its description and inputSchema, then submit the command with valid arguments.".to_string();
+    progress(AgentProgress::ToolDiscovery {
+        server: server.into(),
+        tool: tool.into(),
+        message: "Tool definition ready; preparing the command.".into(),
+    });
+    Ok(Some(ToolOutcome::from(message)))
+}
+
+#[allow(clippy::too_many_arguments)]
+pub(in crate::orchestration) async fn execute_reviewed(
+    action: &str,
+    input: &AgentInput,
+    config: &MintConfig,
+    chat_id: &str,
+    call_id: &str,
+    expected: Option<&mcp_review::McpReview>,
+    approve: &mut (dyn FnMut(&AgentApproval) -> Result<ApprovalOutcome, String> + Send),
+    progress: &mut (dyn FnMut(AgentProgress) + Send),
+) -> Result<ToolOutcome, OrchestrationError> {
+    let server = required(&input.server, "server")?;
+    let tool = if action == "mcp_tool" {
+        required(&input.tool, "tool")?
+    } else {
+        "list_tools"
+    };
+    let mut cfg = config.clone();
+    if action == "mcp_list_tools" {
+        if let Some(out) = authorize(&mut cfg, server, tool, input.arguments.clone(), approve)? {
+            return Ok(out);
+        }
+        return Ok(
+            match crate::mcp::catalog::list_tools(&cfg, server, chat_id).await {
+                Ok(v) => ToolOutcome::from(serde_json::to_string_pretty(&v).unwrap_or_default()),
+                Err(e) => failure(e),
+            },
+        );
+    }
+    let definition = match crate::mcp::catalog::describe_tool(&cfg, server, tool, chat_id).await {
+        Ok(d) => d,
+        Err(e) => return Ok(failure(e)),
+    };
+    if let Err(e) = definition.validate(&input.arguments) {
+        return Ok(failure(e));
+    }
+    if expected
+        .is_some_and(|r| r.fingerprint(server, tool) != Some(definition.fingerprint.as_str()))
+    {
+        return Ok(failure(crate::mcp::McpError::Preflight(
+            "Definition changed; read it again before executing".into(),
+        )));
+    }
+    let status_name = match crate::mcp::device::status_tool(&definition) {
+        Ok(s) => s,
+        Err(e) => return Ok(failure(e)),
+    };
+    let status_definition = if let Some(name) = &status_name {
+        let d = match crate::mcp::catalog::describe_tool(&cfg, server, name, chat_id).await {
+            Ok(d) => d,
+            Err(e) => return Ok(failure(e)),
+        };
+        if expected.is_some_and(|r| r.fingerprint(server, name) != Some(d.fingerprint.as_str())) {
+            return Ok(failure(crate::mcp::McpError::Preflight(
+                "Status definition changed; read it again before executing".into(),
+            )));
+        }
+        let preflight = (|| {
+            definition.output_validator()?;
+            d.valid_schema()?;
+            d.output_validator()?;
+            if crate::mcp::device::status_tool(&d)?.is_some() {
+                return Err(crate::mcp::McpError::Preflight(
+                    "statusTool must be a read-only observation tool without command metadata"
+                        .into(),
+                ));
+            }
+            d.validate(&serde_json::json!({"deviceId":input.arguments["deviceId"],"operationId":uuid::Uuid::new_v4().to_string()}))
+        })();
+        if let Err(e) = preflight {
+            return Ok(failure(e));
+        }
+        Some(d)
+    } else {
+        None
+    };
+    if let Some(out) = authorize(&mut cfg, server, tool, input.arguments.clone(), approve)? {
+        return Ok(out);
+    }
+    if let (Some(name), Some(status_definition)) = (status_name, status_definition) {
+        if let Some(out) = authorize(
+            &mut cfg,
+            server,
+            &name,
+            serde_json::json!({"deviceId":input.arguments["deviceId"],"operationId":"<operationId returned by this command>","scope":"Read status only for this command until its deadline"}),
+            approve,
+        )? {
+            return Ok(out);
+        }
+        // Both event callbacks share the sink but are invoked sequentially.
+        let sink = std::sync::Mutex::new(progress);
+        let result = crate::mcp::device::call_verified(
+            &cfg,
+            server,
+            tool,
+            input.arguments.clone(),
+            chat_id,
+            definition,
+            &name,
+            status_definition,
+            |update| {
+                sink.lock().unwrap()(AgentProgress::ToolProgress {
+                    call_id: call_id.into(),
+                    server: server.into(),
+                    tool: tool.into(),
+                    update,
+                })
+            },
+            |update| {
+                sink.lock().unwrap()(AgentProgress::DeviceState {
+                    call_id: call_id.into(),
+                    server: server.into(),
+                    tool: tool.into(),
+                    update,
+                })
+            },
+        )
+        .await;
+        let mut out = normalize_mcp_result(result.receipt, chat_id, call_id, server);
+        out.status = result.status;
+        out.completion_unconfirmed = result.completion_unconfirmed;
+        out.text.push_str(&format!("\n{}", result.message));
+        if out.status != ToolStatus::Success && !out.text.starts_with("Error:") {
+            out.text.insert_str(0, "Error: ");
+        }
+        return Ok(out);
+    }
+    Ok(
+        match crate::mcp::call_mcp_tool_reviewed(
+            &cfg,
+            server,
+            tool,
+            input.arguments.clone(),
+            chat_id,
+            Some(&definition.fingerprint),
+            |update| {
+                progress(AgentProgress::ToolProgress {
+                    call_id: call_id.into(),
+                    server: server.into(),
+                    tool: tool.into(),
+                    update,
+                })
+            },
+        )
+        .await
+        {
+            Ok(v) => normalize_mcp_result(v, chat_id, call_id, server),
+            Err(e) => failure(e),
+        },
+    )
+}
 
 /// Handles the subset of `execute_tool` actions related to plugins mcp.
 /// Only called for actions `execute_tool` has already routed here, so the
@@ -37,79 +329,19 @@ pub(in crate::orchestration) async fn execute(
             let task = required(&input.instruction, "instruction")?;
             dispatch_one_subagent(root, config, chat_id, name, task, approve_cb, progress).await
         }
-        "mcp_tool" => {
-            let server = required(&input.server, "server")?;
-            let tool = required(&input.tool, "tool")?;
-            let args = input.arguments.clone();
-            let run = |cfg: &MintConfig| -> Result<String, OrchestrationError> {
-                serde_json::to_string_pretty(
-                    &crate::mcp::call_mcp_tool(cfg, server, tool, args.clone())
-                        .map_err(|e| OrchestrationError::Agent(e.to_string()))?,
-                )
-                .map_err(|e| OrchestrationError::Agent(e.to_string()))
-            };
-            mcp_approve_then_run(server, tool, &args, config, approve_cb, run)
-        }
-        "mcp_list_tools" => {
-            let server = required(&input.server, "server")?;
-            let run = |cfg: &MintConfig| -> Result<String, OrchestrationError> {
-                serde_json::to_string_pretty(
-                    &crate::mcp::list_server_tools(cfg, server)
-                        .map_err(|e| OrchestrationError::Agent(e.to_string()))?,
-                )
-                .map_err(|e| OrchestrationError::Agent(e.to_string()))
-            };
-            mcp_approve_then_run(
-                server,
-                "list_tools",
-                &serde_json::json!({}),
-                config,
-                approve_cb,
-                run,
-            )
-        }
+        "mcp_tool" | "mcp_list_tools" => execute_mcp_outcome(
+            action,
+            input,
+            config,
+            chat_id,
+            &uuid::Uuid::new_v4().to_string(),
+            approve_cb,
+            progress,
+        )
+        .await
+        .map(|out| out.text),
         _ => unreachable!(
             "execute_tool routed an unhandled action into tools::plugins_mcp::execute: {action}"
         ),
     }
 }
-
-/// Shared gate for `mcp_tool` / `mcp_list_tools`:
-///  * a server already trusted via `allowedMcpTools` runs `run` with no prompt;
-///  * otherwise the user is asked. "Allow all (*)" (the
-///    [`MCP_ALLOW_ALL_SENTINEL`] answer) persists `allowedMcpTools[server] =
-///    ["*"]` and then runs against the freshly reloaded config, so the same
-///    server never prompts again;
-///  * a plain approve runs once; deny / free-text feedback is returned as-is.
-fn mcp_approve_then_run(
-    server: &str,
-    tool: &str,
-    arguments: &serde_json::Value,
-    config: &MintConfig,
-    approve_cb: &mut (dyn FnMut(&AgentApproval) -> Result<ApprovalOutcome, String> + Send),
-    run: impl Fn(&MintConfig) -> Result<String, OrchestrationError>,
-) -> Result<String, OrchestrationError> {
-    if crate::mcp::is_mcp_tool_allowed(config, server, tool) {
-        return run(config);
-    }
-
-    let outcome = approve_cb(&AgentApproval::McpTool {
-        server: server.to_owned(),
-        tool: tool.to_owned(),
-        arguments: arguments.clone(),
-    })
-    .map_err(OrchestrationError::Agent)?;
-
-    match outcome {
-        ApprovalOutcome::Approved => run(config),
-        ApprovalOutcome::Intercepted(answer) if answer == MCP_ALLOW_ALL_SENTINEL => {
-            crate::mcp::allow_mcp_tool(server, "*")
-                .map_err(|e| OrchestrationError::Agent(e.to_string()))?;
-            let reloaded =
-                crate::load_config().map_err(|e| OrchestrationError::Agent(e.to_string()))?;
-            run(&reloaded)
-        }
-        ApprovalOutcome::Denied => Ok(format!("User denied MCP tool call: {server} {tool}")),
-        ApprovalOutcome::Intercepted(obs) => Ok(obs),
-    }
-}

package/crates/mint-core/src/orchestration/tools/shell.rs

@@ -2,6 +2,40 @@ use std::path::Path;
 
 use super::super::*;
 
+/// Catch ordinary URL launcher commands, not arbitrary shell programs. This is
+/// a workflow guard, not a shell security boundary.
+fn launches_external_url(command: &str) -> bool {
+    let Some(tokens) = shlex::split(command) else {
+        return false;
+    };
+    let Some(program) = tokens.first() else {
+        return false;
+    };
+    let program = program.rsplit(['/', '\\']).next().unwrap_or(program);
+    let launcher = match program.to_ascii_lowercase().as_str() {
+        "xdg-open" | "open" | "wslview" | "sensible-browser" | "start-process" | "start" => true,
+        "gio" => tokens.get(1).is_some_and(|arg| arg == "open"),
+        _ => false,
+    };
+    launcher
+        && tokens.iter().skip(1).any(|arg| {
+            reqwest::Url::parse(arg).is_ok_and(|url| {
+                matches!(url.scheme(), "http" | "https") && url.host_str().is_some()
+            })
+        })
+}
+
+pub(in crate::orchestration) async fn prevent_duplicate_browser_launch(
+    command: &str,
+) -> Result<(), OrchestrationError> {
+    if launches_external_url(command) && crate::browser::session_finish_evidence().await {
+        return Err(OrchestrationError::Agent(
+            "External URL launch skipped: this task already uses the automation browser. Use browser_observe/browser_read to inspect its current page, browser_screenshot for visual inspection, or browser_open if navigation is still needed. Do not open the same URL in another browser.".into(),
+        ));
+    }
+    Ok(())
+}
+
 /// Handles the subset of `execute_tool` actions related to shell.
 /// Only called for actions `execute_tool` has already routed here, so the
 /// fallback arm is unreachable in practice.
@@ -16,6 +50,7 @@ pub(in crate::orchestration) async fn execute(
     match action {
         "run_shell" => {
             let command = required(&input.command, "command")?;
+            prevent_duplicate_browser_launch(command).await?;
             let mode = classify_shell_command(command).mode.as_str().to_owned();
             let approved = approve_cb(&AgentApproval::RunShell {
                 command: command.to_owned(),
@@ -26,8 +61,11 @@ pub(in crate::orchestration) async fn execute(
 
             match approved {
                 ApprovalOutcome::Approved if input.background => {
-                    let started = crate::bg_shell::start_background(root, config, command)
-                        .map_err(|e| OrchestrationError::Agent(e.to_string()))?;
+                    let started = crate::bg_shell::with_context(
+                        crate::bg_shell::chat_context(root, chat_id),
+                        || crate::bg_shell::start_background(root, config, command),
+                    )
+                    .map_err(|e| OrchestrationError::Agent(e.to_string()))?;
                     Ok(format!(
                         "job_id: {}\npid: {}\nstatus: running\nUse the 'shell_output' tool with this job_id to check on it, and 'kill_shell' to stop it.",
                         started.id,
@@ -43,11 +81,27 @@ pub(in crate::orchestration) async fn execute(
         }
         "shell_output" => {
             let job_id = required(&input.job_id, "job_id")?;
+            if !crate::bg_shell::accessible(
+                job_id,
+                &crate::bg_shell::chat_context(root, chat_id).owner,
+            ) {
+                return Err(OrchestrationError::Agent(
+                    "No accessible background job with that id".into(),
+                ));
+            }
             crate::bg_shell::poll_output(job_id)
                 .map_err(|e| OrchestrationError::Agent(e.to_string()))
         }
         "kill_shell" => {
             let job_id = required(&input.job_id, "job_id")?;
+            if !crate::bg_shell::accessible(
+                job_id,
+                &crate::bg_shell::chat_context(root, chat_id).owner,
+            ) {
+                return Err(OrchestrationError::Agent(
+                    "No accessible background job with that id".into(),
+                ));
+            }
             crate::bg_shell::kill_job(job_id).map_err(|e| OrchestrationError::Agent(e.to_string()))
         }
         "verify" => {
@@ -163,3 +217,42 @@ pub(in crate::orchestration) async fn execute(
         ),
     }
 }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    #[test]
+    fn external_url_launch_detection_preserves_other_shell_work() {
+        for command in [
+            "xdg-open 'https://example.com/watch?v=1&list=2'",
+            "/usr/bin/xdg-open https://example.com &",
+            "open -a Firefox https://example.com",
+            "gio open https://example.com",
+            "wslview https://example.com",
+            "Start-Process https://example.com",
+        ] {
+            assert!(launches_external_url(command), "{command}");
+        }
+        for command in [
+            "xdg-open /tmp/report.pdf",
+            "open /tmp",
+            "curl https://example.com",
+            "echo xdg-open https://example.com",
+            "gio info https://example.com",
+            "cargo test",
+        ] {
+            assert!(!launches_external_url(command), "{command}");
+        }
+    }
+
+    #[tokio::test]
+    async fn external_url_launch_allowed_without_browser_use() {
+        crate::browser::run_session(async {
+            prevent_duplicate_browser_launch("xdg-open https://example.com")
+                .await
+                .unwrap();
+        })
+        .await;
+    }
+}

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

@@ -189,6 +189,7 @@ pub(super) async fn run_shell(
     chat_id: &str,
     command: &str,
 ) -> Result<String, OrchestrationError> {
+    tools::shell::prevent_duplicate_browser_launch(command).await?;
     let root = root.to_path_buf();
     let config = config.clone();
     let chat_id = chat_id.to_owned();
@@ -196,7 +197,9 @@ pub(super) async fn run_shell(
     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), || {
+                run_shell_command(&command, &root, true, &config, Some(&chat_id))
+            })
         })
         .await
         .map_err(|e| OrchestrationError::Agent(format!("shell command task panicked: {e}")))?

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

@@ -46,6 +46,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",
@@ -102,6 +105,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",
@@ -185,6 +192,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)",
@@ -451,6 +459,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.",
@@ -492,6 +503,7 @@ 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.");
     }
     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.");
@@ -521,7 +533,7 @@ pub fn build_system_prompt(
         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 navigate the virtual browser to a URL.");
+        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.");
@@ -588,11 +600,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);
 

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

@@ -136,6 +136,32 @@ fn finish_tool() -> ToolSpec {
 
 fn all_tools() -> Vec<ToolSpec> {
     vec![
+        tool(
+            "mod_help",
+            "Read the Mint Mods authoring guide. Call before creating or editing a mod from a user prompt.",
+            schema(json!({}), &[]),
+        ),
+        tool(
+            "mod_list",
+            "Inspect workspace mods, sources, hashes, permissions and active revisions.",
+            schema(json!({}), &[]),
+        ),
+        tool(
+            "mod_validate",
+            "Compile and preview a single-file Mint mod without running real tools. Follow mod_help; fix errors before publishing.",
+            schema(
+                json!({"arguments":{"type":"object","properties":{"manifest":{"type":"object"},"source":{"type":"string"},"readme":{"type":"string"}},"required":["manifest","source"]}}),
+                &["arguments"],
+            ),
+        ),
+        tool(
+            "mod_publish",
+            "Publish a validated mod in workspace/.mint-mods/<id> and open it in this chat. Use only when the user requests mod creation/editing. Requested special permissions require approval. Existing source requires expectedHash.",
+            schema(
+                json!({"arguments":{"type":"object","properties":{"manifest":{"type":"object"},"source":{"type":"string"},"readme":{"type":"string"},"expectedHash":{"type":"string"}},"required":["manifest","source"]}}),
+                &["arguments"],
+            ),
+        ),
         tool(
             "conversation_summary",
             "Internal tool representing a compacted conversation history summary from previous steps.",
@@ -655,7 +681,7 @@ fn all_tools() -> Vec<ToolSpec> {
         tool(
             "run_shell",
             "Run a local shell command. Subject to safety classification and user approval; destructive commands are blocked outright. \
-             Set 'background' to true for a long-running command (a dev server, a watcher, ...) so it doesn't \
+             Always set 'background' to true for development servers and watchers. For example: {command: 'python3 -u -m http.server 8000', background: true}. Check output and HTTP readiness before claiming the server is ready. Set 'background' to true for a long-running command (a dev server, a watcher, ...) so it doesn't \
              block you — it returns a job_id immediately instead of waiting for the command to exit. Use the \
              'shell_output' tool to check on it later and 'kill_shell' to stop it.",
             schema(
@@ -750,7 +776,7 @@ fn all_tools() -> Vec<ToolSpec> {
         ),
         tool(
             "apply_patch",
-            "Apply one or more find-and-replace hunks to an existing file. This is the only way to edit existing files (write_file is for new files only). Keep oldText minimal (1-3 exact lines) per hunk; use separate hunks for separate edit locations.",
+            "Apply one or more find-and-replace hunks to an existing file. Pass patch as a JSON object, never a JSON-encoded string: {\"patch\":{\"path\":\"style.css\",\"hunks\":[{\"oldText\":\"exact existing text\",\"newText\":\"replacement text\"}]}}. This is the only way to edit existing files (write_file is for new files only). Keep oldText minimal (1-3 exact lines) per hunk; use separate hunks for separate edit locations.",
             schema(
                 json!({
                     "patch": {