Built-in Tools
Mistermorph does not register every tool as one flat bundle. Tools are layered by runtime environment:
- Static tools: created from config and directory context alone.
- Engine tools: registered when an agent engine is assembled for a run.
- Runtime tools: require an active LLM client/model or task context.
- Dedicated tools: only appear inside concrete runtimes such as Telegram or Slack.
Tool Groups at a Glance
| Group | When available | Tools |
|---|---|---|
| Static tools | Available from config alone | read_file, write_file, bash, powershell, url_fetch, web_search, contacts_send, todo_list |
| Engine tools | Available when an agent engine is assembled for a run | spawn, coder |
| Runtime tools | Available when the LLM or required context is available | plan_create, todo_update, image_generate, image_edit |
| Channel-specific tools | Available when the current channel is Telegram / Slack or another concrete channel runtime | send_voice, send_photo, send_file, message_react |
Static Tools
For how workspace_dir, file_cache_dir, and file_state_dir fit together, see Filesystem Roots.
Shell defaults are platform-specific:
- Linux/macOS:
bashenabled by default,powershelldisabled by default. - Windows:
powershellenabled by default,bashdisabled by default. - You can still override either one explicitly with
tools.<name>.enabled.
read_file
Reads local text files. The agent uses it to inspect config files, logs, cached results, SKILL.md, or state files.
- Key limits: subject to
tools.read_file.deny_paths; supportsfile_cache_dir/...andfile_state_dir/...aliases.
write_file
Writes local files in overwrite or append mode, for generated output, state updates, or saving downloaded results locally.
- Key limits: writes are restricted to
file_cache_dir/file_state_dir; relative paths default tofile_cache_dir; size is capped bytools.write_file.max_bytes.
bash
Executes local bash commands to call existing CLIs, run one-off conversions, execute scripts, or inspect the local environment.
- Key limits: restricted by
deny_pathsand internal deny-token rules; child processes inherit only an allowlisted environment. - Current isolated-execution behavior: accepts
run_in_subtask=trueand runs the command inside one direct boundary; when the current runtime exposes a stream sink, stdout/stderr chunks can appear in the preview stream before the command exits.
powershell
Executes local PowerShell commands. This is the Windows-oriented shell tool for calling existing CLIs, running scripts, and inspecting the local environment.
- Key limits: can be disabled via
tools.powershell.enabled; restricted bydeny_pathsand internal deny-token rules; child processes inherit only an allowlisted environment. - Current behavior: supports the same
file_cache_dir/file_state_diraliases asbash, including backslash path forms such asfile_cache_dir\foo.txt. - Current gap vs
bash: does not currently exposerun_in_subtask=true.
url_fetch
Makes HTTP(S) requests and returns the response, or downloads the response into a local cache file. Supports GET/POST/PUT/PATCH/DELETE, download_path, and auth_profile.
- Key limits: sensitive request headers are blocked; requests still pass through Guard network policy.
- Plain
GETrequests for allowlisted public post, shared-chat, article, and video URLs try Defuddle, then Jina Reader, then direct access. The allowlist covers X/Twitter posts andt.coshort links, Reddit posts, public ChatGPT/Claude/Gemini/Grok shares, LinkedIn/Threads posts, YouTube/Bilibili videos, and Medium/Substack articles. Requests with custom headers, authentication, a body, ordownload_pathremain direct.
web_search
Runs a web search and returns structured search results. Useful for discovering leads, candidate pages, and public information entry points.
- Key limits: it returns search-result summaries, not full page bodies; result count is capped by
tools.web_search.max_resultsand code-level limits.
contacts_send
Sends one outbound message to a single contact. Delivery is chosen from the contact profile, such as Telegram, Slack, or LINE.
- Key limits: some group/supergroup contexts hide this tool by default.
- Telegram text messages render Markdown (bold, italic, code, links), falling back to plain text if Telegram rejects the markup.
Engine Tools
These tools are registered when an agent engine is assembled for a run. They depend on the current engine state, so they are not part of the static base registry.
spawn
Starts a subagent with its own context and an explicit tool whitelist. The parent agent waits synchronously until the inner run finishes, then receives a structured JSON envelope.
- Key limits: can be disabled via
tools.spawn.enabled; the inner agent can use only the tool names passed intools; raw transcript is not returned to the parent loop by default. - Current observer hint:
spawnaccepts an optionalobserve_profileparameter.defaultkeeps mid-run previews conservative,long_shellis suited to long shell/log output, andweb_extractsuppresses raw noisy output until better stage signals exist.
For parameter details, result envelope fields, test prompts, and the difference from bash.run_in_subtask=true, see Subagents.
coder
Runs a coding subtask with the local Codex, Claude Code or Antigravity (agy) CLI. Each CLI runs as a session over stdio, one process that takes one task after another; what it reports while it works is forwarded as tool-output events before the final SubtaskResult envelope is returned. No terminal is involved and no CLI screen is read.
- Key limits: disabled by default via
tools.coder.enabled=false, but$codercan expose it for one task; only supportscoder=codex,coder=claudeorcoder=agy; runs local CLI processes with approval and permission prompts bypassed, except in the Console, where the sessions ask the user unlesstools.coder.bypass_approvals.codex,.claudeor.agyis true. A Console conversation keeps its sessions between tasks, so a later task can build on an earlier one; anywhere else a session lasts for one run. Outside the Console, a question the CLI itself asks fails the task with the question as its error. - Environment: the CLIs start in the
bashtool's environment (thepowershelltool's on Windows), not in the service's: its allowlisted variables plustools.bash.injected_env_vars, and nothing else. Proxy variables,CODEX_HOME,CLAUDE_CONFIG_DIRand provider keys reach them only when listed intools.bash.injected_env_vars(tools.powershell.injected_env_varson Windows). - PATH:
tools.coder.path_extra, thentools.bash.path_extra, then the service PATH, then, only whiletools.coder.path_extrais empty, the default install locations that exist (~/.local/bin,/opt/homebrew/bin,/usr/local/bin,/home/linuxbrew/.linuxbrew/bin; on Windows%USERPROFILE%\.local\bin,%LOCALAPPDATA%\Programs\OpenAI\Codex\binand%LOCALAPPDATA%\agy\bin). If the CLIs are somewhere else, settools.coder.path_extra. - Codex:
codex app-server(JSON-RPC over stdio). - Claude Code:
claude -p --input-format stream-json --output-format stream-json --verbose --include-partial-messages --permission-prompt-tool stdio --session-id <uuid>, with--permission-mode defaultin a Console session that asks and--dangerously-skip-permissionsotherwise; each task is one message on stdin. A closed session is reopened with--resume <uuid>. - Antigravity:
agy acp(ACP over stdio), with--dangerously-skip-permissionswhen approvals are bypassed.agymust be signed in first: runagyonce in a terminal and sign in. A task that meets a missing sign-in fails at once and says so.
The CLIs report startup, tool activity, and the remaining task time in Console progress. Codex reports command execution, file changes, MCP calls, and turn status; Claude reports initialization and tool activity; the Antigravity CLI reports each tool step with its name and what it runs, and its sub-agents. When Guard is enabled, progress shows status summaries with configured redaction; raw tool arguments, results, and stderr are withheld.
Chat channels (Telegram, Slack, Discord, LINE, Lark, Mixin, and the direct-message channels) cannot show that live progress, so a coder call that runs longer than 2 minutes posts a short status to the conversation, then another every 5 minutes until it finishes, such as "Claude Code is still working (12 min so far). Now: running a command." The status names only the kind of step, never commands, file paths, or output.
The CLI shares the parent task deadline; llm.request_timeout does not control it. No raw logs of a run are written. When a CLI's process dies, the error includes the end of what it wrote to stderr.
The CLI runs in its own process group, so cancellation also stops the commands it started. A task that is cancelled or fails closes the CLI's process; the next task of the same conversation reopens the session.
The result's usage field says what the run used and how much of the coder's subscription quota is left. The Antigravity CLI's quota is per model group (for example Gemini Models and Claude and GPT models), each with its own windows.
Use this for Codex / Claude Code / Antigravity CLI delegation.
Runtime Tools
These tools are injected dynamically while the agent is running.
plan_create
Generates structured execution-plan JSON, typically for complex task decomposition.
- Key limits: step count is capped by
tools.plan_create.max_steps.
todo_update
Maintains TODOs in file_state_dir/cron.yaml.
- Key limits: use
action=add_oncewithcontentandatto add a one-time TODO; useaction=add_recurringwithcontentand a five-field numericcronexpression to add a recurring TODO.titleis optional for new TODOs. Useaction=deleteto delete a TODO. Deletion prefersid; withoutid, it uses semantic matching oncontentand errors on no-match or ambiguous match. Optionalworkspace_dirsets the workspace the TODO runs in: an existing absolute path, orworkspace_dirfor the workspace attached to the current conversation. Optionalbash_envsets the TODO's bash environment as a list of{"name": ..., "value": ...}entries, the same form asbash_envin the TODO list. - Editing: use
action=updatewith the TODO'sidand only the fields to change (title,content,at,cron,tz,chat_id,workspace_dir,bash_env). Omitted fields keep their values and theidstays the same, so an edit never needs a delete and re-add. The change is applied in one transaction: an unknownidor a change that does not validate leaves the TODO as it was.contentis stored exactly as given. Settingatalone makes the TODO one-time and clears itscron; settingcronalone makes it recurring and clears itsat.""clearstz,chat_idorworkspace_dir(and resetstitleto the default);bash_env: []clears the bash environment, while omittingbash_envkeeps it. - Results list a TODO's
bash_envvariable names asbash_env_names, never their values.
todo_list
Lists every TODO, enabled and disabled, one-time and recurring. It is a static tool: it needs no LLM and stays available when tools.todo_update.enabled is off.
- Takes no parameters and always reads the agent's own TODO list.
- Returns
countandtasks([]when there are none). Each TODO has itsid,title,content, its schedule (atorcron, plustz), and anenabledboolean that is always present. - Read-only: it never changes or runs a TODO.
bash_envvalues are never returned, only their names asbash_env_names.
For the runtime workflow around TODOs and HEARTBEAT.md, see TODO and Heartbeat.
image_generate
Generates one image from a prompt and saves it under file_cache_dir or workspace_dir.
- Key limits: registered only when
tools.image_generate.enabled=true, an image model is configured, and the current task has explicit image intent. - Parameters:
promptis required.output_pathis optional, supportsworkspace_dir/...andfile_cache_dir/..., and relative paths resolve underfile_cache_dir/images/. - Output files are written as PNG or JPEG; the final extension is normalized to the returned MIME type.
image_edit
Edits one local image from a prompt and saves the result under file_cache_dir or workspace_dir.
- Key limits: registered only when
tools.image_edit.enabled=true, an image model is configured, and the current task has image-edit intent or retained image state. - Parameters:
promptis required. Useinput_path, or setuse_active_image=truewhen the current session has an active image.output_pathfollows the same rules asimage_generate. - Input images must be readable from
workspace_dirorfile_cache_dir, must be PNG or JPEG, and must be at most 20 MB.
Dedicated Tools
These tools do not exist in plain CLI or generic embedding scenarios. They are injected only when the corresponding channel runtime has enough context.
send_file
Sends a local file from file_cache_dir to the current chat: a document in Telegram, an upload in Slack, a file message in Lark, an attachment in Discord and Mixin, and a file (or image or video) in WeChat and WhatsApp.
- Key limits: only local cached files are allowed; directories are invalid; each channel's file-size cap applies.
send_photo
Sends a local image to the current Telegram, Lark or Mixin chat as an inline photo.
- Key limits: this is a photo-style send, not a document send; use
send_fileif the user should receive it as a file attachment.
send_voice
Sends a local audio file to the current Telegram, Lark or Mixin chat as a voice message.
- Key limits: only local-file sending is supported; files are typically expected under
file_cache_dir; Lark expects OPUS audio; this tool does not do text-to-speech.
message_react
Adds a lightweight emoji reaction to the current message, for cases like acknowledgement, approval, or a quick "seen" signal that does not justify a full text reply.
- Telegram variant: reacts to a Telegram message with an emoji and can optionally use large-reaction style.
- Slack variant: reacts to a Slack message using a Slack emoji name, not a raw Unicode emoji.
- Key limits: parameter shape differs by channel; without channel-specific message context, the tool may be absent or require explicit target parameters.
Tool Selection in Core Embedding
You can whitelist built-ins via integration.Config.BuiltinToolNames.
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "todo_update"}Empty list means all known built-ins.
Key Config Sections
tools:
read_file: ...
write_file: ...
spawn: ...
coder: ...
bash: ...
powershell: ...
url_fetch: ...
web_search: ...
contacts_send: ...
todo_update: ...
plan_create: ...Console Setup / Settings and the /api/settings/agent payload use the same nested shape, for example tools.spawn.enabled and tools.coder.enabled.
For the full configuration, see Config Reference.