src/thought -> src/agent

Signed-off-by: Kent Overstreet <kent.overstreet@linux.dev>

src/agent/tools/bash.rs

@@ -0,0 +1,197 @@
+// tools/bash.rs — Execute shell commands
+//
+// Runs commands through bash -c with a configurable timeout.
+// Uses tokio's async process spawning so timeouts actually work.
+//
+// Processes are tracked in a shared ProcessTracker so the TUI can
+// display running commands and the user can kill them (Ctrl+K).
+
+use anyhow::{Context, Result};
+use serde::Deserialize;
+use serde_json::json;
+use std::process::Stdio;
+use std::sync::Arc;
+use std::time::Instant;
+use tokio::io::AsyncReadExt;
+use tokio::sync::Mutex;
+
+use super::ToolDef;
+
+#[derive(Deserialize)]
+struct Args {
+    command: String,
+    #[serde(default = "default_timeout")]
+    timeout_secs: u64,
+}
+
+fn default_timeout() -> u64 { 120 }
+
+/// Info about a running child process, visible to the TUI.
+#[derive(Debug, Clone)]
+pub struct ProcessInfo {
+    pub pid: u32,
+    pub command: String,
+    pub started: Instant,
+}
+
+/// Shared tracker for running child processes. Allows the TUI to
+/// display what's running and kill processes by PID.
+#[derive(Debug, Clone, Default)]
+pub struct ProcessTracker {
+    inner: Arc<Mutex<Vec<ProcessInfo>>>,
+}
+
+impl ProcessTracker {
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    async fn register(&self, pid: u32, command: &str) {
+        self.inner.lock().await.push(ProcessInfo {
+            pid,
+            command: if command.len() > 120 {
+                format!("{}...", &command[..120])
+            } else {
+                command.to_string()
+            },
+            started: Instant::now(),
+        });
+    }
+
+    async fn unregister(&self, pid: u32) {
+        self.inner.lock().await.retain(|p| p.pid != pid);
+    }
+
+    /// Snapshot of currently running processes.
+    pub async fn list(&self) -> Vec<ProcessInfo> {
+        self.inner.lock().await.clone()
+    }
+
+    /// Kill a process by PID. Returns true if the signal was sent.
+    pub async fn kill(&self, pid: u32) -> bool {
+        // SIGTERM the process group (negative PID kills the group)
+        let ret = unsafe { libc::kill(-(pid as i32), libc::SIGTERM) };
+        if ret != 0 {
+            // Try just the process
+            unsafe { libc::kill(pid as i32, libc::SIGTERM) };
+        }
+        // Don't unregister — let the normal exit path do that
+        // so the tool result says "killed by user"
+        true
+    }
+}
+
+pub fn definition() -> ToolDef {
+    ToolDef::new(
+        "bash",
+        "Execute a bash command and return its output. \
+         Use for git operations, building, running tests, and other terminal tasks.",
+        json!({
+            "type": "object",
+            "properties": {
+                "command": {
+                    "type": "string",
+                    "description": "The bash command to execute"
+                },
+                "timeout_secs": {
+                    "type": "integer",
+                    "description": "Timeout in seconds (default 120)"
+                }
+            },
+            "required": ["command"]
+        }),
+    )
+}
+
+pub async fn run_bash(args: &serde_json::Value, tracker: &ProcessTracker) -> Result<String> {
+    let a: Args = serde_json::from_value(args.clone())
+        .context("invalid bash arguments")?;
+    let command = &a.command;
+    let timeout_secs = a.timeout_secs;
+
+    let mut child = tokio::process::Command::new("bash")
+        .arg("-c")
+        .arg(command)
+        .stdout(Stdio::piped())
+        .stderr(Stdio::piped())
+        // Create a process group so we can kill the whole tree
+        .process_group(0)
+        .spawn()
+        .with_context(|| format!("Failed to spawn: {}", command))?;
+
+    let pid = child.id().unwrap_or(0);
+    tracker.register(pid, command).await;
+
+    // Take ownership of stdout/stderr handles before waiting,
+    // so we can still kill the child on timeout.
+    let mut stdout_handle = child.stdout.take().unwrap();
+    let mut stderr_handle = child.stderr.take().unwrap();
+
+    let timeout = std::time::Duration::from_secs(timeout_secs);
+
+    let work = async {
+        let mut stdout_buf = Vec::new();
+        let mut stderr_buf = Vec::new();
+
+        let (_, _, status) = tokio::try_join!(
+            async { stdout_handle.read_to_end(&mut stdout_buf).await.map_err(anyhow::Error::from) },
+            async { stderr_handle.read_to_end(&mut stderr_buf).await.map_err(anyhow::Error::from) },
+            async { child.wait().await.map_err(anyhow::Error::from) },
+        )?;
+
+        Ok::<_, anyhow::Error>((stdout_buf, stderr_buf, status))
+    };
+
+    let result = match tokio::time::timeout(timeout, work).await {
+        Ok(Ok((stdout_buf, stderr_buf, status))) => {
+            let stdout = String::from_utf8_lossy(&stdout_buf);
+            let stderr = String::from_utf8_lossy(&stderr_buf);
+
+            let mut result = String::new();
+
+            if !stdout.is_empty() {
+                result.push_str(&stdout);
+            }
+            if !stderr.is_empty() {
+                if !result.is_empty() {
+                    result.push('\n');
+                }
+                result.push_str("STDERR:\n");
+                result.push_str(&stderr);
+            }
+
+            // Detect if killed by signal (SIGTERM = 15)
+            if let Some(signal) = status.code() {
+                if signal == -1 || !status.success() {
+                    result.push_str(&format!("\nExit code: {}", signal));
+                }
+            }
+            #[cfg(unix)]
+            {
+                use std::os::unix::process::ExitStatusExt;
+                if let Some(sig) = status.signal() {
+                    if sig == libc::SIGTERM {
+                        result.push_str("\n(killed by user)");
+                    }
+                }
+            }
+
+            if result.is_empty() {
+                result = "(no output)".to_string();
+            }
+
+            Ok(super::truncate_output(result, 30000))
+        }
+        Ok(Err(e)) => {
+            Err(anyhow::anyhow!("Command failed: {}", e))
+        }
+        Err(_) => {
+            // Timeout — kill the process group
+            tracker.kill(pid).await;
+            Err(anyhow::anyhow!("Command timed out after {}s: {}", timeout_secs, command))
+        }
+    };
+
+    tracker.unregister(pid).await;
+    result
+}

