anveesa 0.2.3 → 0.2.5

package/Cargo.lock

@@ -54,7 +54,7 @@ dependencies = [
 
 [[package]]
 name = "anveesa"
-version = "0.2.3"
+version = "0.2.5"
 dependencies = [
  "anyhow",
  "base64",

package/Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "anveesa"
-version = "0.2.3"
+version = "0.2.5"
 edition = "2024"
 default-run = "anveesa"
 

package/README.md

@@ -63,6 +63,26 @@ sessions (stored next to the config as `history`). The active conversation is
 stored next to it as `session.json`. Use the up/down arrows to recall previous
 prompts.
 
+To include an image, copy it to the clipboard and run `/attach` before your
+question:
+
+```text
+❯ /attach
+  [image attached for the next message]
+❯ what is in this screenshot?
+```
+
+You can also attach an image file directly:
+
+```text
+❯ /attach ./screenshot.png
+❯ explain this UI
+```
+
+Image input works with OpenAI-compatible providers and models that support
+vision. Terminals do not paste image pixels into the text prompt itself, so use
+`/attach` instead of pressing paste and expecting the image to appear inline.
+
 `ctx:on` means Anveesa sends lightweight terminal context with each request:
 current directory, parent directory, git root/branch/status when available, and
 a capped directory listing. This lets the model answer questions like "where are

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "anveesa",
-  "version": "0.2.3",
+  "version": "0.2.5",
   "description": "A terminal CLI that wraps AI providers (OpenAI-compatible APIs and local CLIs) into a single unified command",
   "main": "bin/anveesa.js",
   "bin": {

package/src/lib.rs

@@ -12,13 +12,11 @@ use std::{
 };
 
 use anyhow::{Context, Result, bail};
+use base64::{Engine, engine::general_purpose::STANDARD as BASE64};
 use clap::{CommandFactory, Parser};
 use serde::{Deserialize, Serialize};
 use tokio::sync::mpsc;
 
-#[cfg(target_os = "macos")]
-use base64::{Engine, engine::general_purpose::STANDARD as BASE64};
-
 use crate::{
     cli::{AskOptions, Cli, Command, ConfigCommand},
     config::{
@@ -80,6 +78,7 @@ async fn run_interactive(options: AskOptions) -> Result<()> {
         .get(&provider_name)
         .with_context(|| format!("unknown provider '{provider_name}'"))?;
     let tools_available = matches!(provider, ProviderConfig::OpenAiCompatible(_));
+    let images_available = matches!(provider, ProviderConfig::OpenAiCompatible(_));
     let model = options
         .model
         .clone()
@@ -122,6 +121,7 @@ async fn run_interactive(options: AskOptions) -> Result<()> {
     // Fingerprint of the last clipboard image we attached — prevents re-attaching
     // the same screenshot on every subsequent turn until the user copies something new.
     let mut last_image_fp: Option<String> = None;
+    let mut pending_image: Option<ImageAttachment> = None;
     let mut paste_count = 0usize;
 
     loop {
@@ -148,6 +148,7 @@ async fn run_interactive(options: AskOptions) -> Result<()> {
             "/clear" => {
                 history.clear();
                 last_image_fp = None;
+                pending_image = None;
                 paste_count = 0;
                 if let Some(path) = &session_path {
                     let _ = fs::remove_file(path);
@@ -157,12 +158,31 @@ async fn run_interactive(options: AskOptions) -> Result<()> {
             }
             _ => {}
         }
+        if let Some(path) = parse_attach_command(&prompt) {
+            if !images_available {
+                eprintln!("error: image attachments require an openai-compatible provider");
+                continue;
+            }
+
+            match attach_image(path.as_deref()) {
+                Ok(image) => {
+                    last_image_fp = Some(image_fingerprint(&image));
+                    pending_image = Some(image);
+                    eprintln!("\x1b[90m  [image attached for the next message]\x1b[0m");
+                }
+                Err(error) => eprintln!("error: {error:#}"),
+            }
+            continue;
+        }
         if let Some(path) = &history_path {
             let _ = append_repl_history(path, prompt.as_str());
         }
 
-        // Check clipboard for a new screenshot. Skip if it's the same image as last turn.
-        let image = if is_tty {
+        // Use an explicitly attached image first. Otherwise, keep the legacy
+        // convenience behavior: attach a newly copied clipboard image once.
+        let image = if pending_image.is_some() {
+            pending_image.take()
+        } else if is_tty && images_available {
             grab_clipboard_image().and_then(|img| {
                 let fp = image_fingerprint(&img);
                 if last_image_fp.as_deref() == Some(&fp) {
@@ -302,13 +322,14 @@ async fn render_stream(
     let mut spinner_active = false;
     let mut first_token = true;
     let mut produced = false;
+    let mut line_open = false;
     let mut usage: Option<Usage> = None;
     let mut plan_tasks: Vec<String> = vec![];
     let mut plan_done: Vec<bool> = vec![];
 
     static TIPS: &[&str] = &[
         "Tip: type /clear to reset context",
-        "Tip: paste a screenshot and ask about it",
+        "Tip: copy an image, then type /attach",
         "Tip: use --yes to auto-approve file edits",
         "Tip: type /exit to leave the session",
     ];
@@ -326,13 +347,29 @@ async fn render_stream(
                         first_token = false;
                     }
                     produced = true;
+                    line_open = true;
                     print!("{text}");
                     let _ = io::stdout().flush();
                 }
                 Some(StreamEvent::Usage(value)) => usage = Some(value),
+                Some(StreamEvent::ToolCall { summary }) => {
+                    clear_spinner(spinner, spinner_active);
+                    spinner_active = false;
+                    if line_open {
+                        println!();
+                        line_open = false;
+                    }
+                    print_tool_call(&summary, spinner);
+                    first_token = true;
+                    frame = 0;
+                }
                 Some(StreamEvent::Confirm { preview, reply }) => {
                     clear_spinner(spinner, spinner_active);
                     spinner_active = false;
+                    if line_open {
+                        println!();
+                        line_open = false;
+                    }
                     let decision = tokio::task::block_in_place(|| {
                         show_confirm_preview(&preview, spinner);
                         prompt_confirm_decision(spinner)
@@ -345,6 +382,10 @@ async fn render_stream(
                 Some(StreamEvent::FileOp { verb, path, added, removed, preview, truncated }) => {
                     clear_spinner(spinner, spinner_active);
                     spinner_active = false;
+                    if line_open {
+                        println!();
+                        line_open = false;
+                    }
                     print_file_op(&verb, &path, added, removed, &preview, truncated, spinner);
                     // Re-arm the spinner for the next API round.
                     first_token = true;
@@ -353,6 +394,10 @@ async fn render_stream(
                 Some(StreamEvent::PlanSet { tasks }) => {
                     clear_spinner(spinner, spinner_active);
                     spinner_active = false;
+                    if line_open {
+                        println!();
+                        line_open = false;
+                    }
                     plan_done = vec![false; tasks.len()];
                     plan_tasks = tasks;
                     print_plan_list(&plan_tasks, &plan_done, spinner);
@@ -362,6 +407,10 @@ async fn render_stream(
                 Some(StreamEvent::PlanTaskDone { index }) => {
                     clear_spinner(spinner, spinner_active);
                     spinner_active = false;
+                    if line_open {
+                        println!();
+                        line_open = false;
+                    }
                     if index < plan_done.len() {
                         plan_done[index] = true;
                     }
@@ -398,7 +447,7 @@ async fn render_stream(
         }
     }
 
-    if produced {
+    if produced && line_open {
         println!();
     } else {
         clear_spinner(spinner, spinner_active);
@@ -426,6 +475,14 @@ async fn render_stream(
     }
 }
 
+fn print_tool_call(summary: &str, is_tty: bool) {
+    if is_tty {
+        eprintln!("\x1b[90m  └─ {summary}\x1b[0m");
+    } else {
+        eprintln!("tool: {summary}");
+    }
+}
+
 fn print_file_op(
     verb: &str,
     path: &str,
@@ -881,6 +938,7 @@ fn print_session_header(
     row("", "", "  Commands", bg);
     row(&info, dm, "  /clear   reset memory", cy);
     row(&cwd_line, dm, "  /exit    quit session", cy);
+    row("", "", "  /attach  attach image", cy);
     row("", "", approve, cy);
     row("", "", "", "");
 
@@ -1237,17 +1295,138 @@ fn image_fingerprint(img: &ImageAttachment) -> String {
     format!("{}:{}", img.data.len(), prefix)
 }
 
+fn parse_attach_command(prompt: &str) -> Option<Option<String>> {
+    for command in ["/attach", "/image", "/img"] {
+        if prompt == command {
+            return Some(None);
+        }
+        if let Some(rest) = prompt.strip_prefix(command)
+            && rest.chars().next().is_some_and(char::is_whitespace)
+        {
+            let path = unquote_path(rest.trim());
+            if !path.is_empty() {
+                return Some(Some(path.to_string()));
+            }
+            return Some(None);
+        }
+    }
+    None
+}
+
+fn unquote_path(path: &str) -> &str {
+    let trimmed = path.trim();
+    if trimmed.len() >= 2 {
+        let bytes = trimmed.as_bytes();
+        if (bytes[0] == b'"' && bytes[trimmed.len() - 1] == b'"')
+            || (bytes[0] == b'\'' && bytes[trimmed.len() - 1] == b'\'')
+        {
+            return &trimmed[1..trimmed.len() - 1];
+        }
+    }
+    trimmed
+}
+
+fn attach_image(path: Option<&str>) -> Result<ImageAttachment> {
+    match path {
+        Some(path) => load_image_file(Path::new(path)),
+        None => read_clipboard_image().context(
+            "no supported image found in clipboard; copy an image first or use /attach path/to/image.png",
+        ),
+    }
+}
+
+fn load_image_file(path: &Path) -> Result<ImageAttachment> {
+    const MAX_IMAGE_BYTES: u64 = 20 * 1024 * 1024;
+
+    let metadata =
+        fs::metadata(path).with_context(|| format!("failed to read {}", path.display()))?;
+    if !metadata.is_file() {
+        bail!("{} is not a file", path.display());
+    }
+    if metadata.len() > MAX_IMAGE_BYTES {
+        bail!(
+            "{} is too large for an image attachment ({} MB max)",
+            path.display(),
+            MAX_IMAGE_BYTES / 1024 / 1024
+        );
+    }
+
+    let mime = image_mime_for_path(path)
+        .with_context(|| format!("unsupported image type for {}", path.display()))?;
+    let bytes = fs::read(path).with_context(|| format!("failed to read {}", path.display()))?;
+    if bytes.is_empty() {
+        bail!("{} is empty", path.display());
+    }
+
+    Ok(ImageAttachment {
+        mime: mime.to_string(),
+        data: BASE64.encode(&bytes),
+    })
+}
+
+fn image_mime_for_path(path: &Path) -> Option<&'static str> {
+    match path
+        .extension()
+        .and_then(|ext| ext.to_str())
+        .map(|ext| ext.to_ascii_lowercase())
+        .as_deref()
+    {
+        Some("png") => Some("image/png"),
+        Some("jpg") | Some("jpeg") => Some("image/jpeg"),
+        Some("webp") => Some("image/webp"),
+        Some("gif") => Some("image/gif"),
+        _ => None,
+    }
+}
+
 /// Try to grab an image from the system clipboard and return it base64-encoded.
 /// Only supported on macOS; returns None on other platforms or when no image is present.
 #[cfg(target_os = "macos")]
 fn grab_clipboard_image() -> Option<ImageAttachment> {
-    let tmp = format!("/tmp/anveesa_clip_{}.png", std::process::id());
+    read_clipboard_image().ok()
+}
 
-    // AppleScript: cast clipboard to PNG and write to a temp file.
+/// Try to grab an image from the system clipboard and return it base64-encoded.
+#[cfg(target_os = "macos")]
+fn read_clipboard_image() -> Result<ImageAttachment> {
+    if let Ok(bytes) = read_clipboard_class_bytes("PNGf", "png") {
+        return Ok(ImageAttachment {
+            mime: "image/png".to_string(),
+            data: BASE64.encode(&bytes),
+        });
+    }
+
+    if let Ok(bytes) = read_clipboard_class_bytes("JPEG", "jpg") {
+        return Ok(ImageAttachment {
+            mime: "image/jpeg".to_string(),
+            data: BASE64.encode(&bytes),
+        });
+    }
+
+    if let Ok(tiff) = read_clipboard_class_bytes("TIFF", "tiff") {
+        let png = convert_tiff_to_png(&tiff)?;
+        return Ok(ImageAttachment {
+            mime: "image/png".to_string(),
+            data: BASE64.encode(&png),
+        });
+    }
+
+    bail!("clipboard does not contain PNG, JPEG, or TIFF image data")
+}
+
+#[cfg(target_os = "macos")]
+fn read_clipboard_class_bytes(class_code: &str, extension: &str) -> Result<Vec<u8>> {
+    let tmp = std::env::temp_dir().join(format!(
+        "anveesa_clip_{}_{}.{}",
+        std::process::id(),
+        class_code,
+        extension
+    ));
+    let tmp_display = tmp.display();
     let script = format!(
         "try\n\
-         set d to (the clipboard as \u{00AB}class PNGf\u{00BB})\n\
-         set f to open for access POSIX file \"{tmp}\" with write permission\n\
+         set d to (the clipboard as \u{00AB}class {class_code}\u{00BB})\n\
+         set f to open for access POSIX file \"{tmp_display}\" with write permission\n\
          write d to f\n\
          close access f\n\
          return \"ok\"\n\
@@ -1260,23 +1439,52 @@ fn grab_clipboard_image() -> Option<ImageAttachment> {
         .arg("-e")
         .arg(&script)
         .output()
-        .ok()?;
+        .context("failed to read macOS clipboard with osascript")?;
 
     if String::from_utf8_lossy(&out.stdout).trim() != "ok" {
-        return None;
+        let _ = fs::remove_file(&tmp);
+        bail!("clipboard does not contain {class_code} image data");
     }
 
-    let bytes = std::fs::read(&tmp).ok()?;
-    let _ = std::fs::remove_file(&tmp);
+    let bytes = fs::read(&tmp).with_context(|| format!("failed to read {tmp_display}"))?;
+    let _ = fs::remove_file(&tmp);
 
     if bytes.len() < 8 {
-        return None;
+        bail!("clipboard {class_code} image data is empty");
     }
 
-    Some(ImageAttachment {
-        mime: "image/png".to_string(),
-        data: BASE64.encode(&bytes),
-    })
+    Ok(bytes)
+}
+
+#[cfg(target_os = "macos")]
+fn convert_tiff_to_png(tiff: &[u8]) -> Result<Vec<u8>> {
+    let base = std::env::temp_dir().join(format!("anveesa_clip_{}", std::process::id()));
+    let tiff_path = base.with_extension("tiff");
+    let png_path = base.with_extension("png");
+    fs::write(&tiff_path, tiff).context("failed to write temporary TIFF clipboard image")?;
+
+    let status = std::process::Command::new("sips")
+        .arg("-s")
+        .arg("format")
+        .arg("png")
+        .arg(&tiff_path)
+        .arg("--out")
+        .arg(&png_path)
+        .status()
+        .context("failed to convert clipboard TIFF to PNG with sips")?;
+
+    let _ = fs::remove_file(&tiff_path);
+    if !status.success() {
+        let _ = fs::remove_file(&png_path);
+        bail!("failed to convert clipboard TIFF image to PNG");
+    }
+
+    let bytes = fs::read(&png_path).context("failed to read converted clipboard PNG")?;
+    let _ = fs::remove_file(&png_path);
+    if bytes.len() < 8 {
+        bail!("converted clipboard PNG is empty");
+    }
+    Ok(bytes)
 }
 
 #[cfg(not(target_os = "macos"))]
@@ -1284,6 +1492,11 @@ fn grab_clipboard_image() -> Option<ImageAttachment> {
     None
 }
 
+#[cfg(not(target_os = "macos"))]
+fn read_clipboard_image() -> Result<ImageAttachment> {
+    bail!("clipboard image attachment is only supported on macOS; use /attach path/to/image.png")
+}
+
 fn repl_history_path() -> Option<PathBuf> {
     let path = config_path().ok()?;
     let dir = path.parent()?;
@@ -1496,6 +1709,32 @@ mod tests {
         );
     }
 
+    #[test]
+    fn parses_attach_commands() {
+        assert_eq!(parse_attach_command("/attach"), Some(None));
+        assert_eq!(
+            parse_attach_command("/attach screenshot.png"),
+            Some(Some("screenshot.png".into()))
+        );
+        assert_eq!(
+            parse_attach_command("/attach \"folder/my image.jpg\""),
+            Some(Some("folder/my image.jpg".into()))
+        );
+        assert_eq!(
+            parse_attach_command("/img '/tmp/capture.webp'"),
+            Some(Some("/tmp/capture.webp".into()))
+        );
+        assert_eq!(parse_attach_command("/attachment nope"), None);
+    }
+
+    #[test]
+    fn detects_image_mime_from_path() {
+        assert_eq!(image_mime_for_path(Path::new("a.png")), Some("image/png"));
+        assert_eq!(image_mime_for_path(Path::new("a.JPEG")), Some("image/jpeg"));
+        assert_eq!(image_mime_for_path(Path::new("a.webp")), Some("image/webp"));
+        assert_eq!(image_mime_for_path(Path::new("a.txt")), None);
+    }
+
     #[test]
     fn interactive_session_matches_same_scope_only() {
         let options = AskOptions {

package/src/provider/mod.rs

@@ -116,6 +116,8 @@ pub enum StreamEvent {
     Token(String),
     /// Final token accounting for the turn.
     Usage(Usage),
+    /// A read-only tool is running. Used to make multi-round inspection visible.
+    ToolCall { summary: String },
     /// A write/run tool needs the user's approval. The renderer shows the
     /// preview, prompts for a decision, and sends it back through the reply channel.
     Confirm {

package/src/provider/openai_compatible.rs

@@ -21,6 +21,7 @@ const MAX_RETRIES: usize = 2;
 const CONNECT_TIMEOUT: Duration = Duration::from_secs(15);
 /// How many times the model may call the exact same (tool, arguments) pair before we refuse.
 const MAX_IDENTICAL_CALLS: usize = 3;
+const MAX_TOOL_INTENT_REPROMPTS: usize = 2;
 
 pub async fn ask(
     provider_name: &str,
@@ -58,6 +59,7 @@ pub async fn ask(
     let mut approval_state = ToolApprovalState::default();
     let mut full_text = String::new();
     let mut last_usage: Option<Usage> = None;
+    let mut tool_intent_reprompts = 0usize;
 
     loop {
         let mut body = json!({
@@ -94,12 +96,25 @@ pub async fn ask(
         let mut state = StreamState::default();
         stream_response(response, &mut state, events).await?;
 
-        full_text.push_str(&state.content);
         if let Some(usage) = state.usage {
             last_usage = Some(usage);
         }
 
         if state.tool_calls.is_empty() {
+            if tools_enabled
+                && tool_intent_reprompts < MAX_TOOL_INTENT_REPROMPTS
+                && looks_like_unfinished_tool_intent(&state.content)
+            {
+                tool_intent_reprompts += 1;
+                messages.push(json!({
+                    "role": "assistant",
+                    "content": state.content,
+                }));
+                messages.push(tool_intent_reprompt_message());
+                continue;
+            }
+
+            full_text.push_str(&state.content);
             break;
         }
 
@@ -196,6 +211,10 @@ async fn dispatch_tool(
         if !policy.allows_write_tools() {
             return denied_message("write tools are disabled (pass --yes or run interactively)");
         }
+    } else {
+        let _ = events.send(StreamEvent::ToolCall {
+            summary: tools::describe_call(&call.name, &call.arguments),
+        });
     }
 
     // Snapshot BEFORE the tool runs — needed both for preview and for post-run diff.
@@ -397,6 +416,50 @@ fn tool_limit_message(max_tool_rounds: usize) -> Value {
     })
 }
 
+fn tool_intent_reprompt_message() -> Value {
+    json!({
+        "role": "system",
+        "content": "Your previous message said you would inspect/read/check the workspace, but it did not call any tool or provide a final answer. Do not narrate future tool use. If you need information, call the relevant Anveesa tools now. Otherwise, answer the user directly."
+    })
+}
+
+fn looks_like_unfinished_tool_intent(text: &str) -> bool {
+    let lower = text.trim().to_lowercase();
+    if lower.is_empty() || lower.len() > 600 {
+        return false;
+    }
+
+    let has_intent = [
+        "let me inspect",
+        "let me check",
+        "let me look",
+        "let me read",
+        "let me search",
+        "let me peek",
+        "let me also peek",
+        "i'll inspect",
+        "i'll check",
+        "i'll look",
+        "i'll read",
+        "i'll search",
+        "i will inspect",
+        "i will check",
+        "i will look",
+        "i will read",
+        "i will search",
+        "i'm going to inspect",
+        "i'm going to check",
+        "i'm going to look",
+        "i'm going to read",
+        "i need to inspect",
+        "i need to check",
+    ]
+    .iter()
+    .any(|needle| lower.contains(needle));
+
+    has_intent && (lower.ends_with(':') || lower.ends_with('.') || lower.ends_with("first"))
+}
+
 fn denied_message(reason: &str) -> String {
     json!({ "ok": false, "error": reason }).to_string()
 }
@@ -685,15 +748,14 @@ async fn stream_response(
                 // Stream ended normally
                 break;
             }
-            Err(_e) => {
+            Err(error) => {
                 consecutive_errors += 1;
                 if consecutive_errors >= MAX_CONSECUTIVE_ERRORS {
-                    // Log the error but don't fail the whole request
-                    eprintln!(
-                        "\n[warning: stream interrupted after {} consecutive errors]",
-                        consecutive_errors
+                    bail!(
+                        "stream interrupted while reading provider response after {} consecutive errors: {}",
+                        consecutive_errors,
+                        error
                     );
-                    break;
                 }
                 // Try to continue reading - transient network hiccups happen
                 continue;
@@ -972,4 +1034,18 @@ mod tests {
                 .contains("Do not call tools again")
         );
     }
+
+    #[test]
+    fn detects_unfinished_tool_intent() {
+        assert!(looks_like_unfinished_tool_intent(
+            "Let me inspect the workspace structure more thoroughly."
+        ));
+        assert!(looks_like_unfinished_tool_intent(
+            "Let me also peek at the key files to understand the project:"
+        ));
+        assert!(!looks_like_unfinished_tool_intent(
+            "The project is a Rust CLI with an npm wrapper."
+        ));
+        assert!(!looks_like_unfinished_tool_intent(""));
+    }
 }

package/src/tools.rs

@@ -24,7 +24,9 @@ const MAX_COMMAND_TIMEOUT_SECS: u64 = 300;
 pub fn guidance(include_write: bool) -> String {
     let mut text = String::from(
         "You can use Anveesa tools to inspect the workspace: list directories, find files by name, \
-search text, read capped file snippets, and do a basic public web lookup. Prefer tools over guessing.",
+search text, read capped file snippets, and do a basic public web lookup. Prefer tools over guessing. \
+If you need to inspect, read, list, search, or check something, call the relevant tool immediately; \
+do not end a response by saying you will inspect something later.",
     );
     if include_write {
         text.push_str(
@@ -58,6 +60,19 @@ pub fn describe_call(name: &str, arguments: &str) -> String {
     let args: Value = serde_json::from_str(arguments).unwrap_or(Value::Null);
     let field = |key: &str| args.get(key).and_then(Value::as_str).unwrap_or("");
     match name {
+        "list_dir" => format!("list directory {}", field("path").if_empty(".")),
+        "find_files" => format!(
+            "find files matching `{}` under {}",
+            field("query"),
+            field("root").if_empty(".")
+        ),
+        "search_text" => format!(
+            "search text `{}` under {}",
+            field("query"),
+            field("root").if_empty(".")
+        ),
+        "read_file" => format!("read file {}", field("path")),
+        "web_search" => format!("web search `{}`", field("query")),
         "create_dir" => format!("create directory {}", field("path")),
         "write_file" => format!("write file {}", field("path")),
         "edit_file" => format!("edit file {}", field("path")),
@@ -66,6 +81,16 @@ pub fn describe_call(name: &str, arguments: &str) -> String {
     }
 }
 
+trait EmptyStrExt {
+    fn if_empty(self, fallback: &'static str) -> Self;
+}
+
+impl<'a> EmptyStrExt for &'a str {
+    fn if_empty(self, fallback: &'static str) -> Self {
+        if self.is_empty() { fallback } else { self }
+    }
+}
+
 pub fn definitions(include_write: bool) -> Vec<Value> {
     let mut definitions = vec![
         json!({
@@ -846,6 +871,23 @@ mod tests {
 
     #[test]
     fn describes_calls_for_confirmation() {
+        assert_eq!(describe_call("list_dir", r#"{}"#), "list directory .");
+        assert_eq!(
+            describe_call("find_files", r#"{"query":"Cargo","root":"src"}"#),
+            "find files matching `Cargo` under src"
+        );
+        assert_eq!(
+            describe_call("search_text", r#"{"query":"TODO"}"#),
+            "search text `TODO` under ."
+        );
+        assert_eq!(
+            describe_call("read_file", r#"{"path":"README.md"}"#),
+            "read file README.md"
+        );
+        assert_eq!(
+            describe_call("web_search", r#"{"query":"rust termios"}"#),
+            "web search `rust termios`"
+        );
         assert_eq!(
             describe_call("create_dir", r#"{"path":"hello"}"#),
             "create directory hello"
@@ -863,6 +905,7 @@ mod tests {
     #[test]
     fn guidance_mentions_writes_only_when_enabled() {
         assert!(!guidance(false).contains("write_file"));
+        assert!(guidance(false).contains("call the relevant tool immediately"));
         assert!(guidance(true).contains("create_dir"));
         assert!(guidance(true).contains("write_file"));
     }