Fix batch tool resolution loops and update docs parity

Author: tacshade

crates/tandem-core/src/engine_loop.rs

@@ -506,7 +506,12 @@ impl EngineLoop {
                                 continue;
                             }
                         }
-                        let signature = tool_signature(&tool_key, &args);
+                        let signature = if tool_key == "batch" {
+                            batch_tool_signature(&args)
+                                .unwrap_or_else(|| tool_signature(&tool_key, &args))
+                        } else {
+                            tool_signature(&tool_key, &args)
+                        };
                         if is_shell_tool_name(&tool_key)
                             && shell_mismatch_signatures.contains(&signature)
                         {
@@ -517,7 +522,9 @@ impl EngineLoop {
                             continue;
                         }
                         let mut signature_count = 1usize;
-                        if is_read_only_tool(&tool_key) {
+                        if is_read_only_tool(&tool_key)
+                            || (tool_key == "batch" && is_read_only_batch_call(&args))
+                        {
                             let count = readonly_signature_counts
                                 .entry(signature.clone())
                                 .and_modify(|v| *v = v.saturating_add(1))
@@ -1358,11 +1365,69 @@ fn is_read_only_tool(tool_name: &str) -> bool {
     )
 }
 
+fn is_batch_wrapper_tool_name(name: &str) -> bool {
+    matches!(
+        normalize_tool_name(name).as_str(),
+        "default_api" | "default" | "api" | "function" | "functions" | "tool" | "tools"
+    )
+}
+
+fn extract_batch_calls(args: &Value) -> Vec<(String, Value)> {
+    let calls = args
+        .get("tool_calls")
+        .and_then(|v| v.as_array())
+        .cloned()
+        .unwrap_or_default();
+    calls
+        .into_iter()
+        .filter_map(|call| {
+            let obj = call.as_object()?;
+            let tool_raw = obj
+                .get("tool")
+                .and_then(|v| v.as_str())
+                .map(str::trim)
+                .filter(|s| !s.is_empty());
+            let name_raw = obj
+                .get("name")
+                .and_then(|v| v.as_str())
+                .map(str::trim)
+                .filter(|s| !s.is_empty());
+            let effective = match (tool_raw, name_raw) {
+                (Some(t), Some(n)) if is_batch_wrapper_tool_name(t) => n,
+                (Some(t), _) => t,
+                (None, Some(n)) => n,
+                (None, None) => return None,
+            };
+            let normalized = normalize_tool_name(effective);
+            let call_args = obj.get("args").cloned().unwrap_or_else(|| json!({}));
+            Some((normalized, call_args))
+        })
+        .collect()
+}
+
+fn is_read_only_batch_call(args: &Value) -> bool {
+    let calls = extract_batch_calls(args);
+    !calls.is_empty() && calls.iter().all(|(tool, _)| is_read_only_tool(tool))
+}
+
+fn batch_tool_signature(args: &Value) -> Option<String> {
+    let calls = extract_batch_calls(args);
+    if calls.is_empty() {
+        return None;
+    }
+    let parts = calls
+        .into_iter()
+        .map(|(tool, call_args)| tool_signature(&tool, &call_args))
+        .collect::<Vec<_>>();
+    Some(format!("batch:{}", parts.join("|")))
+}
+
 fn tool_budget_for(tool_name: &str) -> usize {
     match normalize_tool_name(tool_name).as_str() {
         "glob" => 4,
         "read" => 8,
         "websearch" => 3,
+        "batch" => 4,
         "grep" | "search" | "codesearch" => 6,
         _ => 10,
     }
@@ -3589,6 +3654,24 @@ Call: todowrite(task_id=3, status="in_progress")
         assert_eq!(normalize_tool_name("functions.shell"), "bash");
     }
 
+    #[test]
+    fn batch_helpers_use_name_when_tool_is_wrapper() {
+        let args = json!({
+            "tool_calls":[
+                {"tool":"default_api","name":"read","args":{"path":"CONCEPT.md"}},
+                {"tool":"default_api:glob","args":{"pattern":"*.md"}}
+            ]
+        });
+        let calls = extract_batch_calls(&args);
+        assert_eq!(calls.len(), 2);
+        assert_eq!(calls[0].0, "read");
+        assert_eq!(calls[1].0, "glob");
+        assert!(is_read_only_batch_call(&args));
+        let sig = batch_tool_signature(&args).unwrap_or_default();
+        assert!(sig.contains("read:"));
+        assert!(sig.contains("glob:"));
+    }
+
     #[test]
     fn runtime_prompt_includes_execution_environment_block() {
         let prompt = tandem_runtime_system_prompt(&HostRuntimeContext {

crates/tandem-tools/src/lib.rs

@@ -165,6 +165,39 @@ fn resolve_registered_tool(
     None
 }
 
+fn is_batch_wrapper_tool_name(name: &str) -> bool {
+    matches!(
+        canonical_tool_name(name).as_str(),
+        "default_api" | "default" | "api" | "function" | "functions" | "tool" | "tools"
+    )
+}
+
+fn resolve_batch_call_tool_name(call: &Value) -> Option<String> {
+    let tool = call
+        .get("tool")
+        .and_then(|v| v.as_str())
+        .map(str::trim)
+        .filter(|s| !s.is_empty());
+    let name = call
+        .get("name")
+        .and_then(|v| v.as_str())
+        .map(str::trim)
+        .filter(|s| !s.is_empty());
+
+    match (tool, name) {
+        (Some(t), Some(n)) => {
+            if is_batch_wrapper_tool_name(t) {
+                Some(n.to_string())
+            } else {
+                Some(t.to_string())
+            }
+        }
+        (Some(t), None) => Some(t.to_string()),
+        (None, Some(n)) => Some(n.to_string()),
+        (None, None) => None,
+    }
+}
+
 impl Default for ToolRegistry {
     fn default() -> Self {
         Self::new()
@@ -2420,16 +2453,24 @@ impl Tool for BatchTool {
         let registry = ToolRegistry::new();
         let mut outputs = Vec::new();
         for call in calls.iter().take(20) {
-            let tool = call
-                .get("tool")
-                .or_else(|| call.get("name"))
-                .and_then(|v| v.as_str())
-                .unwrap_or("");
+            let Some(tool) = resolve_batch_call_tool_name(call) else {
+                continue;
+            };
             if tool.is_empty() || tool == "batch" {
                 continue;
             }
             let call_args = call.get("args").cloned().unwrap_or_else(|| json!({}));
-            let result = registry.execute(tool, call_args).await?;
+            let mut result = registry.execute(&tool, call_args.clone()).await?;
+            if result.output.starts_with("Unknown tool:") {
+                if let Some(fallback_name) = call
+                    .get("name")
+                    .and_then(|v| v.as_str())
+                    .map(str::trim)
+                    .filter(|s| !s.is_empty() && *s != tool)
+                {
+                    result = registry.execute(fallback_name, call_args).await?;
+                }
+            }
             outputs.push(json!({
                 "tool": tool,
                 "output": result.output,
@@ -2834,6 +2875,20 @@ mod tests {
             .expect("batch should return ToolResult");
         assert!(!result.output.contains("Unknown tool: default_api:read"));
     }
+
+    #[tokio::test]
+    async fn batch_prefers_name_when_tool_is_default_api_wrapper() {
+        let tool = BatchTool;
+        let result = tool
+            .execute(json!({
+                "tool_calls":[
+                    {"tool":"default_api","name":"read","args":{"path":"Cargo.toml"}}
+                ]
+            }))
+            .await
+            .expect("batch should return ToolResult");
+        assert!(!result.output.contains("Unknown tool: default_api"));
+    }
 }
 
 async fn find_symbol_references(symbol: &str) -> String {

guide/src/content/docs/reference/engine-commands.md

@@ -45,6 +45,19 @@ tandem-engine serve [OPTIONS]
 - `--web-ui`: Enable embedded web admin UI (env: `TANDEM_WEB_UI`).
 - `--web-ui-prefix <PATH>`: Path prefix for embedded web admin UI (default: `/admin`, env: `TANDEM_WEB_UI_PREFIX`).
 
+## `status`
+
+Checks engine health by calling `GET /global/health` on a target host/port.
+
+```bash
+tandem-engine status [OPTIONS]
+```
+
+**Options:**
+
+- `--hostname <HOSTNAME>` / `--host <HOSTNAME>`: Hostname or IP to check (default: `127.0.0.1`, env: `TANDEM_ENGINE_HOST`).
+- `--port <PORT>`: Port to check (default: `39731`, env: `TANDEM_ENGINE_PORT`).
+
 ## `run`
 
 Execute a single prompt and exit. Useful for quick CLI queries or scripting.

guide/src/content/docs/reference/tools.md

@@ -22,8 +22,12 @@ The Tandem Engine tool registry currently exposes the following tools.
 - **`websearch`**: Search the web (powered by Exa.ai).
   - Input: `query` (string), `limit` (integer)
 - **`codesearch`**: Semantic code search (if configured).
+- **`memory_list`**: List persisted memory entries for a scope/tier.
+  - Input: optional scope + filter arguments (e.g., `session_id`, `project_id`, `tier`, `limit`)
 - **`memory_search`**: Search persisted memory by query and scope.
   - Input: `query` plus one or more scopes (e.g., session/workspace).
+- **`memory_store`**: Persist memory content for session/project/global retrieval.
+  - Input: `content` plus scope/tier arguments (e.g., `session_id`, `project_id`, `tier`)
 
 ## Web
 
@@ -41,6 +45,8 @@ The Tandem Engine tool registry currently exposes the following tools.
   - Aliases: `todowrite`, `update_todo_list`
 - **`task`**: Update the current task status.
 - **`question`**: Ask a structured question to the user and wait for input.
+- **`spawn_agent`**: Spawn an agent-team worker instance (runtime/policy gated).
+  - Input: mission/spawn payload (e.g., `missionID`, `role`, `templateID`, `source`)
 
 ## Specialized