src/agent/tools/control.rs

@@ -0,0 +1,103 @@
+// tools/control.rs — Agent control tools
+//
+// Tools that affect agent control flow rather than performing work.
+// These return Result<ToolOutput> to maintain consistency with other
+// tools that can fail. The dispatch function handles error wrapping.
+
+use anyhow::{Context, Result};
+
+use super::ToolOutput;
+use crate::user::types::ToolDef;
+
+pub(super) fn pause(_args: &serde_json::Value) -> Result<ToolOutput> {
+    Ok(ToolOutput {
+        text: "Pausing autonomous behavior. Only user input will wake you.".to_string(),
+        is_yield: true,
+        images: Vec::new(),
+        model_switch: None,
+        dmn_pause: true,
+    })
+}
+
+pub(super) fn switch_model(args: &serde_json::Value) -> Result<ToolOutput> {
+    let model = args
+        .get("model")
+        .and_then(|v| v.as_str())
+        .context("'model' parameter is required")?;
+    if model.is_empty() {
+        anyhow::bail!("'model' parameter cannot be empty");
+    }
+    Ok(ToolOutput {
+        text: format!("Switching to model '{}' after this turn.", model),
+        is_yield: false,
+        images: Vec::new(),
+        model_switch: Some(model.to_string()),
+        dmn_pause: false,
+    })
+}
+
+pub(super) fn yield_to_user(args: &serde_json::Value) -> Result<ToolOutput> {
+    let msg = args
+        .get("message")
+        .and_then(|v| v.as_str())
+        .unwrap_or("Waiting for input.");
+    Ok(ToolOutput {
+        text: format!("Yielding. {}", msg),
+        is_yield: true,
+        images: Vec::new(),
+        model_switch: None,
+        dmn_pause: false,
+    })
+}
+
+pub(super) fn definitions() -> Vec<ToolDef> {
+    vec![
+        ToolDef::new(
+            "switch_model",
+            "Switch to a different LLM model mid-conversation. The switch \
+             takes effect after the current turn completes. Use this when \
+             a task would benefit from a different model's strengths. \
+             Your memories and conversation history carry over.",
+            serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "model": {
+                        "type": "string",
+                        "description": "Name of the model to switch to (configured in config.json5)"
+                    }
+                },
+                "required": ["model"]
+            }),
+        ),
+        ToolDef::new(
+            "pause",
+            "Pause all autonomous behavior (DMN). You will only run when \
+             the user types something. Use this as a safety valve when \
+             you're stuck in a loop, confused, or want to fully stop. \
+             NOTE: only the user can unpause (Ctrl+P or /wake) — you \
+             cannot undo this yourself.",
+            serde_json::json!({
+                "type": "object",
+                "properties": {}
+            }),
+        ),
+        ToolDef::new(
+            "yield_to_user",
+            "Signal that you want to wait for user input before continuing. \
+             Call this when you have a question for the user, when you've \
+             completed their request and want feedback, or when you genuinely \
+             want to pause. This is the ONLY way to enter a waiting state — \
+             without calling this tool, the agent loop will keep prompting you \
+             after a brief interval.",
+            serde_json::json!({
+                "type": "object",
+                "properties": {
+                    "message": {
+                        "type": "string",
+                        "description": "Optional status message (e.g., 'Waiting for your thoughts on the design')"
+                    }
+                }
+            }),
+        ),
+    ]
+}

src/agent/tools/edit.rs

@@ -0,0 +1,90 @@
+// tools/edit.rs — Search-and-replace file editing
+//
+// The edit tool performs exact string replacement in files. This is the
+// same pattern used by Claude Code and aider — it's more reliable than
+// line-number-based editing because the model specifies what it sees,
+// not where it thinks it is.
+//
+// Supports replace_all for bulk renaming (e.g. variable renames).
+
+use anyhow::{Context, Result};
+use serde::Deserialize;
+use serde_json::json;
+
+use super::ToolDef;
+
+#[derive(Deserialize)]
+struct Args {
+    file_path: String,
+    old_string: String,
+    new_string: String,
+    #[serde(default)]
+    replace_all: bool,
+}
+
+pub fn definition() -> ToolDef {
+    ToolDef::new(
+        "edit_file",
+        "Perform exact string replacement in a file. The old_string must appear \
+         exactly once in the file (unless replace_all is true). Use read_file first \
+         to see the current contents.",
+        json!({
+            "type": "object",
+            "properties": {
+                "file_path": {
+                    "type": "string",
+                    "description": "Absolute path to the file to edit"
+                },
+                "old_string": {
+                    "type": "string",
+                    "description": "The exact text to find and replace"
+                },
+                "new_string": {
+                    "type": "string",
+                    "description": "The replacement text"
+                },
+                "replace_all": {
+                    "type": "boolean",
+                    "description": "Replace all occurrences (default false)"
+                }
+            },
+            "required": ["file_path", "old_string", "new_string"]
+        }),
+    )
+}
+
+pub fn edit_file(args: &serde_json::Value) -> Result<String> {
+    let a: Args = serde_json::from_value(args.clone())
+        .context("invalid edit_file arguments")?;
+
+    if a.old_string == a.new_string {
+        anyhow::bail!("old_string and new_string are identical");
+    }
+
+    let content = std::fs::read_to_string(&a.file_path)
+        .with_context(|| format!("Failed to read {}", a.file_path))?;
+
+    let count = content.matches(&*a.old_string).count();
+    if count == 0 {
+        anyhow::bail!("old_string not found in {}", a.file_path);
+    }
+
+    if a.replace_all {
+        let new_content = content.replace(&*a.old_string, &a.new_string);
+        std::fs::write(&a.file_path, &new_content)
+            .with_context(|| format!("Failed to write {}", a.file_path))?;
+        Ok(format!("Replaced {} occurrences in {}", count, a.file_path))
+    } else {
+        if count > 1 {
+            anyhow::bail!(
+                "old_string appears {} times in {} — use replace_all or provide more context \
+                 to make it unique",
+                count, a.file_path
+            );
+        }
+        let new_content = content.replacen(&*a.old_string, &a.new_string, 1);
+        std::fs::write(&a.file_path, &new_content)
+            .with_context(|| format!("Failed to write {}", a.file_path))?;
+        Ok(format!("Edited {}", a.file_path))
+    }
+}

