Tools

Every agent gets the built-in tools below, plus the tools of connected MCP servers and the control service. Each tool has a kind that decides when it needs approval:

Kind	Needs approval in
Safe	never; consecutive Safe calls also run in parallel
Edit	ask mode
Execute	ask and edits modes

Deny rules apply to every kind, in every mode.

Overview

Tool	Kind	Purpose	Permission key
read	Safe	Read a file, or an image	none
write	Edit	Create or overwrite a file	path
edit	Edit	Replace an exact string in a file	path
bash	Execute	Run a shell command	each command segment
job_list	Safe	List background jobs	none
job_output	Safe	Show a job’s latest output	none
job_kill	Execute	Stop a job and its processes	job id
glob	Safe	Find files by pattern	none
grep	Safe	Search file contents	none
web_fetch	Execute	Fetch a URL	host
todo	Safe	Keep a task list for the current request	none
project_index	Safe	Read or search the project index, or add a note to it	none
skill	Safe	Load a skill’s instructions and files	none
memory_save	Safe	Save a memory	none
memory_search	Safe	Search memories	none
memory_forget	Safe	Delete a memory	none
agent_spawn	Safe	Start a subagent	none
agent_wait	Safe	Wait for subagent reports	none
agent_send	Safe	Message a subagent	none
agent_list	Safe	List subagents	none
malac_settings	Safe	Inspect malac’s configuration and status	none
malac_configure	Execute	Change malac’s configuration	action:key

Tool output longer than 40,000 characters is cut from the middle before it reaches the model, keeping the start and the more relevant end.

Files

read

Reads a file. Text comes back with line numbers (cat -n style); PNG, JPEG, GIF and WebP files come back as images (up to 5 MB). Binary files are refused.

Argument	Type	Meaning
path	string	Absolute or working-directory-relative path. ~/ is expanded.
offset	integer	1-based line to start from
limit	integer	Maximum lines to return (default 2000)

Lines longer than 2000 characters are truncated.

write

Creates a file, or replaces its entire contents. Parent directories are created.

Argument	Type	Meaning
path	string	File to write
content	string	The new contents

edit

Replaces an exact string in a file and returns the edited lines with numbers, so the agent can check the result.

Argument	Type	Meaning
path	string	File to edit
old_string	string	Text to replace. Must match exactly, whitespace included, and be unique unless replace_all is set.
new_string	string	Replacement
replace_all	bool	Replace every occurrence (default false)

Read before write. write and edit refuse to change an existing file the agent has not read in this session, or that changed on disk since it last read it. Edits never clobber changes the model has not seen.

Shell

bash

Runs a command in the working directory and returns combined stdout and stderr.

Argument	Type	Meaning
command	string	The command
description	string	A few words on what it does
timeout	integer	Seconds before the command is killed (default 120, max 1800)
background	bool	Start without waiting: the command becomes a job that keeps running, with its output in ~/.malac/jobs/<id>.log

• Each call starts a fresh shell (your $SHELL if it is bash or zsh, else /bin/sh), so cd does not persist.
• stdin is closed; PAGER and GIT_PAGER are cat, and MALAC=1 is set so scripts can tell.
• A non-zero exit, a timeout or a cancellation is reported as an error, with the exit code.
• On timeout or Ctrl+C, the whole process group is killed.

Jobs

Background commands (bash with background: true) become jobs that outlive the agent’s turn. See Jobs.

Tool	Arguments	What it does
job_list	none	Jobs, newest first, with status, process id and working directory
job_output	id, tail (lines from the end, default 100, max 2000)	The latest output, and whether the job still runs
job_kill	id	SIGTERM to the job’s process group, then SIGKILL after 3 seconds

Search

glob

Finds files by glob pattern, such as **/*.rs or src/**/mod.rs, newest first. Respects .gitignore. Shows up to 500 results.

Argument	Type	Meaning
pattern	string	Glob pattern
path	string	Directory to search (default: working directory)

grep

Searches file contents with a regular expression (Rust regex syntax) and returns path:line: text matches. Respects .gitignore.

Argument	Type	Meaning
pattern	string	Regular expression
path	string	File or directory (default: working directory)
glob	string	Only search files matching this glob, such as *.ts
ignore_case	bool	Case-insensitive search
files_only	bool	Return only file paths
limit	integer	Maximum matches (default 200)

A search that walks for more than 20 seconds (say, from /) stops with partial results.

Web

web_fetch

Fetches an http or https URL. HTML is converted to readable text; JSON and plain text are returned as is. Responses over 10 MB are refused; requests time out after 30 seconds. For pages that need JavaScript or a login, the agent uses the browser tools instead.

Argument	Type	Meaning
url	string	The URL
max_chars	integer	Truncate the result (default 40,000)

Permission rules match the host: web_fetch(docs.rs), web_fetch(*.rust-lang.org).

Planning

todo

Replaces the agent’s task list for the current request. The terminal and web UI show it. The agent uses it for work with three or more steps, keeps exactly one item in_progress, and sends the whole list every time.

Argument	Type	Meaning
items	array	Items with content and status (pending, in_progress or completed)

Project

project_index

Reads the project index, .malac/index.md, kept current from the files. The system prompt tells the agent to start here before searching broadly.

Argument	Type	Meaning
section	string	overview, tree, docs, symbols, notes or all. Without arguments: the overview and tree.
path	string	Only entries under this path prefix
query	string	Paths, symbols and headings containing this text, case-insensitive
note	string	One line for the Notes section, for the next session: where something lives, how parts connect
rebuild	bool	Regenerate the index from scratch

Outside a repository, or with [context] index = false, there is no index and the tool says so.

skill

Loads a skill listed in the system prompt: its instructions, with paths filled in, and the list of its files. From then on the agent’s bash commands have SKILL_DIR set to the skill’s folder.

Argument	Type	Meaning
name	string	The skill’s name as listed, for example ponytail:ponytail-review
arguments	string	Arguments for the skill’s $ARGUMENTS

Memory

See Memory.

Tool	Arguments
memory_save	name (short kebab-case id), description (one line), content, scope (global or project), kind (for project memories: command, convention, gotcha, decision or note, the section of .malac/MALAC.md it is listed under)
memory_search	query, limit (default 5)
memory_forget	name, scope

The memory tools are removed when memory.enabled = false.

Delegation

See Subagents.

Tool	Arguments
agent_spawn	task (the complete brief), label, agent (an agent type), model (chosen from the models listed in the system prompt), read_only, background
agent_wait	ids (default: all subagents still working), timeout (seconds, default 1800)
agent_send	id, message, background
agent_list	none

Agents at agents.max_depth (default 3) do not get these tools.

malac itself

See Configure malac by asking.

Tool	Arguments
malac_settings	show (config, reference, models, status, context or plugins), use_model
malac_configure	action (set, unset, set_api_key, remove_api_key, install_update, marketplace_add, marketplace_remove, marketplace_update, plugin_install, plugin_enable, plugin_disable, plugin_uninstall, plugin_update), file (user or project), key, value, provider, api_key, source (for marketplace_add), plugin (a plugin or marketplace name)

Enabling a plugin that runs code asks you, even in autopilot.

MCP tools

Tools from MCP servers are named <server>__<tool> unless the server sets prefix = false. Tools the server marks read-only are Safe; all others are Execute. The control service’s tools have no prefix; see Control service tools.