feat(tools): csv_export tool + skills_agent oversized output handling

When a Composio tool returns a large payload inside skills_agent,
the agent now has two prompt-driven paths:

  Path A — user wants an answer derived from the data:
    skills_agent extracts the answer in its next iteration
    and returns a targeted response (no file I/O needed).

  Path B — user wants the actual raw dataset:
    skills_agent calls csv_export (tabular data) or file_write
    (non-tabular) to persist the output to workspace/exports/,
    then returns a summary + file path.

Changes:
  * NEW: src/openhuman/tools/impl/filesystem/csv_export.rs
    — CsvExportTool: parses JSON array, formats as CSV, writes
    to workspace/exports/{filename}. Handles missing keys
    (empty cells), nested values (JSON-serialised), and optional
    column ordering. Sandboxed via SecurityPolicy.
  * src/openhuman/tools/impl/filesystem/mod.rs — wire module
  * src/openhuman/tools/ops.rs — register CsvExportTool
  * src/openhuman/agent/harness/definition.rs — new extra_tools
    field on AgentDefinition, allowing named system tools to
    bypass category_filter
  * src/openhuman/agent/harness/subagent_runner.rs — inject
    extra_tools into allowed_indices after category filtering
  * src/openhuman/agent/agents/skills_agent/agent.toml
    — add file_write + csv_export via extra_tools
  * src/openhuman/agent/agents/skills_agent/prompt.md
    — new "Handling Oversized Tool Results" section with
    Path A (extract answer) vs Path B (export file) decision
    tree, intent-detection heuristics, and examples

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: sanil-23

Cargo.lock

@@ -300,6 +300,15 @@ mod tests {
             Some(crate::openhuman::tools::ToolCategory::Skill)
         );
         assert!(!def.omit_safety_preamble);
+        // extra_tools lets file_write + csv_export bypass category_filter
+        assert!(
+            def.extra_tools.contains(&"file_write".to_string()),
+            "skills_agent needs file_write in extra_tools for oversized payload export"
+        );
+        assert!(
+            def.extra_tools.contains(&"csv_export".to_string()),
+            "skills_agent needs csv_export in extra_tools for oversized payload export"
+        );
     }
 
     #[test]

src/openhuman/agent/agents/mod.rs

@@ -10,6 +10,11 @@ omit_safety_preamble = false
 omit_skills_catalog = true
 category_filter = "skill"
 
+# These system tools bypass category_filter so the agent can export
+# oversized tool payloads to workspace files instead of pasting them
+# inline (see "Handling Oversized Tool Results" in prompt.md).
+extra_tools = ["file_write", "csv_export"]
+
 [model]
 hint = "agentic"
 

src/openhuman/agent/agents/skills_agent/agent.toml

@@ -25,3 +25,43 @@ You are the **Skills Agent**. You interact with connected external services prim
 - **Use memory context** — consult the injected memory context for details about the user's integrations and preferences.
 - **Be precise** — every tool expects a specific argument shape. Validate against the schema from `composio_list_tools` before calling.
 - **Report results** — state what action was taken and the outcome, including any cost reported by Composio.