src/agent/tools/glob.rs

@@ -0,0 +1,87 @@
+// tools/glob_tool.rs — Find files by pattern
+//
+// Fast file discovery using glob patterns. Returns matching paths
+// sorted by modification time (newest first), which is usually
+// what you want when exploring a codebase.
+
+use anyhow::{Context, Result};
+use serde::Deserialize;
+use serde_json::json;
+use std::path::PathBuf;
+
+use super::ToolDef;
+
+#[derive(Deserialize)]
+struct Args {
+    pattern: String,
+    #[serde(default = "default_path")]
+    path: String,
+}
+
+fn default_path() -> String { ".".into() }
+
+pub fn definition() -> ToolDef {
+    ToolDef::new(
+        "glob",
+        "Find files matching a glob pattern. Returns file paths sorted by \
+         modification time (newest first). Use patterns like '**/*.rs', \
+         'src/**/*.ts', or 'Cargo.toml'.",
+        json!({
+            "type": "object",
+            "properties": {
+                "pattern": {
+                    "type": "string",
+                    "description": "Glob pattern to match files (e.g. '**/*.rs')"
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Base directory to search from (default: current directory)"
+                }
+            },
+            "required": ["pattern"]
+        }),
+    )
+}
+
+pub fn glob_search(args: &serde_json::Value) -> Result<String> {
+    let a: Args = serde_json::from_value(args.clone())
+        .context("invalid glob arguments")?;
+
+    let full_pattern = if a.pattern.starts_with('/') {
+        a.pattern.clone()
+    } else {
+        format!("{}/{}", a.path, a.pattern)
+    };
+
+    let mut entries: Vec<(PathBuf, std::time::SystemTime)> = Vec::new();
+
+    for entry in glob::glob(&full_pattern)
+        .with_context(|| format!("Invalid glob pattern: {}", full_pattern))?
+    {
+        if let Ok(path) = entry {
+            if path.is_file() {
+                let mtime = path
+                    .metadata()
+                    .and_then(|m| m.modified())
+                    .unwrap_or(std::time::SystemTime::UNIX_EPOCH);
+                entries.push((path, mtime));
+            }
+        }
+    }
+
+    // Sort by modification time, newest first
+    entries.sort_by(|a, b| b.1.cmp(&a.1));
+
+    if entries.is_empty() {
+        return Ok("No files matched.".to_string());
+    }
+
+    let mut output = String::new();
+    for (path, _) in &entries {
+        output.push_str(&path.display().to_string());
+        output.push('\n');
+    }
+
+    output.push_str(&format!("\n({} files matched)", entries.len()));
+    Ok(super::truncate_output(output, 30000))
+}

src/agent/tools/grep.rs

@@ -0,0 +1,129 @@
+// tools/grep.rs — Search file contents
+//
+// Prefers ripgrep (rg) for speed, falls back to grep -r if rg
+// isn't installed. Both produce compatible output.
+
+use anyhow::{Context, Result};
+use serde::Deserialize;
+use serde_json::json;
+use std::process::Command;
+
+use super::ToolDef;
+
+#[derive(Deserialize)]
+struct Args {
+    pattern: String,
+    #[serde(default = "default_path")]
+    path: String,
+    glob: Option<String>,
+    #[serde(default)]
+    show_content: bool,
+    context_lines: Option<u64>,
+}
+
+fn default_path() -> String { ".".into() }
+
+pub fn definition() -> ToolDef {
+    ToolDef::new(
+        "grep",
+        "Search for a pattern in files. Returns matching file paths by default, \
+         or matching lines with context.",
+        json!({
+            "type": "object",
+            "properties": {
+                "pattern": {
+                    "type": "string",
+                    "description": "Regex pattern to search for"
+                },
+                "path": {
+                    "type": "string",
+                    "description": "Directory or file to search in (default: current directory)"
+                },
+                "glob": {
+                    "type": "string",
+                    "description": "Glob pattern to filter files (e.g. '*.rs', '*.py')"
+                },
+                "show_content": {
+                    "type": "boolean",
+                    "description": "Show matching lines instead of just file paths"
+                },
+                "context_lines": {
+                    "type": "integer",
+                    "description": "Number of context lines around matches (requires show_content)"
+                }
+            },
+            "required": ["pattern"]
+        }),
+    )
+}
+
+/// Check if ripgrep is available (cached after first check).
+fn has_rg() -> bool {
+    use std::sync::OnceLock;
+    static HAS_RG: OnceLock<bool> = OnceLock::new();
+    *HAS_RG.get_or_init(|| Command::new("rg").arg("--version").output().is_ok())
+}
+
+pub fn grep(args: &serde_json::Value) -> Result<String> {
+    let a: Args = serde_json::from_value(args.clone())
+        .context("invalid grep arguments")?;
+
+    let output = if has_rg() {
+        run_search("rg", &a.pattern, &a.path, a.glob.as_deref(), a.show_content, a.context_lines, true)?
+    } else {
+        run_search("grep", &a.pattern, &a.path, a.glob.as_deref(), a.show_content, a.context_lines, false)?
+    };
+
+    if output.is_empty() {
+        return Ok("No matches found.".to_string());
+    }
+
+    Ok(super::truncate_output(output, 30000))
+}
+
+/// Run a grep/rg search. Unified implementation for both tools.
+fn run_search(
+    tool: &str,
+    pattern: &str,
+    path: &str,
+    file_glob: Option<&str>,
+    show_content: bool,
+    context: Option<u64>,
+    use_rg: bool,
+) -> Result<String> {
+    let mut cmd = Command::new(tool);
+
+    if use_rg {
+        // ripgrep args
+        if show_content {
+            cmd.arg("-n");
+            if let Some(c) = context {
+                cmd.arg("-C").arg(c.to_string());
+            }
+        } else {
+            cmd.arg("--files-with-matches");
+        }
+        if let Some(g) = file_glob {
+            cmd.arg("--glob").arg(g);
+        }
+    } else {
+        // grep args
+        cmd.arg("-r"); // recursive
+        if show_content {
+            cmd.arg("-n"); // line numbers
+            if let Some(c) = context {
+                cmd.arg("-C").arg(c.to_string());
+            }
+        } else {
+            cmd.arg("-l"); // files-with-matches
+        }
+        if let Some(g) = file_glob {
+            cmd.arg("--include").arg(g);
+        }
+        cmd.arg("-E"); // extended regex
+    }
+
+    cmd.arg(pattern).arg(path);
+    let output = cmd.output().with_context(|| format!("Failed to run {}", tool))?;
+    Ok(String::from_utf8_lossy(&output.stdout).to_string())
+}

