Action Primitives
Relevant source files
The following files were used as context for generating this wiki page:
Action Primitives represent the fundamental atomic operations that the Autohand agent can perform to interact with the workspace, the web, and the underlying operating system. These primitives are encapsulated as "tools" that the agent invokes through a Reasoning-Action (ReAct) loop, allowing for complex multi-step task execution ranging from codebase modification to real-time information retrieval.
The system is architected to ensure safety through a permission-based execution model, providing the agent with a diverse toolset while maintaining user control over destructive operations. Action Primitives are categorized into several functional domains: Filesystem, Version Control (Git), Dependency Management, System Commands, and External Web Retrieval.
Architecture and Execution Flow
The execution of an action primitive involves several layers: the AutohandAgent initiates a request, the ToolManager validates and filters the tool based on the current context, and the ActionExecutor performs the actual operation.
The diagram above illustrates the validation and security pipeline that every action primitive must pass through before execution.
Sources: src/core/agent.ts:771-935, src/core/toolManager.ts:654-712
Tool Management and Filtering
The ToolManager maintains the registry of available primitives and applies a ToolFilter based on the ClientContext (e.g., 'cli' or 'restricted'). Primitives can be marked as requiring explicit user approval, especially those deemed "dangerous" or destructive.
Sources: src/core/toolManager.ts:25-50, src/core/toolManager.ts:601-610
Core Action Categories
Filesystem Primitives
These primitives provide the agent with the ability to observe and modify the codebase structure and content.
| Primitive | Description | Required Arguments |
|---|---|---|
read_file | Reads contents of a file. Supports chunking for large files. | path |
write_file | Writes full contents to a file. Triggers permission checks for new files. | path, contents |
search_replace | Applies precise text replacements using SEARCH/REPLACE blocks. | path, blocks |
multi_file_edit | Applies multiple simultaneous edits to a single file. | file_path, edits |
list_tree | Recursively lists the directory structure of the workspace. | path |
delete_path | Removes files or directories (requires approval). | path |
The ActionExecutor implements "Smart Reading" for large files, providing an outline and specific line chunks to avoid exceeding the agent's context window.
Sources: src/core/actionExecutor.ts:130-186, src/core/toolManager.ts:64-150
Version Control Primitives (Git)
Autohand includes a comprehensive suite of Git primitives for managing repository state and parallel development workflows.
Advanced Worktree Automation
The WorktreeManager extends standard Git functionality by allowing the agent to manage parallel development environments through templates (feature, hotfix, review, experiment).
Sources: src/actions/worktree.ts:60-100
System and Dependency Primitives
These primitives allow the agent to manage the project's environment and execute arbitrary shell commands.
| Primitive | Description | Key Parameters |
|---|---|---|
run_command | Executes shell commands. Supports background execution for dev servers. | command, args, background |
add_dependency | Adds a package to the project (npm, bun, etc.). | name, version, dev |
custom_command | Executes a user-defined reusable command. | name, command |
Sources: src/core/actionExecutor.ts:365-395, src/core/toolManager.ts:188-210
External Information Retrieval
The agent can reach beyond the local workspace using web-based primitives to fetch documentation or package information.
Security and Permission Model
Safety is integrated directly into the action execution pipeline. Primitives classified as "dangerous" (e.g., delete_path, run_command, git_push) trigger a mandatory confirmation flow.
The PermissionManager tracks user decisions to build a persistent policy, reducing repetitive prompts for known safe actions while blocking blacklisted paths.
Sources: src/core/actionExecutor.ts:80-120, src/core/agent.ts:133-150
Meta-Tools and Extensibility
The create_meta_tool primitive allows the agent to define new Action Primitives dynamically. These are persisted to ~/.autohand/tools/ and become available in subsequent sessions.
// Example of a meta-tool definition
{
"tool": "create_meta_tool",
"args": {
"name": "count_lines",
"description": "Count lines in a file",
"parameters": {
"type": "object",
"properties": { "path": { "type": "string" } }
},
"handler": "wc -l {{path}}"
}
}
The system performs security scanning on the handler template to prevent command injection before saving the tool.
Sources: src/core/actionExecutor.ts:840-885, src/core/toolManager.ts:586-598
Action Primitives provide the interface between the agent's reasoning and the physical state of the user's computer. By standardizing these interactions into a governed toolset, Autohand enables reliable, multi-step automation while maintaining high standards for security and workspace integrity.