Factory functions for the four built-in tools: read, write, edit, bash.
These tools cover file system access and shell execution. Together they are sufficient for most agent tasks — reading context, writing code, applying edits, and running scripts (including skill scripts).
Shell execution uses erlexec (:exec) which manages process groups and
cleans up child processes on timeout or termination.
Usage
tools = [
Planck.Agent.BuiltinTools.read(),
Planck.Agent.BuiltinTools.write(),
Planck.Agent.BuiltinTools.edit(),
Planck.Agent.BuiltinTools.bash()
]Pass these alongside any inter-agent tools when starting an agent.
Summary
Functions
@spec bash() :: Planck.Agent.Tool.t()
Returns the bash tool — runs a shell command via erlexec.
Process groups are cleaned up on timeout or termination. Both stdout and stderr are captured; stderr is appended to the output when non-empty.
cwd and timeout are optional tool arguments supplied by the caller at
runtime — they are not baked into the tool at construction time.
@spec edit() :: Planck.Agent.Tool.t()
Returns the edit tool — replaces an exact string in a file.
Fails if old_string is not found or appears more than once. Make
old_string long enough to be unique in the file.
@spec read() :: Planck.Agent.Tool.t()
Returns the read tool — reads the contents of a file from disk.
Supports optional offset (lines to skip from the start) and limit
(maximum number of lines to return) for reading large files in chunks.
Uses line-by-line streaming so only the requested portion is loaded.
@spec write() :: Planck.Agent.Tool.t()
Returns the write tool — writes content to a file.
Creates the file and any missing parent directories. Overwrites if the file already exists.