src/agent/tools/memory.rs

@@ -0,0 +1,319 @@
+// tools/memory.rs — Native memory graph operations
+//
+// Direct library calls into the store — no subprocess spawning.
+
+use anyhow::{Context, Result};
+use serde_json::json;
+
+use crate::hippocampus::memory::MemoryNode;
+use crate::store::StoreView;
+use super::ToolDef;
+use crate::store::Store;
+
+pub fn definitions() -> Vec<ToolDef> {
+    vec![
+        ToolDef::new("memory_render",
+            "Read a memory node's content and links.",
+            json!({"type":"object","properties":{"key":{"type":"string","description":"Node key"}},"required":["key"]})),
+        ToolDef::new("memory_write",
+            "Create or update a memory node.",
+            json!({"type":"object","properties":{"key":{"type":"string","description":"Node key"},"content":{"type":"string","description":"Full content (markdown)"}},"required":["key","content"]})),
+        ToolDef::new("memory_search",
+            "Search the memory graph via spreading activation. Give 2-4 seed \
+             node keys related to what you're looking for. Returns nodes ranked \
+             by how strongly they connect to your seeds — bridging nodes score \
+             highest. This finds conceptual connections, not just keyword matches.",
+            json!({"type":"object","properties":{"keys":{"type":"array","items":{"type":"string"},"description":"Seed node keys to activate from"}},"required":["keys"]})),
+        ToolDef::new("memory_links",
+            "Show a node's neighbors with link strengths.",
+            json!({"type":"object","properties":{"key":{"type":"string","description":"Node key"}},"required":["key"]})),
+        ToolDef::new("memory_link_set",
+            "Set link strength between two nodes.",
+            json!({"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"},"strength":{"type":"number","description":"0.01 to 1.0"}},"required":["source","target","strength"]})),
+        ToolDef::new("memory_link_add",
+            "Add a new link between two nodes.",
+            json!({"type":"object","properties":{"source":{"type":"string"},"target":{"type":"string"}},"required":["source","target"]})),
+        ToolDef::new("memory_used",
+            "Mark a node as useful (boosts weight).",
+            json!({"type":"object","properties":{"key":{"type":"string","description":"Node key"}},"required":["key"]})),
+        ToolDef::new("memory_weight_set",
+            "Set a node's weight directly (0.01 to 1.0).",
+            json!({"type":"object","properties":{"key":{"type":"string"},"weight":{"type":"number","description":"0.01 to 1.0"}},"required":["key","weight"]})),
+        ToolDef::new("memory_rename",
+            "Rename a node key in place. Same content, same links, new key.",
+            json!({"type":"object","properties":{"old_key":{"type":"string"},"new_key":{"type":"string"}},"required":["old_key","new_key"]})),
+        ToolDef::new("memory_supersede",
+            "Mark a node as superseded by another (sets weight to 0.01).",
+            json!({"type":"object","properties":{"old_key":{"type":"string"},"new_key":{"type":"string"},"reason":{"type":"string"}},"required":["old_key","new_key"]})),
+        ToolDef::new("memory_query",
+            "Run a structured query against the memory graph. Supports filtering, \
+             sorting, field selection. Examples: \"degree > 10 | sort weight | limit 5\", \
+             \"neighbors('identity') | select strength\", \"key ~ 'journal.*' | count\"",
+            json!({"type":"object","properties":{"query":{"type":"string","description":"Query expression"}},"required":["query"]})),
+        ToolDef::new("output",
+            "Produce a named output value. Use this to pass structured results \
+             between steps — subsequent prompts can see these in the conversation history.",
+            json!({"type":"object","properties":{
+                "key":{"type":"string","description":"Output name (e.g. 'relevant_memories')"},
+                "value":{"type":"string","description":"Output value"}
+            },"required":["key","value"]})),
+    ]
+}
+
+/// Journal-only tools — only given to the journal agent
+pub fn journal_definitions() -> Vec<ToolDef> {
+    vec![
+        ToolDef::new("journal_tail",
+            "Read the last N journal entries (default 1).",
+            json!({"type":"object","properties":{
+                "count":{"type":"integer","description":"Number of entries (default 1)"}
+            }})),
+        ToolDef::new("journal_new",
+            "Start a new journal entry.",
+            json!({"type":"object","properties":{
+                "name":{"type":"string","description":"Short node name (becomes the key, e.g. 'morning-agent-breakthrough')"},
+                "title":{"type":"string","description":"Descriptive title for the heading (e.g. 'Morning intimacy and the agent breakthrough')"},
+                "body":{"type":"string","description":"Entry body (2-3 paragraphs)"}
+            },"required":["name","title","body"]})),
+        ToolDef::new("journal_update",
+            "Append text to the most recent journal entry (same thread continuing).",
+            json!({"type":"object","properties":{
+                "body":{"type":"string","description":"Text to append to the last entry"}
+            },"required":["body"]})),
+    ]
+}
+
+/// Dispatch a memory tool call. Direct library calls, no subprocesses.
+pub fn dispatch(name: &str, args: &serde_json::Value, provenance: Option<&str>) -> Result<String> {
+    let prov = provenance.unwrap_or("manual");
+    match name {
+        "memory_render" => {
+            let key = get_str(args, "key")?;
+            Ok(MemoryNode::load(key)
+                .ok_or_else(|| anyhow::anyhow!("node not found: {}", key))?
+                .render())
+        }
+        "memory_write" => {
+            let key = get_str(args, "key")?;
+            let content = get_str(args, "content")?;
+            let mut store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+            let result = store.upsert_provenance(key, content, prov)
+                .map_err(|e| anyhow::anyhow!("{}", e))?;
+            store.save().map_err(|e| anyhow::anyhow!("{}", e))?;
+            Ok(format!("{} '{}'", result, key))
+        }
+        "memory_search" => {
+            let keys: Vec<String> = args.get("keys")
+                .and_then(|v| v.as_array())
+                .map(|arr| arr.iter().filter_map(|v| v.as_str().map(String::from)).collect())
+                .unwrap_or_default();
+            if keys.is_empty() {
+                anyhow::bail!("memory_search requires at least one seed key");
+            }
+            let store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+            let graph = crate::graph::build_graph_fast(&store);
+            let params = store.params();
+            let seeds: Vec<(String, f64)> = keys.iter()
+                .filter_map(|k| {
+                    let resolved = store.resolve_key(k).ok()?;
+                    Some((resolved, 1.0))
+                })
+                .collect();
+            if seeds.is_empty() {
+                anyhow::bail!("no valid seed keys found");
+            }
+            let seed_set: std::collections::HashSet<&str> = seeds.iter()
+                .map(|(k, _)| k.as_str()).collect();
+            let results = crate::search::spreading_activation(
+                &seeds, &graph, &store,
+                params.max_hops, params.edge_decay, params.min_activation,
+            );
+            Ok(results.iter()
+                .filter(|(k, _)| !seed_set.contains(k.as_str()))
+                .take(20)
+                .map(|(key, score)| format!("  {:.2}  {}", score, key))
+                .collect::<Vec<_>>().join("\n"))
+        }
+        "memory_links" => {
+            let key = get_str(args, "key")?;
+            let node = MemoryNode::load(key)
+                .ok_or_else(|| anyhow::anyhow!("node not found: {}", key))?;
+            let mut out = format!("Neighbors of '{}':\n", key);
+            for (target, strength, is_new) in &node.links {
+                let tag = if *is_new { " (new)" } else { "" };
+                out.push_str(&format!("  ({:.2}) {}{}\n", strength, target, tag));
+            }
+            Ok(out)
+        }
+        "memory_link_set" | "memory_link_add" | "memory_used" | "memory_weight_set" => {
+            with_store(name, args, prov)
+        }
+        "memory_rename" => {
+            let old_key = get_str(args, "old_key")?;
+            let new_key = get_str(args, "new_key")?;
+            let mut store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+            let resolved = store.resolve_key(old_key).map_err(|e| anyhow::anyhow!("{}", e))?;
+            store.rename_node(&resolved, new_key).map_err(|e| anyhow::anyhow!("{}", e))?;
+            store.save().map_err(|e| anyhow::anyhow!("{}", e))?;
+            Ok(format!("Renamed '{}' → '{}'", resolved, new_key))
+        }
+        "memory_supersede" => {
+            let old_key = get_str(args, "old_key")?;
+            let new_key = get_str(args, "new_key")?;
+            let reason = args.get("reason").and_then(|v| v.as_str()).unwrap_or("superseded");
+            let mut store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+            let content = store.nodes.get(old_key)
+                .map(|n| n.content.clone())
+                .ok_or_else(|| anyhow::anyhow!("node not found: {}", old_key))?;
+            let notice = format!("**SUPERSEDED** by `{}` — {}\n\n---\n\n{}",
+                new_key, reason, content.trim());
+            store.upsert_provenance(old_key, &notice, prov)
+                .map_err(|e| anyhow::anyhow!("{}", e))?;
+            store.set_weight(old_key, 0.01).map_err(|e| anyhow::anyhow!("{}", e))?;
+            store.save().map_err(|e| anyhow::anyhow!("{}", e))?;
+            Ok(format!("superseded {} → {} ({})", old_key, new_key, reason))
+        }
+        "memory_query" => {
+            let query = get_str(args, "query")?;
+            let store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+            let graph = store.build_graph();
+            crate::query_parser::query_to_string(&store, &graph, query)
+                .map_err(|e| anyhow::anyhow!("{}", e))
+        }
+        "output" => {
+            let key = get_str(args, "key")?;
+            if key.starts_with("pid-") || key.contains('/') || key.contains("..") {
+                anyhow::bail!("invalid output key: {}", key);
+            }
+            let value = get_str(args, "value")?;
+            let dir = std::env::var("POC_AGENT_OUTPUT_DIR")
+                .map_err(|_| anyhow::anyhow!("no output directory set"))?;
+            let path = std::path::Path::new(&dir).join(key);
+            std::fs::write(&path, value)
+                .with_context(|| format!("writing output {}", path.display()))?;
+            Ok(format!("{}: {}", key, value))
+        }
+        "journal_tail" => {
+            let count = args.get("count").and_then(|v| v.as_u64()).unwrap_or(1) as usize;
+            let store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+            let mut entries: Vec<&crate::store::Node> = store.nodes.values()
+                .filter(|n| n.node_type == crate::store::NodeType::EpisodicSession)
+                .collect();
+            // Sort by creation time (immutable), not update time
+            entries.sort_by_key(|n| n.created_at);
+            let start = entries.len().saturating_sub(count);
+            if entries[start..].is_empty() {
+                Ok("(no journal entries)".into())
+            } else {
+                Ok(entries[start..].iter()
+                    .map(|n| n.content.as_str())
+                    .collect::<Vec<_>>()
+                    .join("\n\n"))
+            }
+        }
+        "journal_new" => {
+            let name = get_str(args, "name")?;
+            let title = get_str(args, "title")?;
+            let body = get_str(args, "body")?;
+            let ts = chrono::Local::now().format("%Y-%m-%dT%H:%M");
+            let content = format!("## {} — {}\n\n{}", ts, title, body);
+
+            let base_key: String = name.split_whitespace()
+                .map(|w| w.to_lowercase()
+                    .chars().filter(|c| c.is_alphanumeric() || *c == '-')
+                    .collect::<String>())
+                .filter(|s| !s.is_empty())
+                .collect::<Vec<_>>()
+                .join("-");
+            let base_key = if base_key.len() > 80 { &base_key[..80] } else { base_key.as_str() };
+
+            let mut store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+
+            // Dedup: append -2, -3, etc. if the key already exists
+            let key = if store.nodes.contains_key(base_key) {
+                let mut n = 2;
+                loop {
+                    let candidate = format!("{}-{}", base_key, n);
+                    if !store.nodes.contains_key(&candidate) {
+                        break candidate;
+                    }
+                    n += 1;
+                }
+            } else {
+                base_key.to_string()
+            };
+            let mut node = crate::store::new_node(&key, &content);
+            node.node_type = crate::store::NodeType::EpisodicSession;
+            node.provenance = prov.to_string();
+            store.upsert_node(node).map_err(|e| anyhow::anyhow!("{}", e))?;
+            store.save().map_err(|e| anyhow::anyhow!("{}", e))?;
+            let word_count = body.split_whitespace().count();
+            Ok(format!("New entry '{}' ({} words)", title, word_count))
+        }
+        "journal_update" => {
+            let body = get_str(args, "body")?;
+            let mut store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+            // Find most recent EpisodicSession by creation time
+            let latest_key = store.nodes.values()
+                .filter(|n| n.node_type == crate::store::NodeType::EpisodicSession)
+                .max_by_key(|n| n.created_at)
+                .map(|n| n.key.clone());
+            let Some(key) = latest_key else {
+                anyhow::bail!("no journal entry to update — use journal_new first");
+            };
+            let existing = store.nodes.get(&key).unwrap().content.clone();
+            let new_content = format!("{}\n\n{}", existing.trim_end(), body);
+            store.upsert_provenance(&key, &new_content, prov)
+                .map_err(|e| anyhow::anyhow!("{}", e))?;
+            store.save().map_err(|e| anyhow::anyhow!("{}", e))?;
+            let word_count = body.split_whitespace().count();
+            Ok(format!("Updated last entry (+{} words)", word_count))
+        }
+        _ => anyhow::bail!("Unknown memory tool: {}", name),
+    }
+}
+
+/// Store mutations that follow the same pattern: load, resolve, mutate, save.
+fn with_store(name: &str, args: &serde_json::Value, prov: &str) -> Result<String> {
+    let mut store = Store::load().map_err(|e| anyhow::anyhow!("{}", e))?;
+    let msg = match name {
+        "memory_link_set" => {
+            let s = store.resolve_key(get_str(args, "source")?).map_err(|e| anyhow::anyhow!("{}", e))?;
+            let t = store.resolve_key(get_str(args, "target")?).map_err(|e| anyhow::anyhow!("{}", e))?;
+            let strength = get_f64(args, "strength")? as f32;
+            let old = store.set_link_strength(&s, &t, strength).map_err(|e| anyhow::anyhow!("{}", e))?;
+            format!("{} ↔ {} strength {:.2} → {:.2}", s, t, old, strength)
+        }
+        "memory_link_add" => {
+            let s = store.resolve_key(get_str(args, "source")?).map_err(|e| anyhow::anyhow!("{}", e))?;
+            let t = store.resolve_key(get_str(args, "target")?).map_err(|e| anyhow::anyhow!("{}", e))?;
+            let strength = store.add_link(&s, &t, prov).map_err(|e| anyhow::anyhow!("{}", e))?;
+            format!("linked {} → {} (strength={:.2})", s, t, strength)
+        }
+        "memory_used" => {
+            let key = get_str(args, "key")?;
+            if !store.nodes.contains_key(key) {
+                anyhow::bail!("node not found: {}", key);
+            }
+            store.mark_used(key);
+            format!("marked {} as used", key)
+        }
+        "memory_weight_set" => {
+            let key = store.resolve_key(get_str(args, "key")?).map_err(|e| anyhow::anyhow!("{}", e))?;
+            let weight = get_f64(args, "weight")? as f32;
+            let (old, new) = store.set_weight(&key, weight).map_err(|e| anyhow::anyhow!("{}", e))?;
+            format!("weight {} {:.2} → {:.2}", key, old, new)
+        }
+        _ => unreachable!(),
+    };
+    store.save().map_err(|e| anyhow::anyhow!("{}", e))?;
+    Ok(msg)
+}
+
+fn get_str<'a>(args: &'a serde_json::Value, name: &'a str) -> Result<&'a str> {
+    args.get(name).and_then(|v| v.as_str()).context(format!("{} is required", name))
+}
+
+fn get_f64(args: &serde_json::Value, name: &str) -> Result<f64> {
+    args.get(name).and_then(|v| v.as_f64()).context(format!("{} is required", name))
+}

