Skip to content

Built-in Tools

Static tools, runtime-injected tools, and channel-specific tools.

Built-in Tools ​

Mistermorph does not register every tool as one flat bundle. Tools are layered by runtime environment:

  1. Static tools: created from config and directory context alone.
  2. Engine tools: registered when an agent engine is assembled for a run.
  3. Runtime tools: require an active LLM client/model or task context.
  4. Dedicated tools: only appear inside concrete runtimes such as Telegram or Slack.

Tool Groups at a Glance ​

GroupWhen availableTools
Static toolsAvailable from config aloneread_file, write_file, bash, powershell, url_fetch, web_search, contacts_send, todo_list
Engine toolsAvailable when an agent engine is assembled for a runspawn, coder
Runtime toolsAvailable when the LLM or required context is availableplan_create, todo_update, image_generate, image_edit
Channel-specific toolsAvailable when the current channel is Telegram / Slack or another concrete channel runtimesend_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: bash enabled by default, powershell disabled by default.
  • Windows: powershell enabled by default, bash disabled 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; supports file_cache_dir/... and file_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 to file_cache_dir; size is capped by tools.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_paths and internal deny-token rules; child processes inherit only an allowlisted environment.
  • Current isolated-execution behavior: accepts run_in_subtask=true and 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 by deny_paths and internal deny-token rules; child processes inherit only an allowlisted environment.
  • Current behavior: supports the same file_cache_dir / file_state_dir aliases as bash, including backslash path forms such as file_cache_dir\foo.txt.
  • Current gap vs bash: does not currently expose run_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 GET requests for allowlisted public post, shared-chat, article, and video URLs try Defuddle, then Jina Reader, then direct access. The allowlist covers X/Twitter posts and t.co short 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, or download_path remain direct.

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_results and 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 in tools; raw transcript is not returned to the parent loop by default.
  • Current observer hint: spawn accepts an optional observe_profile parameter. default keeps mid-run previews conservative, long_shell is suited to long shell/log output, and web_extract suppresses 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 $coder can expose it for one task; only supports coder=codex, coder=claude or coder=agy; runs local CLI processes with approval and permission prompts bypassed, except in the Console, where the sessions ask the user unless tools.coder.bypass_approvals.codex, .claude or .agy is 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 bash tool's environment (the powershell tool's on Windows), not in the service's: its allowlisted variables plus tools.bash.injected_env_vars, and nothing else. Proxy variables, CODEX_HOME, CLAUDE_CONFIG_DIR and provider keys reach them only when listed in tools.bash.injected_env_vars (tools.powershell.injected_env_vars on Windows).
  • PATH: tools.coder.path_extra, then tools.bash.path_extra, then the service PATH, then, only while tools.coder.path_extra is 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\bin and %LOCALAPPDATA%\agy\bin). If the CLIs are somewhere else, set tools.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 default in a Console session that asks and --dangerously-skip-permissions otherwise; each task is one message on stdin. A closed session is reopened with --resume <uuid>.
  • Antigravity: agy acp (ACP over stdio), with --dangerously-skip-permissions when approvals are bypassed. agy must be signed in first: run agy once 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_once with content and at to add a one-time TODO; use action=add_recurring with content and a five-field numeric cron expression to add a recurring TODO. title is optional for new TODOs. Use action=delete to delete a TODO. Deletion prefers id; without id, it uses semantic matching on content and errors on no-match or ambiguous match. Optional workspace_dir sets the workspace the TODO runs in: an existing absolute path, or workspace_dir for the workspace attached to the current conversation. Optional bash_env sets the TODO's bash environment as a list of {"name": ..., "value": ...} entries, the same form as bash_env in the TODO list.
  • Editing: use action=update with the TODO's id and only the fields to change (title, content, at, cron, tz, chat_id, workspace_dir, bash_env). Omitted fields keep their values and the id stays the same, so an edit never needs a delete and re-add. The change is applied in one transaction: an unknown id or a change that does not validate leaves the TODO as it was. content is stored exactly as given. Setting at alone makes the TODO one-time and clears its cron; setting cron alone makes it recurring and clears its at. "" clears tz, chat_id or workspace_dir (and resets title to the default); bash_env: [] clears the bash environment, while omitting bash_env keeps it.
  • Results list a TODO's bash_env variable names as bash_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 count and tasks ([] when there are none). Each TODO has its id, title, content, its schedule (at or cron, plus tz), and an enabled boolean that is always present.
  • Read-only: it never changes or runs a TODO. bash_env values are never returned, only their names as bash_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: prompt is required. output_path is optional, supports workspace_dir/... and file_cache_dir/..., and relative paths resolve under file_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: prompt is required. Use input_path, or set use_active_image=true when the current session has an active image. output_path follows the same rules as image_generate.
  • Input images must be readable from workspace_dir or file_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_file if 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.

go
cfg.BuiltinToolNames = []string{"read_file", "url_fetch", "todo_update"}

Empty list means all known built-ins.

Key Config Sections ​

yaml
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.