Overview
The SDK includes built-in tools that cover common agent operations:
- File Operations: Read, Write, Edit, Glob, Grep
- Shell Execution: Bash
- Task Management: TodoWrite
- User Interaction: AskUserQuestion
All built-in tools are available in the picrust::tools::common module.
use picrust::tools::{ToolRegistry, common::*};
use std::sync::Arc;
let mut tools = ToolRegistry::new();
// File operations
tools.register(ReadTool::new()?);
tools.register(WriteTool::new()?);
tools.register(EditTool::new()?);
tools.register(GlobTool::new()?);
tools.register(GrepTool::new()?);
// Shell
tools.register(BashTool::new()?);
// Task management
tools.register(TodoWriteTool::new()?);
// User interaction
tools.register(AskUserQuestionTool::new());
let tools = Arc::new(tools);
Parameters
{
"file_path": String, // Required: Path to file
"offset": Option<usize>, // Optional: Start line (1-indexed)
"limit": Option<usize> // Optional: Number of lines (default: 2000)
}
Examples
// Read entire file
{ "file_path": "./src/main.rs" }
// Read with pagination
{ "file_path": "./large-file.txt", "offset": 100, "limit": 50 }
// Read image (auto-detected by extension)
{ "file_path": "./screenshot.png" }
The Read tool automatically detects file type by extension and handles text, images, and PDFs appropriately.
Parameters
{
"file_path": String, // Required: Path to file
"content": String // Required: Content to write
}
WriteTool overwrites files without confirmation. Use EditTool for safer modifications to existing files.
Parameters
{
"file_path": String, // Required: Path to file
"old_string": String, // Required: Text to find
"new_string": String, // Required: Replacement text
"replace_all": bool // Optional: Replace all occurrences (default: false)
}
- Matches exact strings (not regex)
- Fails if
old_string not found
- Fails if
old_string appears multiple times (unless replace_all is true)
Permissions: Required for each file edit.
Finds files matching glob patterns. Results sorted by modification time (most recent first).
Parameters
{
"pattern": String, // Required: Glob pattern
"path": Option<String> // Optional: Base directory (default: cwd)
}
Glob Patterns
* matches any characters except /** matches any characters including /? matches single character[abc] matches one of a, b, or c{foo,bar} matches foo or bar
Permissions: Safe tool — no permission required.
Searches file contents using regex patterns.
Parameters
{
"pattern": String, // Required: Regex pattern
"path": Option<String>, // Optional: File or directory to search
"glob": Option<String>, // Optional: Filter files by glob pattern
"type": Option<String>, // Optional: File type filter (js, py, rust, etc.)
"output_mode": String, // Optional: "content" | "files_with_matches" | "count"
"case_insensitive": bool, // Optional: Case insensitive search
"context": Option<usize>, // Optional: Lines of context around matches
}
Parameters
{
"command": String, // Required: Command to execute
"timeout": Option<u64>, // Optional: Timeout in milliseconds (default: 120000)
"description": Option<String> // Optional: Human-readable description
}
- Executes in current working directory
- Working directory persists between commands
- Shell state does not persist (use
&& to chain)
- Captures both stdout and stderr
BashTool is dangerous and always requires permission. Commands have full system access.
Parameters
{
"action": String, // Required: "create" | "update" | "complete" | "list"
"task_id": Option<u32>, // Required for update/complete
"title": Option<String>,
"description": Option<String>
}
Custom Base Directories
Some tools support custom base directories for security:
let read_tool = ReadTool::with_base_dir("/restricted/path");
tools.register(read_tool);
let write_tool = WriteTool::with_base_dir("/output/directory");
tools.register(write_tool);
Next Steps
Custom Tools
Create your own tools
Hooks
Modify tool behavior