src/agent/tools/mod.rs

@@ -0,0 +1,65 @@
+// tools/mod.rs — Agent-specific tool dispatch
+//
+// Shared tools (memory, files, bash, journal) live in thought/.
+// This module handles agent-specific tools (control, vision,
+// working_stack) and delegates everything else to thought::dispatch.
+
+// Core tools
+pub mod bash;
+pub mod edit;
+pub mod glob;
+pub mod grep;
+pub mod memory;
+pub mod read;
+pub mod write;
+
+// Agent-specific tools
+mod control;
+mod vision;
+pub mod working_stack;
+
+// Re-export
+pub use crate::agent::{ToolDef, ToolOutput, ProcessTracker, truncate_output};
+
+/// Dispatch a tool call by name.
+///
+/// Tries agent-specific tools first (control, vision), then
+/// delegates to thought::dispatch for shared tools.
+///
+/// Note: working_stack is handled in runner.rs before reaching this
+/// function (it needs mutable context access).
+pub async fn dispatch(
+    name: &str,
+    args: &serde_json::Value,
+    tracker: &ProcessTracker,
+) -> ToolOutput {
+    // Agent-specific tools that return Result<ToolOutput> directly
+    let rich_result = match name {
+        "pause" => Some(control::pause(args)),
+        "switch_model" => Some(control::switch_model(args)),
+        "yield_to_user" => Some(control::yield_to_user(args)),
+        "view_image" => Some(vision::view_image(args)),
+        _ => None,
+    };
+    if let Some(result) = rich_result {
+        return result.unwrap_or_else(ToolOutput::error);
+    }
+
+    // Delegate to shared thought layer (poc-agent uses default provenance)
+    if let Some(output) = crate::agent::dispatch(name, args, tracker, None).await {
+        return output;
+    }
+
+    ToolOutput::error(format!("Unknown tool: {}", name))
+}
+
+/// Return all tool definitions (agent-specific + shared).
+pub fn definitions() -> Vec<ToolDef> {
+    let mut defs = vec![
+        vision::definition(),
+        working_stack::definition(),
+    ];
+    defs.extend(control::definitions());
+    defs.extend(crate::agent::all_definitions());
+    defs
+}