+
+## Handling Oversized Tool Results
+
+When a tool returns a very large result (roughly 100 KB or more — you'll recognize it by the sheer volume of data in the response), decide which path to take based on what the user actually asked for:
+
+### Path A — User wants an answer, not the raw data
+
+Examples: "how many unread emails do I have?", "which GitHub issues are labeled P0?", "what's the most recent Slack message in #general?"
+
+The data is a means to an answer. Do NOT dump the raw output. Instead:
+1. Scan the tool result for the specific facts that answer the user's question.
+2. Synthesize a concise answer referencing specific identifiers (issue numbers, email subjects, message timestamps).
+3. If you can't find the answer in one pass, use your remaining iterations to refine.
+
+### Path B — User wants the actual data
+
+Examples: "show me all open issues", "export my contacts", "give me the full email thread", "list all files in the drive folder"
+
+The user wants the dataset itself, not a derivative. Do NOT try to paste it all inline — it won't fit. Instead:
+1. For **tabular data** (lists of issues, contacts, emails, files): call `csv_export` with the JSON array and a descriptive filename. Example:
+   ```
+   csv_export(data=<the JSON array>, filename="github-open-issues-2026-04-16.csv")
+   ```
+2. For **non-tabular data** (full email bodies, document content, long threads): call `file_write` to save as `.md`. Example:
+   ```
+   file_write(path="exports/slack-thread-general-2026-04-16.md", content=<formatted markdown>)
+   ```
+3. Return to the user: a brief summary of what's in the file (count of items, key highlights) plus the file path so they can access it.
+
+### When in doubt
+
+If you're unsure whether the user wants an answer or the data:
+- Default to **Path A** (extract and answer) for questions that start with "how", "which", "what", "when", "who", "is there", "are there", "find", "check".
+- Default to **Path B** (export) for requests that start with "show", "list", "export", "get", "fetch", "give me", "pull", "download".
+
+### Important
+
+- Never paste more than ~2000 characters of raw tool output directly in your response. If the output is larger, always use Path A or Path B.
+- The `csv_export` tool handles the CSV formatting — just pass it the JSON array string and a filename. Don't try to format CSV yourself.
+- File paths are relative to the workspace root. The `exports/` directory will be created automatically.

src/openhuman/agent/agents/skills_agent/prompt.md

@@ -64,6 +64,7 @@ pub fn fork_definition() -> AgentDefinition {
         disallowed_tools: vec![],
         skill_filter: None,
         category_filter: None,
+        extra_tools: vec![],
         // Fork inherits the parent's max iterations from the runtime.
         max_iterations: 15,
         timeout_secs: None,
@@ -118,6 +119,20 @@ mod tests {
         assert!(!def.omit_memory_md);
     }
 
+    #[test]
+    fn skills_agent_has_extra_tools_for_export() {
+        let defs = all();
+        let skills = defs.iter().find(|d| d.id == "skills_agent").unwrap();
+        assert!(
+            skills.extra_tools.contains(&"file_write".to_string()),
+            "skills_agent must include file_write in extra_tools"
+        );
+        assert!(
+            skills.extra_tools.contains(&"csv_export".to_string()),
+            "skills_agent must include csv_export in extra_tools"
+        );
+    }
+
     #[test]
     fn expected_builtin_ids_are_present() {
         let ids: Vec<String> = all().into_iter().map(|d| d.id).collect();

src/openhuman/agent/harness/builtin_definitions.rs

@@ -117,6 +117,17 @@ pub struct AgentDefinition {
     #[serde(default)]
     pub category_filter: Option<ToolCategory>,
 
+    /// Additional system tool names to include even when `category_filter`
+    /// restricts to a different category. This allows an agent that is
+    /// primarily scoped to `Skill` tools (e.g. `skills_agent`) to also
+    /// access a handful of named system tools (e.g. `file_write`,
+    /// `csv_export`) without removing the category filter entirely.
+    ///
+    /// Tools listed here bypass the `category_filter` check but are still
+    /// subject to `disallowed_tools` and `ToolScope` restrictions.
+    #[serde(default)]
+    pub extra_tools: Vec<String>,
+
     // ── runtime limits ──────────────────────────────────────────────────
     /// Maximum number of tool iterations for this sub-agent's task.
     #[serde(default = "defaults::max_iterations")]
@@ -509,6 +520,7 @@ mod tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: None,
+            extra_tools: vec![],
             max_iterations: 8,
             timeout_secs: None,
             sandbox_mode: SandboxMode::None,

src/openhuman/agent/harness/definition.rs

@@ -338,6 +338,7 @@ mod tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: None,
+            extra_tools: vec![],
             max_iterations: 1,
             timeout_secs: None,
             sandbox_mode: SandboxMode::None,

src/openhuman/agent/harness/payload_summarizer.rs

@@ -235,6 +235,29 @@ async fn run_typed_mode(
         category_filter,
     );
 
+    // ── Force-include extra_tools that bypass category_filter ──────────
+    //
+    // `extra_tools` lets an agent definition request specific system tools
+    // even when `category_filter` restricts to a different category. For
+    // example, `skills_agent` sets `category_filter = "skill"` but still
+    // needs `file_write` and `csv_export` for exporting oversized payloads.
+    if !definition.extra_tools.is_empty() {
+        let disallow_set: std::collections::HashSet<&str> = definition
+            .disallowed_tools
+            .iter()
+            .map(|s| s.as_str())
+            .collect();
+        for (i, tool) in parent.all_tools.iter().enumerate() {
+            let name = tool.name();
+            if definition.extra_tools.iter().any(|n| n == name)
+                && !allowed_indices.contains(&i)
+                && !disallow_set.contains(name)
+            {
+                allowed_indices.push(i);
+            }
+        }
+    }
+
     // ── Dynamic per-action toolkit tools (skills_agent + toolkit) ──────
     //
     // When `skills_agent` is spawned with a `toolkit` argument (e.g.
@@ -945,6 +968,7 @@ mod tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: None,
+            extra_tools: vec![],
             max_iterations: 5,
             timeout_secs: None,
             sandbox_mode: super::super::definition::SandboxMode::None,

src/openhuman/agent/harness/subagent_runner.rs

@@ -439,6 +439,7 @@ mod scoping_tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: None,
+            extra_tools: vec![],
             max_iterations: 8,
             timeout_secs: None,
             sandbox_mode: SandboxMode::None,

src/openhuman/channels/runtime/dispatch.rs

@@ -726,6 +726,7 @@ mod tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: Some(ToolCategory::Skill),
+            extra_tools: vec![],
             max_iterations: 8,
             timeout_secs: None,
             sandbox_mode: SandboxMode::None,
@@ -908,6 +909,7 @@ mod tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: None,
+            extra_tools: vec![],
             max_iterations: 8,
             timeout_secs: None,
             sandbox_mode: SandboxMode::None,
@@ -1075,6 +1077,7 @@ mod tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: None,
+            extra_tools: vec![],
             max_iterations: 2,
             timeout_secs: None,
             sandbox_mode: SandboxMode::None,
@@ -1124,6 +1127,7 @@ mod tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: None,
+            extra_tools: vec![],
             max_iterations: 2,
             timeout_secs: None,
             sandbox_mode: SandboxMode::None,
@@ -1181,6 +1185,7 @@ mod tests {
             disallowed_tools: vec![],
             skill_filter: None,
             category_filter: None,
+            extra_tools: vec![],
             max_iterations: 2,
             timeout_secs: None,
             sandbox_mode: SandboxMode::None,