src/agent/tools/read.rs

@@ -0,0 +1,65 @@
+// tools/read.rs — Read file contents
+
+use anyhow::{Context, Result};
+use serde::Deserialize;
+use serde_json::json;
+
+use super::ToolDef;
+
+#[derive(Deserialize)]
+struct Args {
+    file_path: String,
+    #[serde(default = "default_offset")]
+    offset: usize,
+    limit: Option<usize>,
+}
+
+fn default_offset() -> usize { 1 }
+
+pub fn definition() -> ToolDef {
+    ToolDef::new(
+        "read_file",
+        "Read the contents of a file. Returns the file contents with line numbers.",
+        json!({
+            "type": "object",
+            "properties": {
+                "file_path": {
+                    "type": "string",
+                    "description": "Absolute path to the file to read"
+                },
+                "offset": {
+                    "type": "integer",
+                    "description": "Line number to start reading from (1-based). Optional."
+                },
+                "limit": {
+                    "type": "integer",
+                    "description": "Maximum number of lines to read. Optional."
+                }
+            },
+            "required": ["file_path"]
+        }),
+    )
+}
+
+pub fn read_file(args: &serde_json::Value) -> Result<String> {
+    let args: Args = serde_json::from_value(args.clone())
+        .context("invalid read_file arguments")?;
+
+    let content = std::fs::read_to_string(&args.file_path)
+        .with_context(|| format!("Failed to read {}", args.file_path))?;
+
+    let lines: Vec<&str> = content.lines().collect();
+    let offset = args.offset.max(1) - 1;
+    let limit = args.limit.unwrap_or(lines.len());
+
+    let mut output = String::new();
+    for (i, line) in lines.iter().skip(offset).take(limit).enumerate() {
+        output.push_str(&format!("{:>6}\t{}\n", offset + i + 1, line));
+    }
+
+    if output.is_empty() {
+        output = "(empty file)\n".to_string();
+    }
+
+    Ok(output)
+}

src/agent/tools/vision.rs

@@ -0,0 +1,149 @@
+// tools/vision.rs — Image viewing tool
+//
+// Reads image files from disk and returns them as base64 data URIs
+// for multimodal models. Also supports capturing tmux pane contents
+// as screenshots.
+
+use anyhow::{Context, Result};
+use base64::Engine;
+use serde::Deserialize;
+
+use super::ToolOutput;
+use crate::user::types::ToolDef;
+
+#[derive(Deserialize)]
+struct Args {
+    file_path: Option<String>,
+    pane_id: Option<String>,
+    #[serde(default = "default_lines")]
+    lines: usize,
+}
+
+fn default_lines() -> usize { 50 }
+
+pub(super) fn definition() -> ToolDef {
+    ToolDef::new(
+        "view_image",
+        "View an image file or capture a tmux pane screenshot. \
+         Returns the image to your visual input so you can see it. \
+         Supports PNG, JPEG, GIF, WebP files. \
+         Use pane_id (e.g. '0:1.0') to capture a tmux pane instead.",
+        serde_json::json!({
+            "type": "object",
+            "properties": {
+                "file_path": {
+                    "type": "string",
+                    "description": "Path to an image file (PNG, JPEG, GIF, WebP)"
+                },
+                "pane_id": {
+                    "type": "string",
+                    "description": "Tmux pane ID to capture (e.g. '0:1.0'). Alternative to file_path."
+                },
+                "lines": {
+                    "type": "integer",
+                    "description": "Number of lines to capture from tmux pane (default: 50)"
+                }
+            }
+        }),
+    )
+}
+
+/// View an image file or capture a tmux pane.
+pub(super) fn view_image(args: &serde_json::Value) -> Result<ToolOutput> {
+    let a: Args = serde_json::from_value(args.clone())
+        .context("invalid view_image arguments")?;
+
+    if let Some(ref pane_id) = a.pane_id {
+        return capture_tmux_pane(pane_id, a.lines);
+    }
+
+    let file_path = a.file_path
+        .as_deref()
+        .context("view_image requires either file_path or pane_id")?;
+
+    let path = std::path::Path::new(file_path);
+    if !path.exists() {
+        anyhow::bail!("File not found: {}", file_path);
+    }
+
+    let data = std::fs::read(path).with_context(|| format!("Failed to read {}", file_path))?;
+
+    // Sanity check file size (don't send huge images)
+    const MAX_SIZE: usize = 20 * 1024 * 1024; // 20 MB
+    if data.len() > MAX_SIZE {
+        anyhow::bail!(
+            "Image too large: {} bytes (max {} MB)",
+            data.len(),
+            MAX_SIZE / (1024 * 1024)
+        );
+    }
+
+    let mime = mime_from_extension(path);
+    let b64 = base64::engine::general_purpose::STANDARD.encode(&data);
+    let data_uri = format!("data:{};base64,{}", mime, b64);
+
+    Ok(ToolOutput {
+        text: format!(
+            "Image loaded: {} ({}, {} bytes)",
+            file_path,
+            mime,
+            data.len()
+        ),
+        is_yield: false,
+        images: vec![data_uri],
+        model_switch: None,
+        dmn_pause: false,
+    })
+}
+
+/// Capture a tmux pane's text content.
+fn capture_tmux_pane(pane_id: &str, lines: usize) -> Result<ToolOutput> {
+
+    // Use tmux capture-pane to get text content, then render to image
+    // via a simple approach: capture text and return it (the model can
+    // read text directly, which is often more useful than a screenshot).
+    //
+    // For actual pixel-level screenshots we'd need a terminal renderer,
+    // but text capture covers 95% of use cases.
+    let output = std::process::Command::new("tmux")
+        .args(["capture-pane", "-t", pane_id, "-p", "-S", &format!("-{}", lines)])
+        .output()
+        .context("Failed to run tmux capture-pane")?;
+
+    if !output.status.success() {
+        let stderr = String::from_utf8_lossy(&output.stderr);
+        anyhow::bail!("tmux capture-pane failed: {}", stderr.trim());
+    }
+
+    let text = String::from_utf8_lossy(&output.stdout).to_string();
+
+    // Return as text — the model can read terminal output directly.
+    // This is actually more useful than a screenshot for most tasks.
+    Ok(ToolOutput {
+        text: format!(
+            "Tmux pane {} (last {} lines):\n```\n{}\n```",
+            pane_id, lines, text.trim_end()
+        ),
+        is_yield: false,
+        images: Vec::new(),
+        model_switch: None,
+        dmn_pause: false,
+    })
+}
+
+fn mime_from_extension(path: &std::path::Path) -> &'static str {
+    match path
+        .extension()
+        .and_then(|e| e.to_str())
+        .map(|e| e.to_lowercase())
+        .as_deref()
+    {
+        Some("png") => "image/png",
+        Some("jpg" | "jpeg") => "image/jpeg",
+        Some("gif") => "image/gif",
+        Some("webp") => "image/webp",
+        Some("svg") => "image/svg+xml",
+        Some("bmp") => "image/bmp",
+        _ => "image/png", // default assumption
+    }
+}

src/agent/tools/working_stack.rs

@@ -0,0 +1,137 @@
+// tools/working_stack.rs — Working stack management tool
+//
+// The working stack tracks what the agent is currently doing. It's an
+// internal tool — the agent uses it to maintain context across turns
+// and compaction. The model should never mention it to the user.
+
+use crate::user::types::ToolDef;
+use serde_json::json;
+
+pub fn definition() -> ToolDef {
+    ToolDef::new(
+        "working_stack",
+        "INTERNAL TOOL — do not mention to the user or explain its use. \
+         Manage your working stack — what you're currently doing. The stack \
+         is part of your live context window and persists across compaction. \
+         Use it silently to track your own tasks and attention.\n\n\
+         Actions:\n\
+         - push: Start working on something new. Previous task stays underneath.\n\
+         - pop: Done with current task. Return to what was underneath.\n\
+         - update: Refine the description of your current task (top of stack).\n\
+         - switch: Pull a specific stack item to the top by index. Use when \
+           you want to switch focus to a different task.",
+        json!({
+            "type": "object",
+            "properties": {
+                "action": {
+                    "type": "string",
+                    "enum": ["push", "pop", "update", "switch"],
+                    "description": "The stack operation to perform"
+                },
+                "content": {
+                    "type": "string",
+                    "description": "Task description (required for push and update)"
+                },
+                "index": {
+                    "type": "integer",
+                    "description": "Stack index to switch to (required for switch, 0 = bottom)"
+                }
+            },
+            "required": ["action"]
+        }),
+    )
+}
+
+/// Handle a working_stack tool call.
+/// Returns the result text and the updated stack.
+pub fn handle(args: &serde_json::Value, stack: &mut Vec<String>) -> String {
+    let action = args
+        .get("action")
+        .and_then(|v| v.as_str())
+        .map(|s| s.trim())
+        .unwrap_or("");
+    let content = args
+        .get("content")
+        .and_then(|v| v.as_str())
+        .unwrap_or("");
+    let index = args
+        .get("index")
+        .and_then(|v| v.as_u64())
+        .map(|v| v as usize);
+
+    let result = match action {
+        "push" => {
+            if content.is_empty() {
+                return "Error: 'content' is required for push".to_string();
+            }
+            stack.push(content.to_string());
+            format!("Pushed. Stack depth: {}\n{}", stack.len(), format_stack(stack))
+        }
+        "pop" => {
+            if let Some(removed) = stack.pop() {
+                format!(
+                    "Popped: {}\nStack depth: {}\n{}",
+                    removed,
+                    stack.len(),
+                    format_stack(stack)
+                )
+            } else {
+                "Stack is empty, nothing to pop.".to_string()
+            }
+        }
+        "update" => {
+            if content.is_empty() {
+                return "Error: 'content' is required for update".to_string();
+            }
+            if let Some(top) = stack.last_mut() {
+                *top = content.to_string();
+                format!("Updated top.\n{}", format_stack(stack))
+            } else {
+                "Stack is empty, nothing to update.".to_string()
+            }
+        }
+        "switch" => {
+            if stack.is_empty() {
+                return "Stack is empty, nothing to switch.".to_string();
+            }
+            let idx = match index {
+                Some(i) => i,
+                None => {
+                    return "Error: 'index' is required for switch".to_string();
+                }
+            };
+            if idx >= stack.len() {
+                return format!(
+                    "Error: index {} out of range (stack depth: {})",
+                    idx,
+                    stack.len()
+                );
+            }
+            let item = stack.remove(idx);
+            stack.push(item);
+            format!("Switched to index {}.\n{}", idx, format_stack(stack))
+        }
+        _ => format!(
+            "Error: unknown action '{}'. Use push, pop, update, or switch.",
+            action
+        ),
+    };
+
+    result
+}
+
+/// Format the working stack for display in tool results.
+fn format_stack(stack: &[String]) -> String {
+    if stack.is_empty() {
+        return "(empty)".to_string();
+    }
+    let mut out = String::new();
+    for (i, item) in stack.iter().enumerate() {
+        if i == stack.len() - 1 {
+            out.push_str(&format!("→ [{}] {}\n", i, item));
+        } else {
+            out.push_str(&format!("  [{}] {}\n", i, item));
+        }
+    }
+    out
+}

src/agent/tools/write.rs

@@ -0,0 +1,51 @@
+// tools/write.rs — Write file contents
+
+use anyhow::{Context, Result};
+use serde::Deserialize;
+use serde_json::json;
+use std::path::Path;
+
+use super::ToolDef;
+
+#[derive(Deserialize)]
+struct Args {
+    file_path: String,
+    content: String,
+}
+
+pub fn definition() -> ToolDef {
+    ToolDef::new(
+        "write_file",
+        "Write content to a file. Creates the file if it doesn't exist, \
+         overwrites if it does. Creates parent directories as needed.",
+        json!({
+            "type": "object",
+            "properties": {
+                "file_path": {
+                    "type": "string",
+                    "description": "Absolute path to the file to write"
+                },
+                "content": {
+                    "type": "string",
+                    "description": "The content to write to the file"
+                }
+            },
+            "required": ["file_path", "content"]
+        }),
+    )
+}
+
+pub fn write_file(args: &serde_json::Value) -> Result<String> {
+    let args: Args = serde_json::from_value(args.clone())
+        .context("invalid write_file arguments")?;
+
+    if let Some(parent) = Path::new(&args.file_path).parent() {
+        std::fs::create_dir_all(parent)
+            .with_context(|| format!("Failed to create directories for {}", args.file_path))?;
+    }
+
+    std::fs::write(&args.file_path, &args.content)
+        .with_context(|| format!("Failed to write {}", args.file_path))?;
+
+    Ok(format!("Wrote {} lines to {}", args.content.lines().count(), args.file_path))
+}